diff options
| -rw-r--r-- | claude-rules/subagents.md | 126 | ||||
| -rw-r--r-- | debug/SKILL.md | 2 | ||||
| -rw-r--r-- | finish-branch/SKILL.md | 2 | ||||
| -rw-r--r-- | review-code/SKILL.md | 2 |
4 files changed, 132 insertions, 0 deletions
diff --git a/claude-rules/subagents.md b/claude-rules/subagents.md new file mode 100644 index 0000000..310f979 --- /dev/null +++ b/claude-rules/subagents.md @@ -0,0 +1,126 @@ +# Subagents — When, How, and When Not To + +Applies to: `**/*` + +Subagents exist to protect the main thread's context and parallelize +independent work. They are not free — every spawn pays a prompt-construction +cost and breaks the chain of context from the current conversation. Use them +deliberately, not reflexively. + +## When to Spawn a Subagent + +### Parallel-safe (spawn multiple in parallel) + +- **Read-only investigation across independent domains** — "what uses + function X?", "what are the three logging libraries in this repo?", etc. + spread across different subsystems. +- **N independent test-file failures** where each is its own diagnosis. +- **Library/API research across unrelated topics** — doc fan-out. +- **Analysis scans over different parts of a codebase** — e.g. C4 diagram + generation scanning distinct services. + +### Sequential-with-review (one at a time, review between) + +- **Plan-task execution** where each task may depend on the last. +- **Coupled edits** — related files that must stay in sync (schema + migration + + seed script). +- **Anything where mid-course correction is likely** — the review gate is + where course correction happens. + +### Never Parallel + +- **Concurrent writes to the same files or directories** — race conditions, + conflicting edits, lost work. +- **Ordered edits where sequence matters** — e.g. add a config flag, then + read it in code; don't fan these out. + +### Don't Subagent At All + +- **The target is already known** and the work fits in under ~10 tool calls. +- **Single-function logic** — one Read + one Edit is faster than briefing + an agent. +- **You can see the answer from context** — don't spawn a researcher for + something already on screen. + +## Prompt Contract + +Every Agent spawn must include four fields. Missing any one produces +shallow, generic work: + +1. **Scope** — one bounded task, named file or domain. Not "fix the bugs" + but "find the root cause of the NPE in `order_service.py:process_refund`." +2. **Context** — paste the relevant output, error, or prior finding. The + subagent cannot see this conversation. If you learned something from an + earlier turn, include it verbatim; don't paraphrase. +3. **Constraints** — explicit "do NOT" list. "Do not refactor surrounding + code." "Do not add tests." "Do not touch files outside `src/billing/`." +4. **Output format** — what to return and in what shape. "Report root cause + + file:line + proposed fix in under 200 words" beats "investigate this." + +If you can't fill all four fields, you don't yet understand the task well +enough to delegate it. Do it yourself, or think more before dispatching. + +## Context-Pollution Rule + +Subagents exist to absorb noise the main thread shouldn't carry. When one +fails or produces unexpected results: + +- **Do not retry the task manually in the orchestrator context.** That + re-imports the exact noise the subagent was meant to contain — failed + approaches, dead ends, irrelevant exploration. +- **Dispatch a fix subagent** with the failure report as its context + (paste the subagent's output verbatim). New scope, fresh context. +- **If two fix attempts fail**, stop and surface the problem to the user. + Don't keep spawning. + +The corollary: if you're tempted to "just quickly fix it myself after the +agent failed," you are about to pollute your context. Dispatch. + +## Review-Gate Cadence + +Subagent output is not verified work — it's a claim about what was done. +Review before moving on: + +- **Sequential execution** — review after each task completes. Read the + diff, run the relevant tests, confirm the claim matches reality (see + `verification.md`). Then spawn the next task. +- **Parallel execution** — review after every batch of ~3 tasks. Larger + batches compound bugs; smaller batches make review overhead dominate. +- **Never chain subagents past a failed review.** If the review finds a + problem, dispatch a fix subagent before continuing the plan. + +## Delegation vs Understanding + +Subagents execute; they do not understand *for you*. Never write prompts +like: + +- "Based on your findings, fix the bug" — synthesis pushed onto the agent +- "Investigate and implement" — scope too broad, no contract + +Do the understanding step yourself (read the agent's report, decide the +fix), then dispatch the fix with a specific contract. + +## Anti-Patterns + +- **Parallel implementation agents on overlapping files** — they will + conflict. Fan-out is for investigation, not concurrent writes. +- **Broad prompts** — "fix the failing tests" sends the agent exploring; + "fix the assertion at `test_cart.py:142`" gets a diff. +- **Timeout-tuning to quiet flaky tests** — the flake is usually a race + condition. Diagnose, don't mask. +- **Retrying a failed subagent task in the orchestrator** — pollutes + context. Dispatch a fix agent instead. +- **Subagenting trivial work** — one Read + one Edit doesn't need an + agent; spawn overhead exceeds benefit. +- **Skipping review between tasks** — compounding bugs are much harder to + unwind than any single bug. +- **Letting the agent decide scope** — "figure out what needs changing" + produces sprawling, unfocused work. You decide scope; the agent + executes it. + +## Cross-References + +- Completion claims must be verified regardless of who produced them — + see `verification.md`. +- Testing discipline applies to subagent-produced tests too — see + `testing.md`. diff --git a/debug/SKILL.md b/debug/SKILL.md index e4e1041..7f3771a 100644 --- a/debug/SKILL.md +++ b/debug/SKILL.md @@ -46,6 +46,8 @@ Do not propose any fix during this phase. You are gathering evidence. If you've attempted 3 fixes and the bug persists, stop. The problem is likely architectural, not local. Report what you've learned and recommend a broader investigation rather than attempting fix #4. +When fanning out investigation across multiple independent files or subsystems, follow `subagents.md` — use parallel read-only agents for exploration, never for concurrent writes, and dispatch a fresh fix-agent on failure rather than retrying in the main context. + ## What Not to Do - Don't propose fixes before completing Phase 2 diff --git a/finish-branch/SKILL.md b/finish-branch/SKILL.md index 5cb02ef..0903010 100644 --- a/finish-branch/SKILL.md +++ b/finish-branch/SKILL.md @@ -40,6 +40,8 @@ Commands vary by stack. Use what the project's Makefile, `package.json` scripts, **If verification passes:** continue to Phase 2. +If any verification step fails and triggers sub-investigations, follow `subagents.md` — dispatch a fresh fix-agent per failure with pasted error context rather than retrying in the orchestrator. + ## Phase 2 — Determine Base Branch The four outcomes need to know what the branch is being integrated into. Find the base: diff --git a/review-code/SKILL.md b/review-code/SKILL.md index 6366345..fdf5cfb 100644 --- a/review-code/SKILL.md +++ b/review-code/SKILL.md @@ -62,6 +62,8 @@ If skipping, report: "Skipped — <reason>" and stop. Each perspective is a distinct review angle. For substantial changes, dispatch them as parallel sub-agents. For small changes, run sequentially inline. +Follow `subagents.md` for the dispatch contract — each perspective's prompt needs explicit scope, pasted diff context, constraints (don't flag unmodified lines, don't rewrite the PR), and a required output format. Perspectives are read-only and independent, so parallel fan-out is always safe here. + ### Perspective A — CLAUDE.md Adherence Read the CLAUDE.md files collected in Phase 1. For each rule they state, check whether the diff honors it. CLAUDE.md is writing guidance, so not every rule applies at review time — focus on rules that are *assertions about what committed code should look like*. |