Claude Code best practices, with data from 1,000 repos

Updated 9 min read

The Claude Code practices that pay off at work come down to three habits: give Claude a check it can run, keep its context window clean, and write down what it needs in files the whole team shares. In practice that means a short CLAUDE.md with your build and test commands, plan mode before multi-file changes, /clear between tasks, few and well-scoped MCP servers, permission rules instead of clicking through prompts, hooks for anything that must always happen, and a shared place for what sessions learn.

Everything below comes from Anthropic’s best practices page and related docs as read on 12 October 2026, checked against a scan we ran on 1 October of the 1,000 most-starred GitHub repositories pushed since 1 July 2026 (the smallest has 29,547 stars).

What are the Claude Code best practices?

  1. Give Claude a way to verify its work.
  2. Keep CLAUDE.md short, with the commands Claude cannot guess.
  3. Explore and plan before editing.
  4. Manage the context window: /context, /clear, /compact.
  5. Connect few MCP servers, at the right scope.
  6. Set permissions once instead of approving every action.
  7. Use subagents for research and review, skills for repeat workflows.
  8. Use hooks for checks that must run every time.
  9. Commit the team’s .claude setup.
  10. Keep what sessions learn where the next session and your teammates can read it.

How do I give Claude a way to verify its work?

Claude stops when the work looks done, so without a check it can run, you become the check. Give it a test suite, a build, a linter or a screenshot to compare, and ask it to iterate until the check passes.

The docs describe four levels:

  • In the prompt: “write a test for the logged-out case, run the suite and fix failures”.
  • Across a session: set the check as a /goal condition, which a separate evaluator re-checks after every turn.
  • As a gate: a Stop hook runs your check as a script and blocks the turn from ending until it passes. Claude Code overrides a Stop hook after eight consecutive blocks, so the script should check stop_hook_active.
  • As a second opinion: a verification subagent reviews the result in a fresh context.

Ask for evidence too: the command Claude ran and its output.

Of the 124 real CLAUDE.md files in our scan (stubs and one-line pointers excluded), 90 give build or test commands, so in the other 34 Claude has to work out how to run the project.

What should a CLAUDE.md contain?

Run /init to generate a starter file from your codebase, then cut it down. Anthropic’s test for every line: “Would removing this cause Claude to make mistakes?” Keep bash commands Claude cannot guess, style rules that differ from defaults, test instructions, branch and PR conventions, and gotchas. Leave out what Claude can learn by reading the code, file-by-file tours and anything that changes often.

An illustration for a made-up TypeScript project, not a file from our scan:

# Commands
- Build: `pnpm build`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Typecheck before you finish: `pnpm tsc --noEmit`

# Rules
- Never edit files in `src/generated/`; run `pnpm codegen`
- API handlers live in `src/api/handlers/`

The memory docs say to target under 200 lines per file, since longer files cost context and reduce adherence. Real files sit well inside that: the median of the 124 in our scan is 117 lines. Of those 124, 93 describe the architecture and 99 list things not to do. Run /context to confirm the file loaded. /doctor prompt-audit (v2.1.283 or later) finds stale or conflicting instructions and changes nothing until you approve.

Three details from the docs:

  • Rules that matter for part of the codebase go in .claude/rules/ with a paths: frontmatter list, so they load only when Claude works on matching files. @path imports organize a long file but still load at launch.
  • Block-level HTML comments in CLAUDE.md are stripped before Claude sees them, so maintainer notes cost no tokens.
  • If a repository has both files, Claude Code reads only the CLAUDE.md by default and skips AGENTS.md. In our scan, 365 repositories have an AGENTS.md and 213 have both. If yours is one of them, put @AGENTS.md at the top of CLAUDE.md.

Our CLAUDE.md guide covers scopes and imports, and CLAUDE.md examples shows the full scan.

When should I use plan mode?

Use it when you are unsure of the approach, when the change touches several files, or when you do not know the code. Press Shift+Tab until the status bar shows plan mode, or start with claude --permission-mode plan. Claude reads and answers without editing. Ask for a plan, press Ctrl+G to edit it in your editor, then approve it and let Claude implement against it. Anthropic’s own rule for skipping it: if you could describe the diff in one sentence, skip the plan.

For larger features, have Claude interview you with the AskUserQuestion tool and write a SPEC.md, then build from it in a fresh session.

How do I manage the context window?

Anthropic calls context the most important resource to manage, because performance degrades as the window fills. The commands:

/context                          see what is using the window
/clear                            reset between unrelated tasks
/compact Focus on the API changes summarize, with your instructions
/rewind                           restore, or summarize from a checkpoint
/btw what does this flag do?      ask without adding to history

The docs give two rules that cover most cases: run /clear between unrelated tasks, and if you have corrected Claude more than twice on the same issue, /clear and start again with a better prompt, since the context is now full of failed attempts. A line in CLAUDE.md such as “When compacting, always preserve the list of modified files and the test commands” steers automatic compaction.

Our context window guide covers window sizes and what survives compaction.

How many MCP servers should I connect?

