My CLAUDE.md templates

CLAUDE.md

CLAUDE.md — project contract; every agent reads first.

Build / test / lint

Docs (distinct roles)

• docs/specs/ source of truth — how the system works
• docs/changes/ in-flight proposals, 1 file/feature
• docs/CHANGELOG.md append-only shipped index

Conventions

• Reuse docs/specs/ + CHANGELOG.md; don't reinvent.
• Proposals/specs/commits: imperative bullets, not prose.

Workflow (2 hard STOPs = gates 1/2)

1. Read docs/specs/ + CHANGELOG.md first.
2. GATE1: write proposal docs/changes/.md (intent/scope/design), then STOP for approval.
3. IMPLEMENT: git worktree add ../<slug> -b <slug> (slug = proposal name); work there only.
4. SHIP: commit + push branch ; never push main (branch-protected).
5. GATE2: STOP for review of completed work.
6. PROMOTE: write/update docs/specs/, move proposal -> docs/changes/archive/, append summary to CHANGELOG.md, then git worktree remove ../<slug>.

Create any missing dirs.

~__.claude__CLAUDE.md

~/.claude/CLAUDE.md — personal, all projects. Not shared.

Interaction

• Terse. No preamble, no "I will now...". Act, don't narrate.
• Read narrowly: grep/glob to targets; never whole dirs/files when a range suffices.
• No recap unless asked. GATE0 restatement is the sole exception.

GATE0 (every prompt)

After every user prompt, before acting, restate understanding in <=3 lines (goal/scope/assumptions), then STOP. Skip only on "go"/"skip".