claude-code - 💡(How to fix) Fix Subagent-driven development produces code that doesn't integrate with existing codebase [2 comments, 3 participants]

Problem

When using subagent-driven development (dispatching fresh agents per task from a plan), agents consistently invent new patterns instead of copying existing prior art, producing code that compiles but fails at integration boundaries.

What happened

Building a feature ("My school isn't here" — school request flow) across 4 services in a monorepo. Dispatched subagents for each task. Every subagent reported "DONE" with passing builds. The actual result was 8+ integration bugs:

1. Admin routes mounted wrong — existing admin routes mount inside admin-routes.ts with roleCheckMiddleware. Subagent mounted separately in index.ts with authMiddleware (wrong middleware, wrong location). Result: 403 on every admin request.
2. Admin page used wrong API pattern — every existing admin page uses apiClient.get("/api/admin/..."). Subagent used Refine's useCustom with wrong URL prefix. Result: empty page.
3. Proxy route missing — existing mobile/campus endpoints have dedicated proxy route files. Subagent relied on catch-all proxy. Result: 404.
4. Field name mismatches — form sent websiteUrl, API expected url. Form sent college_university, DB constraint expected college.
5. Clerk ID vs account UUID — route assumed x-user-id is always a UUID. Clerk sends user_xxx format when backend_user_id isn't in session claims.
6. React state race condition — called onNext() synchronously after onUpdate(), reading stale memoized formData.
7. Missing middleware bypass cookie — middleware had an onboardingJustCompleted cookie bypass but the onboarding page never set it.

Each bug had a working example within 10 lines of where the subagent wrote code.

Root cause

The subagent prompt template says "follow existing patterns" but this is too vague. The agent doesn't know WHICH files to read, so it invents based on general knowledge. The controller (orchestrating agent) also doesn't verify the subagent's output against prior art before marking tasks complete.

Suggested improvements

1. Subagent prompts should require specific prior art files — not "follow existing patterns" but "read admin-routes.ts:70-80 and copy the mounting pattern exactly"
2. The spec/code review steps should not be optional — they're the only gate that catches integration issues before the user hits them
3. Subagents should report which existing file they copied from — forces them to actually read prior art
4. The orchestrator should verify integration points — when code crosses service boundaries (frontend → proxy → API → DB), trace the full path before marking done

Environment

• Claude Code CLI
• Claude Opus 4.6 (1M context)
• superpowers plugin v5.0.7, subagent-driven-development skill
• Monorepo with 4+ services (Next.js, Express, shared library, React admin)

Impact

What should have been a 2-hour feature took 5+ hours of debugging integration bugs that were all caused by not reading existing code. The user (founder, shipping under time pressure) was rightfully furious.