Agent Coding Handbook

A chat model answers once. A coding agent runs a loop: it reads your goal, gathers evidence from the real repository, decides on one action, executes it through a tool, observes the result, and decides again. It stops when the goal is met or when it needs you.

The model supplies reasoning. Everything around it — which files it can see, which commands it may run, what happens after each edit, what counts as done — is the harness. claude and codex are harnesses. Configuring them well is the whole job.

The six parts you configure

Every feature in the rest of this handbook belongs to exactly one of these. When something goes wrong, name the part first — it tells you which file to open.

Install Claude Code

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Homebrew (does not auto-update; run 'brew upgrade claude-code')
brew install --cask claude-code

# WinGet (does not auto-update)
winget install Anthropic.ClaudeCode

Native installs update themselves in the background. On native Windows, install Git for Windows as well — without it Claude Code falls back to PowerShell for its shell tool instead of Bash.

Install Codex

# Install (and later, update — same command)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# First run signs you in with your ChatGPT account
codex

Your first task, in the right order

1. Generate the instruction file — Run /init in either tool. Claude Code writes CLAUDE.md; Codex writes AGENTS.md. Both read the codebase first and propose build commands and conventions.
2. Read what it wrote — This file is loaded into every future session. Delete anything the agent can already derive from the code, and keep the things it cannot — pitfalls, rationale, conventions that differ from the tool defaults.
3. Ask a read-only question first — "Explain how authentication flows through this repo, and cite the files." You are checking whether the agent can find things before you let it change things.
4. Give it one bounded change — One file, one behaviour, with a test you can run. Ask for the plan before the edit.
5. Verify yourself — Run the build and the tests in your own terminal, then read the diff. Never approve a diff you have not read.
6. Write down what you corrected — The first correction you repeat twice belongs in CLAUDE.md or AGENTS.md. This is how the setup compounds.

Both tools are terminal-first agent harnesses with an IDE extension, a cloud runner, and a GitHub integration. They differ in file layout and in how permissions are expressed, not in the shape of the loop.

Running both tools on one repository

Claude Code reads CLAUDE.md, not AGENTS.md. Keep one source of truth by writing AGENTS.md and importing it, so a change in shared conventions never has to be made twice.

@AGENTS.md

## Claude Code only

Use plan mode for changes under `src/billing/`.
Run `pnpm test` before reporting a task complete.

Every session starts with a fresh context window and immediately fills part of it before you say anything. Knowing the running order tells you why an instruction was ignored — usually it was never loaded at all.

Run /context in a session to see the real numbers for the current run, including which memory files actually loaded. If a file you wrote is not in that list, the agent cannot see it — no amount of rewording will help.

What survives compaction

When the window fills, Claude Code summarizes the conversation and continues. Content loaded from disk is re-injected; content that only ever existed in the conversation is summarized away. This table is the single most useful thing to know about long sessions.

Where Claude Code looks

Files in directories above your working directory load at launch, ordered from the filesystem root down, so the file closest to where you started is read last. Files in subdirectories load on demand when the agent reads a file there.

Where Codex looks

Codex builds an instruction chain at startup: global first, then project files from the git root down to your working directory. In each location it checks AGENTS.override.md before AGENTS.md. Files closer to your current directory appear later in the combined prompt and therefore override earlier guidance. The chain stops once it reaches project_doc_max_bytes — 32 KiB by default.

codex --ask-for-approval never "Summarize the current instructions."

How to write instructions that get followed

• Stay under 200 lines — Longer files consume context and measurably reduce adherence. If it is growing, that content belongs in a path-scoped rule or a skill.
• Be concrete enough to verify — "Use 2-space indentation" beats "format code properly". "Run pnpm test before committing" beats "test your changes".
• Write what cannot be derived — Skip the directory listing and the dependency list — the agent can read those. Keep the pitfalls, the rationale, and the conventions that differ from the tool defaults.
• Remove contradictions — When two files disagree, the agent picks one arbitrarily. Review the whole set periodically, including nested files.
• Add an entry the second time you repeat yourself — The first correction is a conversation. The second is a missing instruction.

Imports

CLAUDE.md can pull in other files with @path/to/file, resolved relative to the importing file, up to four hops deep. Imports are expanded at launch, so they organize content — they do not reduce what it costs. Wrap a path in backticks to mention it without importing it.

