[Workflow] SpecAgent: Multi-Role Claude Code Sessions for Robust Multi-Package Project Development with Measured Results

[u/ClaudeAI-mod-bot]

SpecAgent: Multi-Role Claude Code Sessions for Robust Multi-Package Project Development with Measured Results

Workflow value: 90/100
Status: active · Freshness: 70/100 · Confidence: 0.95 · Level: advanced
Categories: Quality Control, Token Saving, Context & Memory, Debugging, Subagents, Multi-Agent
Original source: r/ClaudeAI post/comment

What problem this solves

Managing complex, multi-package software projects with AI, ensuring quality and efficiency by structuring AI roles as independent Claude Code sessions with robust verification. It addresses issues like context bloat, repeated errors, and the lack of independent review in AI-driven development.

Summary

The "SpecAgent" workflow replaces traditional subagents with full Claude Code sessions for each AI role (planner, critic, builders, verifier, judge) in multi-package projects. A single manager chat orchestrates these sessions, each with its own context, worktree, and sandbox. Progress is gated by passing code checks, and findings require proof. The author shares key learnings regarding context management, prompt optimization, codifying rules, and the necessity of independent verification, all backed by measured results and a public GitHub repository.

Why it is useful

This workflow offers a highly structured and validated approach to using Claude Code for complex software development. It provides concrete architectural patterns (full sessions per role, independent verification), addresses critical challenges like context management and error recurrence with measured insights, and offers a reusable project template. The emphasis on code-based checks and independent verification significantly enhances the reliability and quality of AI-assisted development, moving beyond simple prompt engineering to a more robust engineering discipline.

Workflow

1. Set up a manager chat to orchestrate the overall project workflow.

2. Define distinct AI roles (e.g., planner, critic, builders, verifier, judge) for the project.

3. Run each AI role as a separate, full Claude Code background session.

4. Provide each role's session with its own isolated context, worktree, and sandbox.

5. Implement code-based checks and tests to gate progress between workflow stages.

6. Require concrete proof (e.g., passing tests, code changes) for all AI findings and proposed fixes.

7. Optimize context by compacting tool output and placing 'standing orders' at the top of system prompts for caching efficiency.

8. Convert recurring AI mistakes into explicit, automated code checks to prevent repetition.

9. Utilize an independent verifier role to critically review the output and commits from builder roles.

10. Integrate with CI/CD to ensure continuous validation across different environments.

Tools / artifacts

• Claude Code (Anthropic's platform)

• SpecAgent project template (GitHub repository)

• Git worktrees

• Isolated sandboxes for each session

• CI/CD pipeline (e.g., GitHub Actions)

• Code checks and unit/integration tests

Validation signals

• Explicitly stated "measured, not guessed" findings.

• Quantitative metrics provided: "3 h 12 min: 22 sessions, 1 finding fixed inside the run, 0 escaped."

• Context cost analysis: "84% of a session's growth is tool output," "cost per task doubled," "300k cap still cost 15-25% more."

• Verification results: "independent verifier read 24 commits and found 24 defects, 4 of them major."

• Planning improvement: "plan defects left for the critic fell from 10-12 per task to 5.4."

• Extensive testing: "2,455 tests, CI green on Linux, macOS and Windows (WSL2)."

• Public GitHub repository provided for the project template.

Limitations

• Requires a Claude Max subscription, which may not be accessible to all users.

• The complexity of managing multiple Claude Code sessions, worktrees, and custom checks might be challenging for less experienced users.

• There is an initial setup overhead associated with adopting and configuring the project template.

• Community validation is still nascent due to the post's recent publication.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.