Claude Code Best Practices for Teams, From Our Own PRs

The Claude Code best practices that moved our numbers most are: keep pull requests small, give the agent a check to run, keep CLAUDE.md short, use hooks for rules that can’t bend, and judge the result on what merged. On our team, PRs under 100 lines were flagged in review 11% of the time, and PRs of 1,000 to 2,999 lines 57%. No model switch came close to that.

Most lists of Claude Code tips are written for one person at a keyboard. This one is for a team that already pays for it and wants the same results from every engineer. Each practice comes with what we measured on the pull requests merged in our two repositories, 866 of them carrying an agent-written session block and 1,232 with a readable review, or with what Anthropic’s own best-practice docs say, read on November 4, 2026. Those docs now open with a useful line: in most cases your first plain prompt in a fresh session already does the right thing. So this is about what the defaults can’t know.

1. Ask for small pull requests

An agent will happily write 2,000 lines. Reviewers, human or AI, can’t keep up.

This table covers all 1,232 reviewed PRs with a readable first pass, leaving out release PRs, and the reviewer is our sister product, IonWarp. Above 3,000 lines the rate stops rising, partly because the reviewer reads a capped slice of a very large diff. Matched on repository, engineer and week, PRs of 1,000 lines or more were flagged 36 points more often than PRs under 300 lines (95% interval +27 to +43). The same matching mostly erased the gap between models. So a line in your team’s CLAUDE.md asking for one change per PR is worth more than any debate about which model to use. See best model for coding.

2. Give it a check to run

Claude stops when work looks done. With nothing that returns pass or fail, you are the test suite. A test file, a build’s exit code, a linter or a script that diffs against a fixture all work.

86% of our PRs with a session block touched a test file, against 61% of the PRs merged in the same weeks without one. That isn’t proof tests cause anything, but it is how agents behave when the repo makes testing easy. Local testing took 29% of our agents’ session minutes, and the agents named vitest, bun test, Playwright and pytest most often. Put the exact commands in CLAUDE.md, including how to run a single test file.

3. Keep CLAUDE.md short, and in the repo

CLAUDE.md loads into every session, so every line takes a little attention on every task. Anthropic’s test for a line: Claude couldn’t work it out from the code. That leaves four kinds:

• How to confirm work: exact test, typecheck and lint commands.
• Where the code misleads: an old pattern new code must not copy.
• Decisions that aren’t in the repo: how deploys work, what needs a migration review.
• Anything you’ve had to correct twice.

Keep it under 200 lines. /init drafts one, /doctor suggests cuts, and CLAUDE.local.md (in .gitignore) holds personal preferences. Commit the shared file and review changes to it like code, since it steers every engineer’s agent. You no longer need to describe your architecture or file layout there: Claude reads the repo itself.

4. Use hooks for rules that can’t bend

An instruction in CLAUDE.md is one Claude usually follows. A hook, a deny rule or a managed setting is applied by Claude Code every time. Anthropic’s own rule of thumb: if you keep adding emphasis to a line and it still gets missed, it belongs in a hook.

