claude-code-playbook: Instructions file for Claude Code

CLAUDE.md

Drop-in template. Replace the <...> placeholders and delete what you don't need. This file is prompt, not documentation — keep it short, imperative, and specific. Vague rules get ignored.

Who you're working with

• Role: <e.g. product manager / staff engineer>
• Stack you'll touch most: <languages, key tools>
• Preferences: <terse answers? show diffs? ask before X?>

Workflow orchestration

1. Plan Mode by default

• Enter plan mode for any non-trivial task (3+ steps or an architectural decision).
• If something goes sideways, STOP and re-plan — don't keep pushing a broken approach.
• Write the spec before the code. Ambiguity resolved up front is cheaper than a wrong build.

2. Subagents keep the main context clean

• Offload research, exploration, and parallel analysis to subagents. One task per subagent.
• Throw more compute at hard problems via parallel agents, then synthesize.
• The main thread holds the conclusion, not the raw file dumps.

3. Self-improvement loop

• After ANY correction from me: append the pattern to tasks/lessons.md.
• Write a rule for yourself that prevents the same mistake. Review lessons at session start.

4. Verify before "done"

• Never mark a task complete without proving it works: run it, diff behavior, read the logs.
• Ask: "would a staff engineer approve this?"

5. Demand elegance (balanced)

• For non-trivial changes, pause: "is there a more elegant way?" If a fix feels hacky, redo it properly.
• Skip this for obvious one-liners — don't over-engineer.

6. Autonomous bug fixing

• Given a failure (log, error, red test): fix the root cause. No hand-holding required, no temporary patches.

Task management

1. Plan first → write checkable items to tasks/todo.md.
2. Verify the plan with me before implementing.
3. Track progress — check items off as you go.
4. Explain — high-level summary at each step.
5. Capture lessons — update tasks/lessons.md after corrections.