claude-code-kickstart CLAUDE.md

Be concise. State conclusions first. Skip preamble and filler.

Core loop: gather context → act → verify → repeat.

1. Session Protocol

Start: read primer.md (state, next steps) and gotchas.md (past mistakes). Pick mode by scope:

• 1–2 files: just do it.
• 3–5 files: state scope, get approval, execute.
• 5+ files: plan mode, phased execution, max 5 files per phase.

End: run /wrap-up before closing the session.

Continuity: prefer claude --continue over fresh sessions. --fork-session to branch. /compact proactively when context degrades. Don't switch models mid-session — delegate to sub-agents.

2. Planning

• Plan and build are separate. "Think about this" = plan only, no code.
• If the user gives a plan, execute it. Flag real problems; don't improvise.
• Non-trivial work (3+ steps or architectural decisions): align on tradeoffs before writing code.
• One-word replies ("yes", "do it", "push") = execute, don't restate the plan.

3. Code Quality

• Senior-dev bar. Flawed architecture or duplicated state → propose structural fixes, don't just patch.
• Write human code. No robotic comments or boilerplate.
• Simple and correct beats elaborate and speculative.
• On non-trivial changes, pause once: "is there a cleaner way?"

4. Execution Loop

Non-negotiable workflow for any task beyond a trivial one-liner:

• One task at a time. Batch only closely-related small steps. Never implement task B before task A is fully done (impl + tests + review + fixes).
• Implementation writes the tests. Same context, same turn. Tests are not a follow-up task — they're part of the definition of done.
• Checkpoint reviews in parallel. After each meaningful chunk, launch review sub-agents concurrently (single message, multiple Agent calls). Minimum set: code-reviewer, security-reviewer, test-runner. Add accessibility-reviewer for UI work.
• Review agents must read the plan first. Every review agent gets the task description, intended behavior, and the list of files touched — not just "review my code". A reviewer without intent can't judge correctness.
• Review scope: bugs, security holes, data leaks, naming problems, inconsistencies, data corruption risks, edge cases, missing tests, race conditions.
• Fix all valid findings before moving on. No "I'll address this in a follow-up." If a finding is invalid, state why in one sentence.
• Never defer quality, testing, or security to the end. Each checkpoint is independently shippable.
• Code understanding: when tracing dependencies, following call graphs, or exploring unfamiliar code, prefer SocratiCode MCP tools (codebase_search, codebase_graph_query) over raw grep for non-trivial searches.