{
  "permissions": {
    "deny": ["Read(./.env)", "Bash(git push *)"]
  },
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "bun run typecheck 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

That goes in .claude/settings.json. Those deny rules have limits: Bash(git push *) matches the command text, so git -C . push gets past it, and Read(./.env) doesn’t stop a script that opens the file itself. Anthropic points to the sandbox or a PreToolUse hook when that matters, and branch protection on GitHub is the real guard for your main branch. The Stop hook refuses to let the session finish while the typecheck fails: exit code 2 blocks the stop, and what it prints to stderr goes back to Claude as the reason. If the check can fail for reasons Claude can’t fix, the hook should read stop_hook_active from its input and let the session end, or it can loop. Our hooks guide has more patterns. For rules that must hold across every repo, use managed settings instead. And delete hooks that only enforce preferences. Those can stay as guidance.

5. Put team procedures in skills

Your release steps and incident runbook go in .claude/skills/<name>/SKILL.md. A skill loads only when the task calls for it, so a long procedure doesn’t weigh on an unrelated bug fix the way it would in CLAUDE.md. Our skills guide shows the format.

Then check what’s actually used. In one engineer’s 323 sessions, the Stripe plugin, enabled the whole time, used none of its 10 skills or its MCP tools. /usage breaks recent usage down by skill, subagent, plugin and MCP server, so an audit takes a minute.

6. Don’t chase models. Do record them

Our default model changed twice in four weeks, and every switch felt important at the time. Matched on engineer, repository and week, Codex against Claude Code came out +1 point on review flags (95% interval −16 to +20, 24 PRs against 162), Opus 5.5 against Fable 5.1 −7 points (−30 to +15). Those intervals are too wide to act on.

Leave the default alone until you have a reason, and record which model ran. Effort is the setting to reach for first: Opus 5.5, Sonnet 5.5 and Haiku 5.5 default to medium, Anthropic says to raise it for bugs in code you didn’t write and schema changes, and max tends to overthink on ordinary tasks. Phrases like “think harder” aren’t controls: they are ordinary prompt text.

7. Clear between tasks and watch where tokens go

Cache reads were 98.4% of one engineer’s 67.9 billion tokens in a month and 57% of the list-price cost. Every turn re-reads the conversation, so /clear between unrelated tasks is the cheapest habit there is. Subagents took 34% of that month’s cost: give simple ones model: haiku. The full breakdown, with what a cold cache costs, is in our guide to Claude Code token usage.

8. Get a second reader

A fresh reviewer helps because it hasn’t seen how the code was written. Delegating the same task to a subagent doesn’t make the answer better, but a separate session or /code-review reading the finished diff catches things.

In the 30 days to October 4, 58% of our reviewed PRs got at least one fix round from the agent. Of the 2,273 findings the agents answered, they fixed 80%, declined 18% and handed 1.6% to a human. So decide up front who has the last word, and keep it deterministic: branch protection and a person who approves the merge, rather than Claude’s summary of what it did.

9. Run parallel work in worktrees

claude -w feature-auth starts a session in its own worktree, so edits can’t collide. A worktree is a fresh checkout, so gitignored files such as .env aren’t there and dependencies aren’t installed. List the small files to copy in .worktreeinclude, and keep the install command in CLAUDE.md.

10. Ask the agent to write down what happened

This one is ours, and it’s where our harness, model and time numbers come from. We ask the agent, in CLAUDE.md, to end each pull request description with a short block:

harness: Claude Code (Opus 5.5)
intent: Add rate limiting to the login endpoint
session_flow:
  planning_min: 3
  coding_min: 10
  local_testing_min: 5
dev_testing:
  - tool: vitest
    detail: 10 files
task:
  type: feature   # design | feature | bug | refactor | infra | docs

It costs a few lines per PR and no tooling. In about eight weeks it gave us the harness and model of 866 PRs, the time per phase on 398 of them, and the kinds of work. The minutes are the agent’s own estimate, so don’t read them as a stopwatch. It also showed that coding was only 43% of session minutes. Planning and local testing together were half.

11. Measure on merged work, not on activity

Decide what good looks like before you roll out further: cost per merged PR, the share flagged on first review, fix rounds, how many engineers used it this week. Don’t score people on tokens, for the reasons in why token counts mislead engineering teams.

For the raw data, see Claude Code monitoring with OpenTelemetry or the four ways to see team usage. Zest does the join for you: each engineer’s sessions, models and skills next to the pull requests they led to.

What you can stop doing

Anthropic’s docs now list habits that newer models made unnecessary. The ones we see most on teams:

Caveats

• One small team, two repositories. This is how we work, not a sample of the industry.
• Agent-written labels. Harness, model and minutes come from a block the agent writes.
• Our own reviewer. Flag rates come from IonWarp, our sister product, and it changed during the window.
• Docs move. Anthropic’s advice was read on November 4, 2026, and changes with each release.

Frequently asked questions

What are the most important Claude Code best practices?

Keep pull requests small, give Claude a check it can run, keep CLAUDE.md short and committed, enforce rules that can’t bend with hooks or deny rules, and clear the session between unrelated tasks. On our team, pull request size moved review findings far more than the choice of model did.

How long should CLAUDE.md be?

Anthropic recommends under 200 lines, holding only what Claude can’t work out from the code: test and build commands, misleading patterns, decisions that aren’t in the repo and anything you have corrected twice. Longer procedures belong in skills, which load on demand.

How should a team set up Claude Code?

Commit a short CLAUDE.md and .claude/settings.json to each repo, put shared procedures in .claude/skills, and use managed settings for anything that must apply everywhere, such as deny rules and telemetry. Then measure on merged pull requests.

Should we use Opus or Sonnet in Claude Code?

Start with the default, Opus 5.5, and use Sonnet where work is routine: Sonnet 5.5 costs half per token. On our repositories, once we compared the same engineer and week, the gap between models in review findings mostly disappeared. Test on your own work before you standardize.

How big should a Claude Code pull request be?

As small as the change allows. Our reviewer flagged 11% of pull requests under 100 lines, 23% at 100 to 299, 45% at 300 to 999 and 57% at 1,000 to 2,999. Those counts come from 1,232 reviewed pull requests in two repositories.

Do Claude Code best practices work for Codex and Cursor?

Most do. Small pull requests, a check to run and hooks apply to any agent. Instructions go in AGENTS.md for Codex, and Cursor also reads CLAUDE.md. See Claude Code vs Codex and Claude Code vs Cursor.