Claude Code Guide

## Full reference: Claude Code in production

### 1. Discovery order

Claude Code loads context in this precedence, highest first:

1. System prompt (CLI-bundled, immutable).
2. `~/.claude/CLAUDE.md` — user-global instructions across every project.
3. `<repo>/AGENTS.md` (or `CLAUDE.md` — both are honoured; AGENTS.md is the cross-tool convention).
4. `<repo>/.claude/skills/**/SKILL.md` — surfaced on-demand when the frontmatter `description` matches the task.
5. User messages in the chat.

Practical consequence: put universal style preferences in `~/.claude/CLAUDE.md`, project-specific rules in `AGENTS.md`, and task-scoped recipes in skills. Do not duplicate across layers — later layers should specialise, not override.

### 2. AGENTS.md — the project charter

The AGENTS.md convention was introduced by Anthropic and subsequently adopted by OpenAI's Codex CLI, Cursor, Aider, Continue, and many others. As of early 2026 the file is committed in 60,000+ public GitHub repos.

Keep it terse. An effective AGENTS.md covers:

- **Run commands**: test, lint, build, dev server.
- **Directory map**: one line per top-level directory.
- **Conventions**: naming, imports, test placement, forbidden patterns.
- **Definition of done**: what passes before a task is considered complete.
- **Known landmines**: "never run `prisma migrate reset` — it drops the dev seed."

Anti-patterns:

- Dumping the entire style guide. Link to it instead.
- Storing secrets or anything that must not appear in logs. AGENTS.md content is visible in every agent run.
- Marketing copy. The agent doesn't care that your product is "delightful."

### 3. Skills — scoped, on-demand expertise

A skill is a directory under `.claude/skills/<name>/` containing at least a `SKILL.md`. The frontmatter `description` is a retrieval key — Claude Code loads the body when a task matches it.

```markdown
---
name: migrate-prisma
description: Use this skill when adding a Prisma migration. Enforces naming, reversibility, and CI smoke-test update.
---

# Prisma migration recipe
1. `pnpm prisma migrate dev --name <slug>`
2. Review generated SQL for destructive ops; abort if any `DROP`.
3. Update `scripts/smoke-test.ts` to exercise the new columns.
4. Commit migration + smoke test together.
```

Skills can include `scripts/` and `references/` subdirectories. The agent can read them on demand with the Read tool — they do NOT all enter context at invocation. That is the unlock: dozens of skills cost zero baseline context.

### 4. Subagent delegation (Task tool)

The Task tool spawns a subagent with its own isolated context. The subagent runs to completion and returns a single text message to the parent.

Use it when:

- **Wide exploration**: "find every call site of this function" — subagent reads 50 files, parent gets a 500-token summary.
- **Parallel investigation**: three subagents in parallel, each chasing a hypothesis.
- **Context hygiene**: the parent's context is getting long and the upcoming step is read-heavy.

Do not use it when:

- The main thread already has the files in context — re-reading in a subagent wastes tokens.
- The task requires state that lives only in the parent (a half-written plan, an uncommitted edit).
- One step away from done.

### 5. Hooks — PostToolUse, PreToolUse, Stop

Configured in `.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "pnpm lint --fix \"$CLAUDE_FILE_PATHS\"" },
          { "type": "command", "command": "pnpm tsc --noEmit" }
        ]
      }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "pnpm test --run" }] }
    ]
  }
}
```

Key facts:

- Hook stdout is fed back into the agent's context as tool output.
- Hook stderr with non-zero exit causes the agent to see a failure and react.
- `$CLAUDE_FILE_PATHS` is injected for Edit/Write matchers; space-separated.
- PreToolUse can block a call by exiting non-zero — used to enforce "never edit `_generated/` files."

The practical wedge: hooks take the "did the agent remember to run the tests" problem off the table. The harness runs them every time.

### 6. Session memory

Claude Code persists three kinds of state across a session:

- **Conversation history**: full turn log, kept until compaction.
- **Plans**: if the agent writes a plan via the todo tool, it survives.
- **Scratch files** in `.claude/scratch/`: optional, project-local.

When the context window gets tight, the harness runs auto-compaction: older turns are replaced by a summary. You can force it earlier with `/compact`.

### 7. Context-window tactics

At 200k tokens the budget feels infinite. It is not — large repos blow through it.

- **Read less, search more**: prefer Grep / smart_search over Read when you don't know the file.
- **Unfold, don't Read**: structural tools like `smart_outline` + `smart_unfold` return only the symbol you need.
- **Delegate wide reads**: subagent returns a summary, parent keeps the synthesis.
- **Edit, don't Write**: Edit sends only the diff; Write ships the whole file back into context.
- **Prune plans**: drop completed todos; don't let the list grow unboundedly.

### 8. Edit vs Write — the decision tree

```
Does the file already exist?
├─ No  → Write
└─ Yes → Are you changing <30% of the content?
          ├─ Yes → Edit (with replace_all if mass rename)
          └─ No  → Write only if a full rewrite is clearly simpler; otherwise a
                   sequence of Edit calls stays cheaper on the context budget.
```

Edit failures usually mean the `old_string` isn't unique — widen the context before retrying. If three Edits in a row fail, step back and Read the current state.

### 9. The todo tool

Claude Code ships a built-in todo tool. Use it when:

- The task is ≥3 distinct steps.
- You need visible progress for the user.
- You want a durable plan that survives compaction.

Do not use it for:

- Single-step tasks — visible noise.
- Exploratory work where the steps aren't yet known.

Always maintain exactly one `in_progress` todo at a time. Mark complete the moment a task finishes — batch completions erode trust.

### 10. Installation and updates

```bash
npm install -g @anthropic-ai/claude-code
claude  # launches the CLI in the current directory
```

Version and harness identifier surface via `claude --version`. Pin the version in CI if hook behaviour matters.

### 11. Common misunderstandings

1. "Skills are auto-loaded into context." No. The frontmatter is indexed; the body loads on demand.
2. "AGENTS.md overrides the system prompt." No. The system prompt safety rules are immutable.
3. "Subagents share memory with the parent." No. Only the return text enters the parent's context.
4. "Hooks run in the agent's turn." Hooks are external processes; they don't count against model tokens but their output does.
5. "CLAUDE.md and AGENTS.md are different." In Claude Code they are equivalent; AGENTS.md is preferred because other tools honour it.