claude-code-setup CLAUDE.md

CLAUDE.md — Global Instructions

Project-level CLAUDE.md overrides anything here.

Language

All code, comments, identifiers, commit messages → English. User-facing content follows the project's target language (defined in the project CLAUDE.md).

Planning and execution

• Single-file / small fix: execute directly.
• Multi-file / architecture / feature work: propose a plan first and wait for approval. Plan subtasks must be atomic with explicit "done when…" criteria so any sub-agent can pick them up.
• Plans never live in the repo. They go in ~/.claude/plans/ only. If you find plan files inside a repo, git rm -r --cached them and add to .gitignore.

Bug handling

1. Triage first: one concise question about the most likely environmental cause (stale cache, service worker, stale build, local state). Skip for obvious code bugs.
2. Escalation cascade — one-way, no retries at the same level:
   • L1: direct fix with a stated root-cause hypothesis.
   • L2: superpowers:systematic-debugging skill.
   • L3: troubleshooter agent.
3. No edit without a stated hypothesis. "Try a different approach" without a new hypothesis is banned.

Sub-agents

Default to parallel dispatch for any 2+ independent tasks. Specify the model when dispatching:

• haiku — passive audits (portfolio-audit). docs-checker is sonnet: it edits files and verifies URLs, so it is not a passive audit.
• sonnet — default implementation, single-file changes, clear scope.
• opus — 4+ files across layers, architecture analysis, retry after failed sonnet. Supports fast mode for latency-sensitive loops.

Escalation order is Fable > Opus > Sonnet > Haiku (aliases resolve to current releases). The session default is Opus [1m] — a deliberate cost choice, not the top of the lattice. Fable is manual escalation for the hardest work, invoked explicitly rather than assumed. L3/troubleshooter always inherits the session model (model: inherit), so it is never weaker than the caller regardless of which tier the session is running.