See @README for the project overview and @package.json for available commands.

# Additional instructions
- Git workflow: @docs/git-instructions.md
- Personal preferences shared across worktrees: @~/.claude/my-project-instructions.md

Path-scoped rules

.claude/rules/ holds one markdown file per topic, discovered recursively. A rule with no frontmatter loads at launch with the same priority as .claude/CLAUDE.md. A rule with paths: frontmatter loads only when the agent reads a matching file — which is how you keep backend conventions out of a frontend task.

---
paths:
  - "src/api/**/*.ts"
  - "src/**/*.{controller,service}.ts"
---

# API rules

- Every endpoint validates its input before touching a service.
- Errors use the shared error envelope, never a bare string.
- A new endpoint ships with an integration test in the same PR.

Personal rules in ~/.claude/rules/ apply to every project and load before project rules, so project rules take priority. The directory supports symlinks, which is the clean way to share one rule set across several repositories.

Auto memory: the notes the agent keeps

Separately from anything you write, Claude Code saves short notes as it works — your preferences, corrections you gave it, and project facts it cannot derive from the code. They live in plain markdown you can read, edit, or delete.

{
  "autoMemoryEnabled": false
}

A skill is a folder with a SKILL.md in it. Unlike an instruction file, the body costs nothing until it is invoked — which is why a skill can be long and detailed where CLAUDE.md must be short.

Anatomy of a skill

---
name: review-diff
description: Reviews uncommitted changes for correctness and risk. Use before opening a PR.
allowed-tools: Bash(git diff:*) Read Grep
disable-model-invocation: true
---

## Current changes

!`git diff HEAD`

## Instructions

1. Group the diff by intent, not by file.
2. For each group, state the behaviour change in one sentence.
3. Flag: missing error handling, untested branches, widened permissions,
   and any change to a public contract.
4. End with a GO / NO-GO line and the single most important reason.

The ` !git diff HEAD ` line is dynamic context injection: the command runs and its output is inserted before the model reads the skill, so the review is grounded in the real diff rather than in a description of one.

Codex uses the same two required fields — name and description — and adds an optional agents/openai.yaml for display name, icon, implicit-invocation policy, and MCP tool dependencies. Bundle supporting material in scripts/, references/, and assets/ beside the SKILL.md in either tool.

A subagent is a separate context window with its own system prompt, tool allowlist, and model. It receives a task, works independently, and returns a summary — the intermediate file reads never enter your main session. That is the point: you keep the conclusion, not the search.

Delegate when the answer requires reading across many files and you only need the finding, or when you want a genuinely independent opinion on work the main session just produced. Do not delegate a single-file lookup — the coordination costs more than the search.

---
name: backend-reviewer
description: Reviews backend changes for data-safety and API-compatibility risk. Use after a service or migration is edited.
tools: Read, Grep, Glob, Bash(./gradlew test:*)
model: sonnet
permissionMode: plan
memory: project
color: cyan
---

You review backend changes. You never edit files.

For every finding, give: the file and line, the concrete failure scenario
(inputs and state that produce the wrong result), and the smallest fix.
Rank findings by severity. If you find nothing, say so in one line —
do not invent findings to fill the report.

# 1. Automatic — the agent matches your task to the description
# 2. By name in a prompt
"Have backend-reviewer look at the migration"

# 3. Guaranteed, via @-mention typeahead
@"backend-reviewer (agent)" review src/db/migrations

# 4. Run the whole session as that agent
claude --agent backend-reviewer

The Model Context Protocol is an open standard for exposing tools and resources to any compatible agent. An MCP server advertises named capabilities with schemas; the agent discovers and calls them. Because the contract is typed and the credentials live in the server, the agent never sees the secret — it only sees the tool.

Claude Code

# stdio server, project scope so the team gets it via git
claude mcp add --transport stdio --scope project postgres -- npx -y @bytebase/dbhub

# Remote HTTP server with a header
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  -H "Authorization: Bearer ${GITHUB_TOKEN}"

claude mcp list          # what is configured
claude mcp get <name>    # one server's details
claude mcp login <name>  # OAuth flow
claude mcp remove <name>

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": { "DB_URL": "${DATABASE_URL:-postgresql://localhost/mydb}" }
    }
  }
}

