# 02 — Claude Code How we configure and use Claude Code across projects. ## Configuration files Each project should have: ``` / ├── CLAUDE.md ← project context (committed) └── .claude/ ├── settings.json ← shared settings (committed) ├── settings.local.json ← personal overrides (gitignored) └── skills/ ← project-local skills (committed) ``` `settings.local.json` is **always** gitignored. Personal API keys, local paths, and individual hook tweaks live there. ## CLAUDE.md content Every `CLAUDE.md` answers, in this order: 1. **What is this project?** Two sentences max. 2. **How do I run it?** Build, test, lint commands as bash blocks. 3. **Architecture in one paragraph.** Where the entry points are and how data flows. No diagrams unless they save words. 4. **Conventions specific to this repo.** Naming, layout, patterns that aren't obvious from the code. 5. **Don'ts.** Things Claude has gotten wrong before. One line each. A new contributor (human or AI) should be productive after reading it once. If a `CLAUDE.md` is over 100 lines, it's drifted into documentation and should be split. Use `templates/CLAUDE.md.template` as the starting point. ## Permissions Default permission posture: **prompt for everything risky, allow read-only freely.** In `.claude/settings.json`, allow these without prompting: - All `Read`, `Glob`, `Grep` tools - `Bash(git status)`, `Bash(git diff)`, `Bash(git log)`, `Bash(git branch)` - Project-specific read-only commands (e.g. `Bash(npm test)`, `Bash(pytest)`) Always prompt for: - File `Edit` / `Write` outside the working tree - `Bash` with destructive verbs (`rm`, `mv`, `git push`, `git reset --hard`, package installs) - Any MCP tool that talks to a remote service When you find yourself approving the same prompt over and over, run the `fewer-permission-prompts` skill — it scans your transcripts and proposes an allowlist. ## Hooks Hooks are how the harness enforces rules automatically — Claude itself won't reliably remember a "from now on…" instruction across sessions. Use hooks for: - Auto-formatting on file edit (Prettier, ruff, gofmt) - Blocking edits to protected paths (`.env`, generated files, `dist/`) - Auto-running tests after a write to a known test path - Notifying on session stop / long-running task completion Don't use hooks for: - One-off checks ("just remember to do X this week") - Anything that depends on Claude's judgment ("only run if it makes sense") Configure via the `update-config` skill or edit `.claude/settings.json` directly. Document each hook with a one-line comment in the JSON. ## Memory The harness has a per-machine memory system. Use it for: - **User**: who you are, your role, your preferences. - **Feedback**: corrections you've given Claude that should stick across sessions (with the *why*). - **Project**: facts about ongoing work that aren't in the code (deadlines, stakeholder decisions, why a refactor is happening). - **Reference**: pointers to external resources (Linear projects, Grafana dashboards, internal wikis). Don't put memory content in `CLAUDE.md`. CLAUDE.md is project context, shared with the team. Memory is personal, per-machine, and lives outside the repo. Don't use memory as a notes app. If it's task-scoped, it goes in a plan or PR description. ## Skills Skills live in three places: - **User skills** (`~/.claude/skills/`) — installed once, available everywhere - **Project skills** (`/.claude/skills/`) — committed, shared with team - **Plugin skills** — installed via marketplace Promote a workflow to a skill once you've done it the same way three times. See `docs/04-skills-and-planning.md` for the catalog. ## Sub-agents Spawn a sub-agent (via the `Agent` tool) when: - The task needs a search across many files and you don't want the results in your main context. - You want a second, independent read on a design or diff. - The work is genuinely parallel (e.g. researching three options). Don't spawn sub-agents for tasks the main agent can do in two tool calls. The handoff overhead isn't free. ## Sessions - One task per session. Open a new session for a new task. - If a session is running long and the context bar is filling, finish the current step, summarize state into a plan or PR draft, then start fresh. - Don't use `--continue` to resume a session from yesterday on a new topic. The stale context will leak in.