Claude Code best practices for a team: 7 that hold

The Claude Code best practices that matter for a team are not prompting tips. They are seven rules that hold even when nobody is watching: a short CLAUDE.md that CI keeps short, one shared plugin, permissions and hooks in the repository, one issue to one PR, a test that fails first, and a reviewer that did not write the code. Each one is enforced by a file or a check, not by memory.

We run every repository this way, and AI writes all of our code today. The rest of this article is how each practice is enforced, with the real files.

Which Claude Code practices hold in a team?

Solo tips live in one person's head. A team practice needs a place where it is written down and a check that notices when it breaks:

Read the table as an order, too. The first four cost an afternoon. The last three change how work flows.

1. Why keep CLAUDE.md short, and how do you enforce it?

CLAUDE.md and every always-loaded rule file go into context on every request. Anthropic's cost guide suggests keeping it under 200 lines and moving workflow instructions into skills, which load only when used.

"Keep it short" lasts about two weeks. So our validator counts it. It adds up CLAUDE.md and every always-loaded rule together, which is why its ceiling is 300 lines, not 200:

# CLAUDE.md + every .claude/rules/*.md that loads on every session
# (rules scoped with `paths:` load only under matching paths and are skipped)
if [ "$total_lines" -gt 300 ]; then
  log_critical "Context budget exceeded: $total_lines lines (max 300)."
fi

It runs in CI in every repository. In company and client repositories it fails the build, in code repositories it warns.

The other half is where a rule goes. Personal working style belongs in ~/.claude. Anything the whole team must follow belongs in the repository.

How to split rules between CLAUDE.md, AGENTS.md and personal files is covered in detail in Rules for AI code in a team.

2. Why one shared plugin instead of copies?

We used to copy our planning, build and review skills into each repository. Within weeks the copies drifted apart, and some were empty stubs. Discipline did not fix it. One plugin did: wizrd, our internal Claude Code plugin and CLI (not public). Skills, agents and hooks live in one repository, and every other repository enables it in two lines of settings:

{
  "enabledPlugins": { "wizrd@digitaliko": true },
  "extraKnownMarketplaces": {
    "digitaliko": { "source": { "source": "directory", "path": "services/wizrd" } }
  }
}

A fix to the review skill now reaches every session the next time it starts. How we structure the plugin itself is in Claude Code skills and plugins for a team.

3. Why put permissions in the repository?

Because a deny in the repository beats an allow anywhere else. Claude Code checks deny rules first, then ask, then allow, across every settings file. So the team decides once, in .claude/settings.json: deny .env files and keys, ask before a push, a merge or a deploy, allow the scripts the agent needs to check its own work.

Everything personal stays in ~/.claude/settings.json. The shape and our exact entries are in Claude Code dangerously-skip-permissions: when is it safe?.

4. Why block with hooks instead of asking in CLAUDE.md?

A sentence in CLAUDE.md is a request. On one day in October an agent typed an AI attribution footer into several pull request bodies in our own repositories, in a session whose CLAUDE.md forbade exactly that in plain words.

The fix was a PreToolUse hook that scans every git commit, gh pr and gh issue command, including files passed with --body-file, and exits 2. The comment at the top of the script says it best: "A rule is a request. This is the lock."

Hooks have their own failure mode: they can go silent and still pass. The four checks that catch it are in Claude Code hooks that silently do nothing.

5. Why one issue to one PR?

An agent session forgets. A GitHub issue does not. Every task starts as an issue with what "done" means, written so a reviewer can answer yes or no, and ends as one pull request with Closes #N.

That gives three things a chat session cannot. The plan is visible before the work starts. Two agents can work in parallel, each in its own git worktree on its own branch, without touching each other. And the merged pull requests are the changelog, so nobody writes a worklog.

Plan mode helps inside the session. Where it stops being enough for a team is in Claude Code plan mode: when is it enough?.

6. Why must the test fail first?

An agent can write tests that pass whether the code works or not. So our gate runs the new or changed tests against the base branch, before the fix. If they pass there too, they prove nothing, and the pull request goes back. Only a test that is red without the change and green with it counts. The whole mechanism is in Red-green TDD with AI agents.

7. Why should a different agent review the code?

The author agent has already convinced itself. A fresh session that only reads the diff finds what the author skipped. Our CI reviewer gets a read-only tool list (git diff, git log, gh pr diff, Read, Grep) and a review checklist from the repository. It comments. It never approves. Branch protection requires a person, so the merge is always a human decision. Setup and prompt are in Claude Code review in CI.

Where should a team start?

Not with all seven at once. The order that worked for us:

The first three take a day in an existing repository. The fourth is a habit, and it takes a few weeks of review comments before the team writes issues that an agent can finish without asking.

How far is your team today?

Count what is already in your repositories, not what people say they do:

You can copy the settings, hooks, gate and review workflow from our Claude Code production starter, MIT licensed.

Want these practices running in your repositories?

We set them up right in a team's repositories, together with the developers, as part of AI-native SDLC for development teams. AI writes all of our code today, and a senior is accountable for the result. Since 2023 we have delivered 15+ production projects.

We get back to you within two business days, and together we pick what to fix first.

If you'd rather talk first, book a 15-minute meeting with Filip.

Which of the seven would break first in your team if nobody checked?

Frequently asked questions

What are the most important Claude Code best practices?

For a team: keep CLAUDE.md short and enforce the limit, share skills and hooks as one plugin, put permissions in the repository, block with hooks instead of asking in prose, take one issue to one PR, prove each change with a test that fails first, and let a different agent review it before a person merges.

How long should CLAUDE.md be?

Short enough that it pays for itself on every request. Anthropic suggests under 200 lines. We count CLAUDE.md plus every always-loaded rule file together and fail CI above 300 lines in our company and client repositories.

Should Claude Code settings be committed to git?

The team part, yes: .claude/settings.json with permissions and hooks belongs in the repository. Personal preferences go in ~/.claude/settings.json and local overrides in .claude/settings.local.json, which stays out of git.

How do you share Claude Code skills across a team?

As a plugin that every repository enables in its settings. Copies of skills in each repository drift apart within weeks; one plugin gives every session the same skills, agents and hooks.

Is plan mode a best practice for every task?

For exploring before a bigger change, yes. For a team, the plan also has to live somewhere others can read it, such as the issue with its acceptance criteria, not only in one developer's session.