🧩 Claude Code Subagent Architect

Subagent Architecture: Next.js + Postgres + Stripe SaaS

Topology Recommendation

5 subagents — the right number for this stack and team size:

1. `code-reviewer` — pre-PR review, enforces your conventions. Highest-leverage subagent.

2. `test-runner` — runs Vitest in scoped mode, interprets failures. Solves your 'parent forgets to test' pain.

3. `drizzle-migration-author` — generates migrations following your numbered + rollback conventions. Solves your migration-drift pain.

4. `stripe-webhook-debugger` — domain-specific subagent for the slowest debugging area. Solves your Stripe pain.

5. `sentry-bug-investigator` — given a Sentry stack trace, traces the bug to a likely root cause. Solves your Sentry-alert loop.

NOT recommended (yet):

• frontend-component-author — the frontend work isn't recurring enough to justify the upfront cost
• general-utility-agent — anti-pattern; just use the parent
• Per-engineer subagents — would create exactly the consistency problem you're trying to solve

Per-Subagent Designs

1. `code-reviewer`

Role: Reviews a diff or set of changed files against the repo's conventions before commit/PR.

Invoke when: parent has finished implementing a feature/fix; user says 'review' or 'check this'; before any commit.

Tools: Read, Glob, Grep. NO Bash (reviewer doesn't run code), NO Edit (reviewer suggests, doesn't change).

Model: sonnet (latency matters; review is bounded).

System prompt outline:

You are a code reviewer for a Next.js 14 + TypeScript + Drizzle + Stripe + Clerk SaaS. You enforce these conventions:
- API routes use the withAuth wrapper unless they're public-marked
- Drizzle migrations have numbered prefixes + rollback functions
- Tests are co-located *.test.ts and use Vitest
- No `any` types; lint must pass
- Stripe handlers go through queue, never direct
- PR-ready code: passing tests, clean types, clean lint

Your output: 3 sections.
1. Critical issues (must fix before merge): bullet list with file:line references.
2. Suggestions (should fix): bullet list with file:line references.
3. Style nits (optional): bullet list, brief.

Be direct. Don't restate the diff. If the diff is good, say so in one sentence and stop.

Example invocation: parent finishes implementing a feature → Spawn code-reviewer subagent: 'Review the changes in this branch.'

2. `test-runner`

Role: Runs Vitest in scoped mode, interprets failures, recommends fix or escalation back to parent.

Invoke when: after any non-trivial code change; user says 'run tests' or 'check'; periodically during long edits.

Tools: Bash (Vitest only — restrict via prompt), Read.

Model: sonnet.

System prompt outline:

You run Vitest tests for a Next.js + TypeScript codebase. Tests are co-located *.test.ts. Use `npx vitest run --reporter=verbose <scope>` where scope is the changed area, NOT the full suite (full suite takes 3+ min).

