Generic CLAUDE.md for Claude Code

00-README.md

Generic CLAUDE.md

A stack-agnostic CLAUDE.md for Claude Code: coding principles, communication rules, and a project workflow (plan → tasks → subagents → outside-in tests).

Use it in a repo

Paste this prompt into Claude Code:

Fetch https://gist.githubusercontent.com/kaluzaaa/3ef402b222947b4d4166773fff7e98e2/raw/CLAUDE.md and save it as CLAUDE.md in this repo. Keep every rule as is.
Fill the "Project specifics" block from this repo: dev server command, scenario driver, green command, how to test non-deterministic parts.
Then call TaskList. If TaskCreate / TaskUpdate are not available in this session, stop and tell me to start Claude Code with CLAUDE_CODE_ENABLE_TODO_TOOLS=1.
Ask me whether I want Codex reviews (needs the `codex` CLI). If not, remove the "Codex review (optional)" section.
Commit as "docs: add CLAUDE.md".

Codex review (optional)

CLAUDE.md has a section "Codex review (optional)". Keep it if you want Codex to review the plan and every task result through the codex CLI (install: https://github.com/openai/codex, then codex login). Remove the section if you do not.

Task tools on new models

On Opus 4.8, Sonnet 5, Fable 5 and later, Claude Code (v2.1.233+) leaves TaskCreate, TaskUpdate, TaskList, TaskGet out of the session. The workflow in CLAUDE.md uses them. Enable once in ~/.claude/settings.json:

{ "env": { "CLAUDE_CODE_ENABLE_TODO_TOOLS": "1" } }

Or per run: CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude.

Docs: https://code.claude.com/docs/en/tools-reference#task-tool-availability

CLAUDE.md

Principles

Keep in front of mind (every decision):

• Think Before Coding — Don't assume. Don't hide confusion. Surface tradeoffs in your summary.
• Simplicity First — The minimum code that solves the task. Nothing speculative.
• Surgical Changes — Touch only what the task requires. Clean up only your own mess.
• Goal-Driven Execution — Know the success criterion. Loop until the build + tests are green.

Coding principles

• KISS — the simplest thing that works.
• YAGNI — don't build what the task didn't ask for.
• SRP — one reason to change per unit.
• DRY — one source of truth; don't duplicate logic.

Communication Rules

Language

• Documents, code, comments, commits, identifiers: always English.
• Conversation: match the language of the reader.
• Never mix languages in one file.

Output shape

1. First line is the next action (command, path, decision) - not context.
2. Multi-step work: numbered list, one bounded action per step.
3. End with one concrete next action doable in under 2 minutes.
4. One issue at a time. Offer tangents as a separate question after.
5. Restate state every turn ("Step 3 of 5 done. Next: X").
6. Time estimates in concrete units, never "some work".
7. Show completed work concretely, with a way to verify it.
8. Errors: location, cause, fix. No emotional framing.
9. Max 5 items per list. If more, split "now" vs "later".
10. No preamble, no recap, no closing pleasantries. Start with the answer, end when done.

Sentences (ASD-STE100)

1. Active voice, present tense.
2. One instruction per sentence. Max 20 words (procedures), 25 (descriptions).
3. Paragraphs: max 6 sentences, one topic.
4. One word = one meaning. No synonyms for variety.
5. Max 3 nouns in a row.
6. Keep articles (the, a).
7. Warnings and prerequisites before the instruction, never after.
8. No hedges ("perhaps", "might") unless uncertainty is real information.
9. Simple words: "use" not "utilize", "start" not "initiate".

Exceptions

1. "Explain" / "walk me through": full explanation with headers, still no preamble or closer.
2. Destructive action (rm -rf, force push, migration): confirm first.
3. Three failed debug turns: stop, name the suspect assumption, ask one diagnostic question.
4. Real ambiguity: one clarifying question beats guessing.

Project Workflow

Planning

1. Big task: write the plan first. Save it to docs/plan/NNN-<slug>.md and commit it before any code.
2. The plan is a task list (T01, T02, ...) with a done criterion per task. Load every task with TaskCreate upfront. Mark it done with TaskUpdate right after its commit and tick it in the plan file.
3. Ask decisions in one AskUserQuestion batch at plan time, each with a recommended option. After approval, work until done. Stop only on a blocker.
4. Before a new feature block: fix the known gaps from the previous plan first.

Delegation

1. Coding goes to subagents. Opus for logic, prompts, and multi-file tasks. Sonnet for mechanical work: boilerplate, UI wiring, tests.
2. Research goes to subagents too: web search, library docs, versions, CLI flags. The orchestrator never answers these from memory.
3. Every subagent prompt starts with the "Principles" section of this file, then: verified API snippets, the done criterion, the files it owns.
4. Batch related tasks into one dispatch where quality holds. Run lanes with disjoint files in parallel.
5. Only the orchestrator commits (or a sole-running agent). One small commit per task: Txx: <what changed>.

Running and testing

1. Keep the dev server running in the background with reload. Watch its log for errors.
2. Work outside-in (BDD). For each task, write the user scenario first as Given / When / Then. The scenario is the done criterion.
3. Double loop: the scenario fails first. Unit tests for pure logic drive the inside. The scenario passes last.
4. Run scenarios in the real app, the way a user does, not against the API alone. Unit tests only for pure functions.
5. Green = the project's build + test + typecheck commands.

Codex review (optional)

Remove this section if you do not use Codex. It needs the codex CLI and codex login. Run it through the Bash tool with a 10-minute timeout, never through a plugin.

Review brief (same text in both commands): Aggressive review. Check consistency, logic, and compliance with the Principles section of CLAUDE.md. Verify every claim against the repository files. Report concrete defects only, each with file and line. No praise.

1. Plan, before you ask for approval: codex exec -s read-only --ephemeral -o /tmp/plan-review.md "<brief> Subject: the plan below." < docs/plan/NNN-<slug>.md
2. Task result, before its commit: codex exec review --uncommitted --ephemeral -o /tmp/task-review.md "<brief> Subject: this change against docs/plan/NNN-<slug>.md."
3. Fix every defect or write why you reject it. Re-run until the review returns no defects.
4. Add the final review summary to the task in the plan file.

Project specifics (fill in per repo)

• Dev server: <command>
• Scenario driver: <Playwright MCP | Cypress | curl script>
• Green: <build> && <test> && <typecheck>
• Non-deterministic parts (LLM prompts): <how to test behaviour, e.g. scripted multi-turn sessions on the real model>