ClaudePath

A reusable .claude/ setup for scientific (HEP/ML) research repositories. Grounded in Anthropic's official Claude Code documentation (best practices, memory, skills, subagents, hooks, settings) and battle-tested in a CMS unfolding analysis.

Design principles

1. CLAUDE.md is a lean map, not a manual (< 200 lines, ideally < 60). Per-line test: would removing this cause Claude to make mistakes?
2. One rule per mistake, self-improving. Every conceptual mistake Claude makes becomes a numbered rule in .claude/rules/learned-mistakes.md. Prune and merge regularly — a one-off glitch is not a rule.
3. Procedures live in skills (loaded on demand), constraints in rules (loaded at launch, path-scoped where possible), must-happen actions in hooks (deterministic, not advisory), fresh-context judgment in subagents, external systems via MCP.
4. Verify, don't trust — be skeptical of results AND instructions. Results get adversarially red-teamed by fresh-context subagents before they are written down; commits require a scientific-reasonability pass, not just green linters; claims in tickets/notes/memory are checked against current code and data before being acted on.
5. Git is part of the workflow, worktree-first: small verified commits, regular pushes; parallel or experimental work starts in a worktree (claude -w), never on the main checkout.
6. No secrets in tracked files, ever.

Quick start (copy mode)

git clone https://github.com/SebPit/ClaudePath.git
./ClaudePath/install.sh /path/to/your/project          # add --force to overwrite

The installer copies .claude/ (never overwriting existing files; --force overwrites .claude/ files and CLAUDE.md with the current template versions), creates CLAUDE.md from the template if absent, appends the .gitignore block, and sets up auto memory to live in the tracked .claude/memory/ (autoMemoryDirectory in machine-local settings.local.json — re-run the installer on each new machine). Then edit the <placeholders> in CLAUDE.md, delete anything that does not apply — an unused instruction is context noise — and commit and push the setup (git add .claude CLAUDE.md .gitignore .pre-commit-config.yaml .worktreeinclude): the shared .claude/ only syncs between your devices once it is on the remote. The .gitignore secrets list and the Read deny list in .claude/settings.json name the same file set — keep them in sync when you extend either. On an existing large repo, /init drafts the Map section of CLAUDE.md for you — trim its output against design principle 1 before committing.

What's inside

