Blog
Claude Code best practices for teams
Published: October 24, 2026
The best practices that matter most for Claude Code all follow from one constraint: the context window fills fast, and quality drops as it does. Give Claude a check it can run, plan before large changes, keep CLAUDE.md short, clear context between tasks, and turn must-never rules into hooks. For a team, add one more: decide once, in one place.
The first half of this note condenses Anthropic's own best practices page, checked on 2026-09-23. The second half is what that page leaves to you: how the practices hold up once ten people and three different agents share a codebase.
What are Anthropic's Claude Code best practices?
| Practice | In practice |
|---|---|
| Give Claude a way to verify its work | Tests, a build, a screenshot to compare. Without a check, "looks done" is the only signal, and you become the test suite. |
| Explore, then plan, then code | Plan mode (Shift+Tab) for changes that touch several files or code you do not know. Skip it when you could describe the diff in one sentence. |
| Be specific | Name the file, the scenario and what "fixed" looks like. Point at an existing pattern to copy. |
| Keep CLAUDE.md short | Only what Claude cannot infer from the code. For each line, ask whether removing it would cause a mistake. |
| Hooks for what must always happen | CLAUDE.md is advisory; a hook runs every time. |
| Skills for what matters sometimes | Domain knowledge and workflows that load on demand instead of every session. |
| Subagents for investigation | Research in a separate context, so the reading does not fill yours. |
| Manage context aggressively | /clear between unrelated tasks. After two failed corrections, start fresh with a better prompt. |
| Review with fresh eyes | A reviewer in a new context sees the diff, not the reasoning that produced it. |
The page also names the failure patterns worth memorising: the kitchen-sink session, correcting the same mistake over and over, the over-specified CLAUDE.md, trusting output you did not verify, and exploration nobody scoped. Its verdict on the long file is blunt: when it is too long, Claude ignores half of it.
How should you write CLAUDE.md?
Start with /init and cut. Keep build and test commands, style rules that differ from defaults, repo etiquette, environment quirks and the decisions specific to this project. Leave out what the code already says, standard conventions, and anything that changes often. Use “IMPORTANT” on one line at most; emphasis on every line is emphasis on none. Size, cost and what the research says are in how long should CLAUDE.md be, and why newer models need less of it in context engineering after Claude 5.
Claude Code best practices for teams
Anthropic's list is written from one developer's chair. A team hits a different set of problems, and they are mostly about where instructions come from and whether they stay true.
| Team practice | Why |
|---|---|
| Commit the shared config, keep the personal local | CLAUDE.md, .claude/settings.json, skills and agents are team files. CLAUDE.local.md and settings.local.json are yours. |
| One source of instructions for every agent | Half the team runs Cursor or Codex. Keep the rules in AGENTS.md and import it, or they fork. |
| Review rule changes like code | A new line in CLAUDE.md changes every session on the team. It deserves the same review as a config change. |
| Write the reason next to the rule | A rule without its why gets deleted by the first person who does not know what it prevented. |
| Prune on a schedule | Rules are added after incidents and rarely removed. Put a date and an owner on each one. |
| Turn repeated corrections into rules, once | If three people corrected the agent the same way this month, that correction belongs in the shared file, not in three memories. |
Which files to commit is covered in should you commit CLAUDE.md, and the one-file-for-every-agent setup in AGENTS.md vs CLAUDE.md.
Where do the team's rules come from?
Mostly not from anyone sitting down to write CLAUDE.md. A reviewer writes “we never retry non-idempotent calls” on a pull request. A thread in #eng-payments settles the webhook retry limit at five. An ADR records why the queue moved. Each of those is a rule the agents should know, and each lives somewhere an agent never looks until a person copies it over. The gap between where a team decides and what its agents read is the gap most best-practice lists skip. More on it in turning review comments into agent rules and getting Slack decisions to coding agents. For the bigger decisions, ADRs written for AI agents carry the why with the rule, and Claude Code team memory covers which files already reach the whole team.
How do you know which practices are working?
For most of them, by watching: does the check pass, did the plan hold, did Claude stop repeating the mistake. For the rules themselves it is harder, because a rule that is never needed looks exactly like a rule that is quietly followed. Anthropic's advice is to test a change by observing whether behaviour actually shifts. That works for one file and one person. Across a team, it needs a count.
Where Harbor fits
Harbor closes the gap between where the team decides and what the agents read. It reads Slack threads, pull request reviews and docs, a person approves what becomes a fact (or a policy you set approves the routine ones), and Claude Code, Codex and Cursor are each served the approved facts that apply to the task on turn one. A correction made in one session goes back through the gate you set and then reaches everyone's agents.
It also supplies the count. Every served fact is numbered, answers cite the ones they used, and Harbor counts served against cited per fact. A rule served for months and never cited is the first one to question when you prune. A cite is evidence, not proof. See served vs cited.
Questions
What are the most important Claude Code best practices?
Give Claude a check it can run, explore and plan before large changes, be specific in prompts, keep CLAUDE.md short, clear context between tasks, and use hooks for anything that must happen every time.
How should a team set up Claude Code?
Commit the shared configuration, keep personal settings local, keep one instruction file for every agent the team uses, review rule changes like code, and prune rules on a schedule.
How long should a CLAUDE.md file be?
As short as it can be. Anthropic’s guidance is to keep only what Claude cannot infer from the code and to ask of each line whether removing it would cause a mistake.
When should I use /clear in Claude Code?
Between unrelated tasks, and after correcting the same mistake twice. A fresh session with a better prompt usually beats a long session full of failed attempts.