Community Use Cases

— Real AI workflows with problem, steps, tools, and outcomes.

Inputs Needed

Claude Code desktop app installed on macOS or Windows (Agent Teams and parallel Git worktrees are not available on Linux — use CLI with sequential worktrees instead); CLAUDE.md file written, reviewed, and committed to repository root before starting; GitHub fine-grained PAT with pull_requests:write and contents:write scopes set to 2-hour expiry; MCP v2.1 configured with read/write database credentials scoped to feature-specific tables only (never admin privileges); existing test suite with at least 60% coverage before any agentic work; clean Git state (no uncommitted changes) before the lead agent starts

Quality Check

Before approving the PR, review the interface contract file (types/[feature_name]-contract.ts or equivalent) first — this file is where sub-agent assumptions surface and is the most common source of post-merge failures. Then review each workstream diff independently before reviewing the merged result. Run the integration test suite on a clean database seed, not your development database. Confirm no workstream modified files outside its designated scope (this should be caught by the lead agent but verify independently). Finally, check the NEVER DO section of your CLAUDE.md and confirm none of those operations were performed.

Limits / Watchouts

Agent Teams and Git worktrees require the Claude Code desktop app — not available on Linux; Linux users must run sub-agents sequentially in separate terminal sessions. The /loop feature must never be configured to run autonomously on migrations, authentication code, or billing logic — documented production incidents exist from loops that entered infinite regression cycles on these sensitive operations. Token consumption scales linearly with parallel sub-agents: 4 parallel agents consume approximately 4x the tokens of a single session; monitor usage on Pro plans. Sub-agents do not share live memory — the interface contract file pattern in Step 5 is not optional; skip it and sub-agents will make incompatible assumptions about the API shape. The CLAUDE.md file is the single most important prerequisite: running this workflow without a well-structured CLAUDE.md produces unpredictable results; running it with a mature CLAUDE.md consistently delivers production-quality features.

Additional Notes

Stack: Claude Code desktop app (4 parallel sessions, each auto-creating its own Git worktree), CLAUDE.md (standing architecture instructions), /loop slash command (automated test cycle), MCP v2.1 (scoped database access), GitHub fine-grained PAT (PR creation). Key correction most tutorials get wrong: "Agent Teams" in Claude Code means you open parallel sessions in the desktop app and direct each one — you are the human orchestrator. Fully automated lead-agent-spawns-sub-agents orchestration requires writing an Agent SDK coordinator script (TypeScript or Python). For most teams, 4 manual parallel sessions is faster to set up, easier to monitor, and produces better results than automated orchestration on the first few runs. The CLAUDE.md is not configuration — it is the architectural briefing you would give a new senior engineer on their first day. Treat it that way.

The Problem

Shipping a full feature — schema change, API route, frontend component, tests, documentation — sequentially takes 1–2 days even for experienced engineers. The bottleneck is not skill; it is the sequential nature of the work. Backend must exist before the frontend can consume it, tests must be written after the implementation, documentation comes last. Claude Code's Agent Teams break this sequence entirely: all four workstreams run in parallel in isolated Git worktrees, coordinated by a lead agent that manages dependencies and merges results. For senior engineers, the bottleneck shifts from implementation speed to architectural judgment — which is exactly where human expertise should be focused.

Workflow Steps

Build a production-quality CLAUDE.md architecture file at your repository root before any agentic work. This is the highest-leverage investment in Claude Code productivity — every hour spent here pays compound returns across every future feature. Include: project purpose (2–3 sentences), directory structure with what each top-level folder contains, tech stack with exact versions, coding conventions (naming patterns, file structure rules, import ordering), testing requirements (minimum coverage, test naming convention, which test runner), and a NEVER DO section listing operations Claude must not perform without explicit human confirmation: database migrations, modifications to .env or secrets, pushes to main, changes to authentication middleware

Configure short-lived scoped credentials: never give Claude Code your full-privilege credentials. For MCP v2.1 database access, generate a read/write role scoped only to the tables the specific feature touches — never admin, DBA, or migration privileges. For GitHub, create a fine-grained PAT scoped to the single repository with only pull_requests:write and contents:write permissions. Set token expiry to 2 hours. Rotate after the session. Document this rotation in your CLAUDE.md under Security Practices

Write a structured task brief before opening any sessions: write your task brief as a text file before opening Claude Code. Include the full GitHub issue text, acceptance criteria, the exact files expected to change as the scope boundary, and the 4 workstream assignments with their dependencies made explicit. Writing this offline prevents you from making decisions mid-session under time pressure. Save it as task-brief.md at your project root — you will paste sections of it into each session

Open 4 parallel sessions in the Claude Code desktop app — one per workstream: Claude Code's desktop app creates an isolated Git worktree automatically for each new session opened in the same repository. Open the desktop app, open your project, then open 4 sessions using the new session button. You are the human orchestrator directing each session — there is no automatic "lead agent spawns sub-agents" behavior without the Agent SDK. In each session, paste the relevant workstream section from your task-brief.md. Label each session clearly in the sidebar: WS1-Database, WS2-Backend, WS3-Frontend, WS4-Tests. If you want fully automated orchestration, use the Claude Code Agent SDK (TypeScript/Python) to write a coordinator script — but for most teams, manually directing 4 parallel sessions is faster to set up and easier to monitor

Prompt Example

Write this task brief as task-brief.md before opening any Claude Code sessions: --- FEATURE: [FEATURE NAME FROM GITHUB ISSUE #N] GITHUB ISSUE: [PASTE COMPLETE ISSUE TEXT] ACCEPTANCE CRITERIA: [LIST EACH CRITERION EXPLICITLY] SCOPE BOUNDARY — do not modify files outside this list without asking: [LIST FILES AND DIRECTORIES] WORKSTREAM ASSIGNMENTS: WS1 — Database (open this session first): Write schema migration file for [TABLE CHANGES]. File location: db/migrations/[timestamp]_[feature_name].sql DO NOT run the migration. Write the file only. Commit the file when done. WS2 — Backend API: Implement route at [METHOD] [PATH]. Include input validation, error handling, and typed response shape. When complete: write the full API contract (request + response types) to shared/[feature-name]-contract.ts and commit it. Tell me when the contract file is committed. WS3 — Frontend (do not start fetch implementation until WS2 contract is provided): Implement component at [FILE PATH]. Wait for the API contract — I will paste it into this session from WS2. Once you receive the contract, use it as the sole source of truth for all type definitions and fetch calls. WS4 — Tests and Docs: Write unit tests for the API route and one integration test for the full request-response flow. Update the README section for [FEATURE AREA]. When initial tests are written, I will activate /loop — wait for my instruction. NEVER DO (in any workstream): - Run database migrations - Modify .env or any secrets file - Push to main branch - Modify authentication middleware --- Paste the relevant workstream section into each of the 4 Claude Code desktop app sessions.

Community Use Cases

Community Use Cases

Orchestrate a Claude Code Agent Team to Deliver a Complete Feature From GitHub Issue to Merged PR

Outcome

Related Workflows

Inputs Needed

Quality Check

Limits / Watchouts

Additional Notes

The Problem

Workflow Steps

Prompt Example

Find Related Workflows