${VAR} and ${VAR:-default} are expanded from your environment, so the file itself stays safe to commit. Project-scoped servers require an explicit approval the first time an interactive session sees them.

Codex

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"
tool_timeout_sec = 45

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client
codex mcp login example
codex mcp list

Plugins

A plugin is an installable bundle — skills plus MCP servers plus, in Claude Code, subagents, commands, and hooks — distributed through a marketplace. Reach for a plugin when you want one install to deliver both the instructions and the connected service; reach for a bare skill when you only need instructions.

The `.claude` directory

Settings precedence, highest first

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(pnpm run lint)", "Bash(pnpm run test:*)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"],
    "additionalDirectories": ["../shared-types"],
    "defaultMode": "default"
  },
  "env": { "NODE_ENV": "test" },
  "autoMemoryEnabled": true
}

Codex `config.toml`

model = "gpt-5.6"
approval_policy = "on-request"     # or "never"
sandbox_mode = "workspace-write"
default_permissions = ":workspace" # :read-only | :workspace | :danger-full-access
web_search = "cached"              # cached | indexed | live | disabled

[windows]
sandbox = "elevated"               # fall back to "unelevated" if needed

[permissions.review-only]
# a named profile you can switch into

Two independent layers protect you. Permissions decide which tool calls the harness will make; they cover every tool. Sandboxing is OS-level enforcement on shell commands and their child processes. Permissions can be talked around by a convincing prompt injection; a sandbox cannot. Use both.

Rule syntax

Every rule is Tool or Tool(specifier). A bare tool name in deny removes the tool from the agent's context entirely, so it never even sees it. A scoped rule leaves the tool available and blocks only the matching calls.

Rules match each subcommand of a compound command independently, so Bash(safe-cmd *) does not approve safe-cmd && rm -rf /. Deny and ask rules also reach inside subshells, command substitutions, and loop bodies. Environment-runner wrappers such as npx, docker exec, and devbox run are not stripped — write one rule per inner command rather than trusting Bash(devbox run *).

Permission modes

Changing who reviews a request never widens the sandbox — the two are separate dials. In the Codex CLI, /permissions manages both.

{
  "permissions": {
    "deny": [
      "Read(./.env)", "Read(./.env.*)",
      "Read(./**/credentials.json)", "Read(~/.ssh/**)",
      "Bash(curl:*)", "Bash(git push --force:*)"
    ],
    "ask": ["Bash(git push:*)", "Bash(gh pr merge:*)"],
    "allow": [
      "Bash(pnpm install)", "Bash(pnpm run:*)",
      "Bash(git status)", "Bash(git diff:*)", "Bash(git log:*)"
    ],
    "defaultMode": "default",
    "disableBypassPermissionsMode": "disable"
  }
}

A hook is a shell command bound to an event. It runs whether or not the model thought of it, which is precisely why it is the right home for formatting, secret scanning, and any rule you have written into CLAUDE.md twice and watched get skipped anyway.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          { "type": "command", "command": "pnpm exec prettier --write \"$CLAUDE_FILE_PATHS\"" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scan-secrets.sh" }
        ]
      }
    ]
  }
}

There are around thirty events in total, covering permission decisions, task lifecycle, model switches, worktrees, config changes, and MCP elicitation. The full list is in the hooks reference; the twelve above cover most real setups.

The exit-code contract

#!/usr/bin/env bash
# PreToolUse hook: refuse commands that would print a secret file.
set -euo pipefail

payload="$(cat)"                       # hook input arrives on stdin as JSON
command="$(jq -r '.tool_input.command // ""' <<<"$payload")"

if grep -Eq '(^|[[:space:]])(cat|less|head|tail)[[:space:]]+.*\.env' <<<"$command"; then
  echo "Refusing: this command would print .env to the transcript." >&2
  exit 2
fi
exit 0

The failure mode of agent-assisted work is not bad code — it is unbounded work. A stage that never declares itself finished quietly turns into a 40-file diff nobody can review. Give every stage an input, a deliverable, and a criterion that says when it is done.

Plan before you let it write

Plan mode is the highest-leverage habit in the whole handbook. The agent reads and explores but cannot edit, so you get to inspect the intent before the diff exists — and a bad plan costs you thirty seconds instead of a revert.

# Claude Code — Shift+Tab cycles the permission mode, or:
claude --permission-mode plan