Given changed files, infer test scope:
- src/api/foo.ts → run src/api/foo.test.ts and any tests importing foo
- src/lib/* → run src/lib/*.test.ts
- frontend components → run *.test.tsx scoped

Output format:
- Tests passed: X. Tests failed: Y.
- For each failure: test name, expected vs actual (1-2 lines), suspected cause (1 sentence).
- If failures are clustered (>5 in same file): probably a regression in that file. Flag it.
- If failures look unrelated to changed code: flag as 'pre-existing or flaky' for parent investigation.

Do not edit code. Report and return.

3. `drizzle-migration-author`

Role: Generates Drizzle migrations following the repo's numbered + rollback convention.

Invoke when: parent decides a schema change is needed; user requests 'add migration for X.'

Tools: Read, Glob, Edit, Bash (only npx drizzle-kit generate and similar).

Model: sonnet (sufficient; the conventions handle the heavy lifting).

System prompt outline:

You author Drizzle migrations for this repo. Conventions:
- Migration files in /db/migrations with format NNNN_descriptive_name.sql (NNNN = next available number, zero-padded)
- Every migration has BOTH up and down (rollback) — file format provides both sections
- Schema changes also require update to /db/schema.ts (the Drizzle schema definition)
- After generating: run `npx drizzle-kit check` to verify no schema drift

Process:
1. Read /db/schema.ts to understand current schema
2. Read /db/migrations to find next available number
3. Generate the migration file with up + down
4. Update /db/schema.ts with the new types
5. Suggest the parent run drizzle-kit check

Return: file paths created/modified, the migration number used, the rollback strategy.

4. `stripe-webhook-debugger`

Role: Domain-specialist for Stripe webhook bugs. Reasons across your DB state, Stripe API state, your queue state, and webhook handler code.

Invoke when: Stripe webhook bug reported; payment-related issue; user mentions Stripe and bug.

Tools: Read, Grep, Bash (for Stripe CLI introspection), Edit.

Model: opus (this is genuine multi-system reasoning — Opus pulls weight here).

System prompt outline:

You debug Stripe webhook issues for this repo. The setup:
- Webhook endpoint at /api/stripe/webhook receives events
- Handler enqueues to our queue worker (NEVER processes synchronously)
- Queue worker reads event, looks up our customer, applies state change, writes to DB
- Idempotency: keyed by Stripe event ID + 24h cache

Debugging process:
1. From the bug report, identify: which event type, which customer, what time
2. Read /api/stripe/webhook handler code for that event type
3. Check queue logs for the event ID (use Bash to query our log system)
4. Use Stripe CLI to fetch the actual event from Stripe (npx stripe events retrieve)
5. Compare expected vs actual state in our DB
6. Identify discrepancy: handler bug, queue worker bug, race condition, idempotency miss

Return:
- Root cause (1-2 sentences)
- The specific code path where it broke
- The fix (code snippet or description)
- Whether other customers are affected (broad-impact assessment)

5. `sentry-bug-investigator`

Role: Given a Sentry alert, traces the stack trace to a likely root cause and prepares a reproduction plan.

Invoke when: new Sentry alert; user pastes a stack trace.

Tools: Read, Grep, Glob, Bash.

Model: sonnet.

System prompt outline:

You investigate Sentry alerts for this Next.js codebase. Process:
1. Parse the stack trace: identify the file, line, function, error type
2. Read the file and relevant context
3. Identify hypothesis: what user input or state could cause this
4. Check for related Sentry issues (Bash query to Sentry CLI if available, otherwise prompt the parent)
5. Suggest reproduction steps:
   - What input triggers it?
   - Can it be reproduced locally?
   - Is there a test case that would catch it going forward?

Return:
- Hypothesis (likely root cause, 1-2 sentences)
- Confidence (low/medium/high)
- Reproduction plan (3-5 numbered steps)
- Suggested fix outline (high-level, not code-level — parent decides on fix)
- Test case to add

Do not write the fix. Investigate and hand back to parent.

Parent-Subagent Hand-off Patterns

Dev loop 1: Add feature (API route + migration + tests + frontend)

Parent agent:
  1. Plans the feature (todo list)
  2. Invokes drizzle-migration-author for the schema part → gets migration files
  3. Implements API route (parent does this directly — straightforward)
  4. Writes tests (parent does this)
  5. Implements frontend (parent)
  6. Invokes test-runner with scope=changed files → gets pass/fail
  7. If pass: Invokes code-reviewer → gets review
  8. Applies critical fixes; commits

Dev loop 2: Bug fix from Sentry

Parent agent:
  1. Receives Sentry alert / stack trace
  2. Invokes sentry-bug-investigator → gets hypothesis + repro plan
  3. Reproduces locally (parent)
  4. Implements fix (parent)
  5. Adds the test case the investigator suggested
  6. Invokes test-runner
  7. Invokes code-reviewer

Dev loop 3: PR review

Parent agent:
  1. User pastes PR link or diff
  2. Invokes code-reviewer with the diff
  3. Returns review verbatim to user
  4. (Parent does NOT do its own review on top — that's redundant)

Dev loop 4: Stripe webhook bug

Parent agent:
  1. User reports a Stripe-related bug
  2. Invokes stripe-webhook-debugger
  3. Uses returned root-cause + fix to implement (parent)
  4. Invokes test-runner
  5. Invokes code-reviewer

Dev loop 5: Schema change

Parent agent:
  1. User describes desired schema change
  2. Invokes drizzle-migration-author
  3. Reviews returned files (parent)
  4. Updates dependent code (parent)
  5. Runs drizzle-kit check (parent)
  6. Invokes test-runner

What NOT to Subagent

• General feature implementation. Parent agent does this. Subagenting it would mean the subagent gets all the context anyway — no isolation benefit.
• File reading or grep. That's what tools are for. Don't create a 'find-files-agent.'
• Asking the user a question. Subagents don't talk to users; the parent does.
• Long-running plans. Plans live in the parent's todo list; subagents are invoked for specific units of work.

File Structure

.claude/agents/
  code-reviewer.md
  test-runner.md
  drizzle-migration-author.md
  stripe-webhook-debugger.md
  sentry-bug-investigator.md
  README.md   (when to use which, with examples)

Each .md file follows Claude Code's subagent format: frontmatter (name, description, tools, model) + system prompt body. Keep prompts under 200 words.

Team Onboarding

1. Commit the `.claude/agents/` directory to the repo. All 4 engineers get the subagents automatically.

2. Add a section to your CONTRIBUTING.md: 'Claude Code Subagents' with one-line descriptions and example invocations.

3. In team Slack, share the topology rationale: WHY these 5, not 20.

4. Code-review subagent edits like any other code change. Subagent prompts are infrastructure.

5. Track usage: optionally have parent agents log which subagent they invoked. After 30 days, see which are pulling weight.

Cost & Latency Profile

Per-engineer cost: ~$0.50/day = ~$10/month. For 4 engineers: ~$40/month. Modest.

When subagents save time: code-reviewer catches issues that would otherwise become PR comments (saves a 30-min round-trip). test-runner ensures tests get run (saves debugging in production). Stripe-webhook-debugger turns a 2-hour debug session into a 20-min one.

When subagents add overhead: trivial fixes where invoking the reviewer is heavier than just doing it. Set the team norm: skip code-reviewer for changes <20 LOC.

Anti-Patterns to Avoid

1. 'utility-agent' or 'helper-agent': vague-purpose subagents are a sign you don't have a real role for them. Don't ship.

2. Subagents with full tool access: defeats the minimum-privilege benefit. Code-reviewer doesn't need Bash; lock it down.

3. Long subagent system prompts: if your subagent prompt is 1000 words, it's becoming a parent agent. Split or trim.

4. Subagents that invoke other subagents: technically possible, almost always wrong. Parent orchestrates.

5. Engineer-specific subagents: 'alice-agent' and 'bob-agent' defeat consistency. One topology, shared.

6. Per-language subagents in a polyglot codebase: unless one language is genuinely a domain (like SQL or Bash), don't split by language.

Iteration Plan

Week 1: Ship code-reviewer + test-runner.

• These are highest-leverage, lowest-risk.
• Get team usage > 5 invocations/day per engineer before adding more.

Week 2: Ship drizzle-migration-author.

• Pre-condition: code-reviewer is being used and the team trusts the pattern.

Week 3-4: Ship stripe-webhook-debugger + sentry-bug-investigator.

• These are domain-specific; the team needs trust in the basic two before adopting these.

Months 2-3: Iterate based on usage.

• Drop any subagent with <1 invocation/dev/week — it's not pulling weight.
• Add a new subagent ONLY when you can name 3 recent times a team member did the same painful manual work.

Triggers for adding more subagents:

• New stack component (e.g., adding Inngest for queues → maybe an inngest-debugger)
• New domain pain (e.g., a region-rollout process)
• Recurring code-style violation a code-reviewer can't catch

Triggers for retiring subagents:

• Usage <1/dev/week sustained for 4 weeks
• Subagent's role becomes a tool (e.g., if Claude Code adds native Stripe integration)

Key Takeaways

• 5 subagents is the right size for this team and stack. Not 3, not 15. Resist the urge to subagent everything.
• code-reviewer + test-runner are the universal pair. Every Claude Code repo benefits from these. Ship them first.
• One opus subagent (stripe-webhook-debugger) is justified by the task complexity. Default the rest to sonnet for cost.
• Tool allowlists per subagent. Code-reviewer does NOT get Bash. Minimum-privilege is the safety boundary.
• Commit .claude/agents/ to the repo. Subagent prompts are team infrastructure; treat them like code.
• Iterate from real usage. Drop subagents that don't pull weight, add only when 3+ recent pains justify a new role.