Only the ones you use in this project. claude mcp add writes to local scope by default: private to you, in this project only, stored in ~/.claude.json. --scope user makes a server available in all your projects, and --scope project writes it to .mcp.json for the team to commit.

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http --scope project <name> <url>

MCP tool search is on by default, so only tool names and server instructions load at session start, and full tool definitions load when Claude needs them. Toggle off servers you are not using in the /mcp panel; the configuration stays. Where a CLI exists, Anthropic calls it the most context-efficient option: install gh and Claude uses it for issues and pull requests. More in our Claude Code MCP guide.

How should I set up permissions?

With Claude Code v2.1.283 or later, auto mode is the starting permission mode for interactive terminal and VS Code sessions: a classifier reviews most actions and blocks what looks risky. On earlier versions it is the starting mode only on Pro, Max and Team plans. In Manual mode Claude asks before every write, command and MCP call, and by the tenth approval you are no longer reading them. Two tools cut prompts in both modes: allow rules set with /permissions, and /sandbox for OS-level isolation of filesystem and network access.

Choosing “Yes, and don’t ask again” saves an allow rule to .claude/settings.local.json, which stays yours. Rules the whole team needs, such as allowing npm run test * and denying reads of .env, belong in the committed .claude/settings.json. One limit: permissions.defaultMode set to auto or bypassPermissions does not take effect from project or local settings, only from user or managed settings.

When should I use subagents and skills?

A subagent runs in its own context window and reports back a summary, so the files it reads never fill yours. Use one for investigation (“use subagents to investigate how token refresh works”) and for review. The bundled /code-review skill checks the current diff in a fresh subagent. Anthropic warns that a reviewer asked for gaps will usually find some, so tell it to report only gaps that affect correctness or the stated requirements.

Define a reusable subagent in .claude/agents/:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
Review the diff for injection, auth flaws and secrets. Cite lines.

Skills live in .claude/skills/<name>/SKILL.md. Claude loads them when relevant, or you run one with /name. Add disable-model-invocation: true to any skill with side effects, such as deploys, so it runs only when you type it. Skills are what teams share most: of the 173 repositories in our scan with a .claude directory, 124 hold skills, 37 commands and 32 agents.

For parallel work, worktrees give each session its own git checkout so edits do not collide. Agent teams, where a lead session coordinates teammates through shared tasks and messages, are experimental and disabled by default. For review, Anthropic’s simpler Writer/Reviewer pattern uses a fresh session, which is not biased toward code it just wrote.

What should hooks do?

Hooks are scripts Claude Code runs at fixed points, every time, while CLAUDE.md is advice Claude may skip. This one, from Anthropic’s hooks guide, formats every file Claude edits:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

A PreToolUse hook blocks an action whatever Claude decides, and for a rule that must never be broken the memory docs point to one instead of a line in CLAUDE.md. A Stop hook can hold the turn open until tests pass. Claude can write hooks for you, and /hooks lists what is configured. In our scan hooks tie with rules as the least used: only 20 of the 173 .claude directories contain hooks.

What should the team commit?

Commit CLAUDE.md, .claude/settings.json, .mcp.json, and the skills, agents and rules under .claude/. Keep personal overrides in .claude/settings.local.json and CLAUDE.local.md. In our scan, 173 of the 1,000 repositories have a .claude directory and 64 of those commit a settings.json. Seats, settings precedence and what an admin can enforce are in our Claude Code team setup guide.

Where should Claude Code keep what it learns?

Claude Code’s auto memory saves notes from your corrections to ~/.claude/projects/<project>/memory/: a MEMORY.md index, whose first 200 lines or 25KB load into every session, and one topic file per memory. The docs say it is machine-local. Worktrees of one repository share it, but other machines and cloud environments do not, so what your session learned about a flaky test stays on your laptop.

Three places can hold it for everyone:

  • CLAUDE.md or a rules file, changed by pull request. It costs nothing, gets reviewed and is versioned with the code, which makes it the better pick for small, stable lessons that fit the 200-line budget.
  • Your existing docs tool over MCP, when the knowledge already lives there. See Notion MCP and Atlassian MCP.
  • A wiki the agents write themselves. Dexio is a hosted wiki of linked markdown pages that Claude Code and a team’s other agents read, search and edit over MCP. People see what their agents know as a page graph, and every change keeps the agent and person behind it. It is open source (AGPL-3.0), free for one person, and agents never count as members. To connect, ask Claude Code to follow https://dexio.wiki/agents.md; it gives you a sign-in link to open in your browser, then adds the server at user scope.

The Claude Code memory guide compares auto memory and CLAUDE.md in more depth.

FAQ

What is the most important Claude Code best practice?

Anthropic puts verification first: give Claude a test, build or screenshot to check its own work against. It also calls the context window the most important resource to manage.

How long should a CLAUDE.md be?

Anthropic suggests under 200 lines per file. The median real CLAUDE.md in our scan of the 1,000 most-starred repositories is 117 lines.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If you have both, import it with @AGENTS.md.

Sources

Ask a question

Ask anything about Dexio.

About
We reply by email.