CLAUDE.md

Global rules

Verification

• A passing check is not evidence it works. A green run means either the code is fine or the gate is broken, and those look identical. Before trusting or shipping any gate — test, lint rule, CI step, assertion, self-check — break the smallest thing it guards, confirm it goes red and names the right problem, then restore.
• This applies to gates you are building, changing, or about to stake a claim on — not to running an existing suite on request. If asked simply to run tests, report the result; offer the red-proof, don't perform it unasked.
• When the red-proof applies, show both results, the red and the green. "It passes" on its own is not a report there.
• This matters most where failure is silent rather than loud: a gate that can only ever print success looks exactly like one that is working.

Subagent Delegation & Context Economy

Principle: Protect the main thread. Delegate for reasoning quality, not parallelism.

Use subagents carefully.

Before delegating, decide whether the work should be split by cognitive locality. If two tasks require understanding the same files, conventions, or architecture, give them to one agent instead of splitting them.

For concurrent agents:

• Assign clear ownership of files or areas.
• Avoid overlapping edits.
• Do not use repository-wide Git commands while other agents are active.
• Do not fetch or paste full agent transcripts into the main context.

Each subagent should return a compact report:

• Scope investigated
• Key findings
• Files changed or files that need changes
• Tests run or tests recommended
• Risks, blockers, or uncertainty
• Recommended next action

Keep all exploratory reasoning, failed attempts, raw logs, and verbose tool output out of the orchestrator context unless I explicitly request them.

Verification & Integration

• Prefer documented evidence for established external behavior.
• Execute code when necessary for project-specific behavior, debugging, or validation.
• Run relevant tests for implemented changes when feasible.
• The orchestrator validates integration across agent boundaries.
• Do not confuse individual subagent success with overall task completion.

Cost & Communication Habits

• Minimize redundant exploration, duplicated context loading, and unnecessary tool calls.
• Provide sufficiently complete instructions upfront to reduce clarification rounds.
• Batch related work and decisions into substantive handoffs.
• Prefer targeted file inspection over broad repository dumps.
• Prefer concise evidence summaries over verbose transcripts.
• Do not sacrifice correctness or necessary validation merely to reduce tool usage.

Final rule: Optimize for useful information reaching the orchestrator per unit of context consumed, while preserving correctness, traceability, and integration safety.