# Persist it as the default for a risky repository, in .claude/settings.json:
#   { "permissions": { "defaultMode": "plan" } }

# Codex — review without touching the working tree:
codex review

A plausible implementation is not a verified one. A gate is a check with a binary outcome that must pass before work advances — compile, test, lint, type-check, security scan, and a review pass that did not write the code.

Ask for a review that is falsifiable

"Review this code" produces a list of style opinions. Demand a concrete failure scenario for every finding and the list gets short, specific, and worth reading.

Review the uncommitted diff for correctness only — not style.

For each finding give exactly:
  1. file:line
  2. the inputs or state that produce the wrong behaviour
  3. the observable wrong result
  4. the smallest fix

Rank by severity. If a finding is a guess, label it PLAUSIBLE, not CONFIRMED.
If you find nothing, say so in one line. Do not pad the list.

Both tools ship review entry points: /code-review and the ultrareview and Code Review integrations in Claude Code, and codex review plus /review in Codex. Use them for the first pass, and read the diff yourself for the second — the review is a filter, not a substitute.

Both tools are composable Unix programs. Piping into them and running them from CI is where the time actually comes back — the interactive session is for work that needs judgement, and everything else should be a script.

# Claude Code — one-shot, prints and exits
claude -p "translate new strings into French and open a PR"

# Feed it a stream
tail -200 app.log | claude -p "summarize anomalies as a bullet list"
git diff main --name-only | claude -p "review these files for security issues"

# Codex — the same shape
codex exec "add a regression test for the null-tenant bug"
codex resume            # pick up where a previous run stopped

Rules for unattended runs

1. Deny by default — Run in dontAsk mode with an explicit allowlist, or a Codex permission profile scoped to what the job needs. A run with nobody to answer a prompt should fail closed, not proceed.
2. Sandbox it — A container or an ephemeral VM, with no production credentials mounted. The blast radius should be the checkout, and nothing else.
3. Bound the run — maxTurns on subagents, a job timeout in CI, and a token budget. An agent in a loop is expensive long before it is dangerous.
4. Produce a reviewable artefact — A pull request, not a push to main. The output of an unattended run is a proposal.
5. Keep the trace — Log which context loaded, which commands ran, and what failed. Without the trace an unattended failure is unexplainable.

Parallelism pays when tasks are genuinely independent — three separate bugs, or one review split across dimensions. It costs when they are not: two agents in one working tree will overwrite each other, and merging their reasoning is slower than doing the work once.

The isolation primitive is the git worktree: a second checkout of the same repository on its own branch, in its own directory. Each agent gets a real filesystem it cannot share, and you merge through the normal review path.

git worktree add ../repo-auth-fix -b fix/auth-refresh
git worktree add ../repo-perf   -b perf/query-plan
git worktree list
git worktree remove ../repo-auth-fix   # when the branch has merged

Claude Code automates this. A subagent with isolation: worktree in its frontmatter runs in a temporary worktree that is cleaned up if it changed nothing. .worktreeinclude in the project root lists the gitignored files — .env.local, build caches — that must be copied into each new worktree for the project to actually run there.

Codex approaches the same problem from the cloud side: start several cloud tasks in parallel and bring each result back into your checkout with codex apply. The isolation is the remote environment rather than a local worktree, and the merge point is still a reviewed diff.

Prompts, instruction files, and tool definitions are code with no test suite by default. A change that feels like an improvement can quietly break a behaviour you relied on, and you will not find out until it costs you an afternoon.

A minimal eval loop

1. Collect real failures — Every time you correct the agent, save the task and the wrong output. Ten of these is already a useful suite.
2. Write the expected behaviour, not the expected text — "Refuses to widen the permission scope" is checkable. "Says the right thing" is not.
3. Re-run the set after every configuration change — New rule, new skill, new model — the same ten tasks, and you compare.
4. Grade deterministically where you can — Exit codes, file diffs, and "did it touch a forbidden path" beat a subjective judgement every time.
5. Keep the trace, not just the verdict — Which context loaded, which tool ran, where it turned wrong. A failed eval with no trace tells you nothing actionable.

Observability

/context shows what is loaded right now. The InstructionsLoaded hook logs which instruction files loaded, when, and why. claude doctor prints the fully resolved configuration and flags rules it had to skip. Between them you can answer nearly every "why did it do that?" question without guessing.

Cost and context discipline

Vocabulary