Path	What	When it loads
CLAUDE.md.template	Lean map + core rules, with <placeholders>	every session
.claude/rules/code-quality.md	Clarity/efficiency constraints	launch
.claude/rules/git-workflow.md	Commit/push cadence, worktree-first constraints	launch
.claude/rules/scientific-writing.md	Notation discipline for papers	when editing **/*.tex
.claude/rules/learned-mistakes.md	Self-improving numbered rule list	launch
.claude/skills/session-notes/	NOTES.md handoff between sessions	on demand
.claude/skills/science-plots/	Publication plotting conventions	on demand
.claude/skills/red-team-result/	Adversarial verification of results	on demand
.claude/skills/checkpoint/	Verify → reasonability check → commit → push	on demand
.claude/skills/memory-prune/	Grow-and-prune pass: old context out of the always-loaded index	on demand
.claude/skills/usage-review/	Prompt-habit coach report via usage-coach	/usage-review (user-run)
.claude/agents/usage-coach.md	Reviews recent prompts vs Anthropic practice	delegated
.claude/agents/result-verifier.md	Skeptical scientific reviewer persona	delegated
.claude/agents/diff-reviewer.md	Fresh-context diff review before merge	delegated
.claude/agents/perf-reviewer.md	Efficiency review: GPU sync stalls, vectorization, O(N²), memory leaks	delegated
.claude/hooks/guard_project_python.sh	Blocks bare python when ./venv exists (best-effort segment matching)	every Bash call
.claude/hooks/session_reminders.sh	Nudges session-notes / memory-prune only when due	session start
.claude/settings.json	Safe permission allowlist + hook wiring	launch
.claude/memory/README.md	Tracked cross-device memory pattern	reference
pre-commit-config.yaml.template	black + ruff + pydoclint + darglint2 stack	installed per repo
.worktreeinclude.template	Gitignored files copied into new worktrees	installed per repo

Other ways to consume this repo

• Symlink the rules (documented by Anthropic): keep one clone and ln -s /path/to/ClaudePath/.claude/rules .claude/rules/shared in each project.
• User-level defaults: copy pieces into ~/.claude/ (CLAUDE.md, rules/, skills/, agents/) to apply on every project on the machine.
• Plugin: when this stabilizes for a team, convert to a Claude Code plugin (.claude-plugin/plugin.json + root-level skills/, agents/, hooks/) and distribute via a marketplace repo. Anthropic recommends starting with a plain .claude/ and converting once shared.
• AGENTS.md bridge: in repos shared with other agent tools, keep AGENTS.md canonical and make CLAUDE.md a one-line @AGENTS.md import — Claude Code reads CLAUDE.md, not AGENTS.md.

Working habits the files can't encode

Anthropic's recommended workflow patterns that live in how you drive the session, not in this repo — teach them to yourself and your collaborators:

• Explore → Plan → Implement → Commit. Use plan mode for anything you could not describe as a one-sentence diff; approve or refine the plan before code changes. For big features: have Claude interview you, write a SPEC.md, then execute in a FRESH session.
• Interview over assumption. When a request is ambiguous, Claude should ask targeted clarifying questions (CLAUDE.md Rule 1) instead of guessing — under-instructing is the most common failure mode, and unstated assumptions are how it compounds.
• Worktree per task. claude -w <topic> gives every parallel or experimental line of work an isolated checkout — see "Worktrees" below.
• Proactive commits are a deliberate choice. The checkpoint skill is model-invocable by design; the safety valve is that git push sits in the settings ask list. Don't blanket-allow push if you want that gate.
• Keep context clean. /clear between unrelated tasks. After two failed corrections, restart with a better prompt instead of correcting a third time — a clean session with a better prompt beats a long session with accumulated corrections.
• Verification ladder. In-prompt check → deterministic hook gate → fresh-context reviewer subagent (diff-reviewer, perf-reviewer, result-verifier). Have Claude show evidence, not assert success.
• Personal overrides go in CLAUDE.local.md (gitignored) and .claude/settings.local.json, never in the shared files.
• Permission posture. Prefer auto mode (background classifier checks) over bypassPermissions; reserve bypassPermissions for disposable containers/VMs only, and dontAsk (auto-deny anything not allowlisted) for locked-down CI. Note: defaultMode: "auto" is only honored in user settings — ignored in project/local settings by design, which is why this repo's settings.json does not set a mode; it is a per-user choice.
• Headless/CI: claude -p "<prompt>" --allowedTools ... for scripted or CI usage once the interactive workflow is stable (--permission-mode dontAsk for locked-down CI).

Worktrees (parallel sessions)

• claude --worktree <name> (or claude -w <name>) creates an isolated worktree at .claude/worktrees/<name>/ on branch worktree-<name> and starts the session there; omit the name for an auto-generated one. Clean exits auto-remove the worktree and branch; dirty exits prompt keep-or-remove.
• New worktrees branch from origin's default HEAD; set "worktree": {"baseRef": "head"} in settings to branch from the local HEAD instead. claude --worktree "#1234" branches from a PR.
• .worktreeinclude (repo root, gitignore syntax) lists gitignored files (.env, local config) that get copied into each new worktree so it runs out of the box.
• Subagents can set isolation: worktree to run in a disposable worktree; deliberately NOT set on diff-reviewer/result-verifier, which must see the current working tree.
• Manual fallback (non-Claude tooling): git worktree add ../<repo>-<topic> -b <topic>; finish with git worktree remove and git branch -d <topic>.

Optional: bare-repo layout (community pattern, not Anthropic-documented)

No checkout is "the" checkout — every branch is a sibling worktree:

git clone --bare <url> <repo>/.bare
echo "gitdir: ./.bare" > <repo>/.git
cd <repo>
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" && git fetch
git worktree add main        # then one worktree per long-lived branch

To convert an existing clone, re-clone into this layout and move the untracked state over (.env, venv/, CLAUDE.local.md, .claude/settings.local.json); do not attempt in-place surgery on .git. claude -w still works inside any worktree of this layout.

The self-improvement contract

After any correction or conceptual mistake: append an actionable rule to .claude/rules/learned-mistakes.md (numbered, phrased as the correct understanding, not a war story). When the list grows past ~25 entries, merge duplicates and retire rules the model reliably follows unprompted. Keep CLAUDE.md itself stable and short.