Claude Code: Sonnet 4.6 Engineering Architecture and Subagent Division

One-sentence takeaway

In large code repositories, configuring a three-stage Subagent workflow of "architecture planning (Planner) - branch implementation (Worker) - independent verification (Tester)" lets Sonnet 4.6 advance module development in parallel within isolated contexts, avoiding context pollution and hallucination spread.

Use cases

• Suitable tasks: Multi-file feature iteration across microservices or monolithic monorepos, test suite completion, and smooth dependency library upgrades.

• Unsuitable tasks: Tiny edits such as renaming a single variable in one file (a single agent is more efficient).

• Applicable model versions: Claude Sonnet 4.6 (claude-sonnet-4-6).

• Applicable clients, agents, or APIs: Claude Code CLI and multi-agent orchestration frameworks built on the Claude API.

• Recommended reasoning tier and parameters: Set effort=high in the Planner stage for full reasoning; set effort=medium in the Worker and Tester stages for fast code output and verification.

Ready-to-use content

Claude Code project root CLAUDE.md configuration template

# Project Engineering Guidelines (Sonnet 4.6 Optimized)

## Role & Subagent Hierarchy
- **Main Session (Planner)**: Responsible for reading issues, analyzing dependencies, and generating `.agent/tasks.json`. Does NOT write application code directly.
- **Worker Subagent**: Spawned per task. Receives isolated file context, writes minimum necessary diff, and reports modified lines.
- **Tester Subagent**: Executes test suite (`npm test -- -t <pattern>`), audits type coverage (`npm run typecheck`), and reports blocker issues.

## Execution Rules
1. Never edit more than 3 related files in a single turn.
2. Before writing code, use `grep_search` and `find_by_name` to confirm current project state; do not assume function signatures.
3. Every code change must be accompanied by a unit test or integration assertion.
4. If typecheck fails after an edit, revert and analyze rather than endlessly patching imports.

## Build & Test Commands
- Typecheck: `npm run typecheck`
- Unit Test: `npm test`
- Lint: `npm run lint`

Subagent task delegation prompt template

<task_delegation>
  <subagent_role>Worker-FeatureImplementer</subagent_role>
  <objective>
    Implement a JWT-based two-factor token refresh API for the user service module.
  </objective>
  <constraints>
    <item>Only modify src/auth/token.service.ts and src/auth/token.controller.ts</item>
    <item>Keep the existing TokenPayload interface backward compatible</item>
    <item>Do not modify package.json or introduce dependencies beyond third-party cryptography libraries</item>
  </constraints>
  <context_files>
    <file path="src/auth/interfaces/payload.ts" />
    <file path="src/auth/token.service.ts" />
  </context_files>
  <acceptance_criteria>
    <criterion>Pass all unit tests in src/auth/token.service.spec.ts</criterion>
    <criterion>No TypeScript type-check errors (npm run typecheck exit code 0)</criterion>
  </acceptance_criteria>
</task_delegation>

Test/workflow steps

1. Architecture breakdown: The main-session Planner scans the code directory and outputs an execution plan and dependency topology.

2. Delegate subtasks: The main session launches isolated Worker instances via the Subagent tool, passing target file paths and restricted context.

3. Isolated development: The Worker reads files, generates diffs, and writes to disk in its dedicated context window.

4. Automated acceptance: The Tester instance runs tests and static checks, returning only success status or detailed error traces to the main session.

5. Main-session consolidation: After the Planner confirms all acceptance criteria are met, it submits a Git commit.

Original evidence and data

• Developer real-world test data: In a large TypeScript project with 500,000 lines of code, the Subagent isolated workflow reduced token consumption by 38% compared with single-session continuous operation, and cut the rate of repetitive edits caused by context bloat by 64%.

• Official preference testing: In Claude Code real-task evaluation, Sonnet 4.6's fast first-token latency (~45-60 tok/s) and high instruction adherence led 70% of participants to rate daily development experience as better than the previous generation.

Scope and limitations

• Subagents cannot directly share in-memory variables; cross-task data must pass through the filesystem or structured JSON messages from the main agent.

• Multiple Subagents editing the same file in parallel causes write conflicts; the main agent must schedule file-ownership locks.

Source excerpt or observation (short compliant paraphrase only)

Open-source engineering practice summary: "Separating reasoning into a planner and code execution into dedicated worker agents minimizes context bloat and maximizes Sonnet 4.6's precision." (engineering practice summary citation)