Team Conventions for Claude Code

Claude Code works best for teams when the repo teaches it how the team works before anyone asks for code. Start with shared context, review expectations, permission boundaries, and a small operating checklist that supports ai code solutions for diverse coding skills teams.

Claude Code, Anthropic's coding agent, is most useful when it has durable repository memory instead of one-off prompts. A Claude Code team convention is a written rule or workflow artifact that makes the agent behave predictably across engineers, branches, and reviews.

As of June 20, 2026, the official Claude Code changelog lists Claude Code 2.1.185. The useful team habit is simple: every meaningful tool update should trigger a quick check of your Claude Code workflow, not a scramble to rewrite how your team ships software.

Set the shared context before the agent starts

Put durable rules in CLAUDE.md. This is where Claude Code should learn the repo shape, the test commands, the migration policy, and the things your reviewers care about every time.

Good Claude Code training usually starts here because CLAUDE.md is not a prompt trick. It is shared repository context. For a Rails app, that might mean telling Claude to run focused model specs before controller specs, never edit generated schema by hand, and ask before changing background job retry behavior.

Keep the file short enough that humans will maintain it. The trap is turning CLAUDE.md into a dusty handbook with every preference the team has ever debated. Durable rules belong there; task-specific instructions belong in the chat, a slash command, or a skill.

If you are building a wider adoption plan, keep this tied to the related training topic so engineers learn the convention, not just the file name.

Keep conventions scoped to where work happens

Use local context when different parts of the repo have different rules. A mobile app, an API service, and an infra directory should not share the same testing and deployment assumptions just because they live in one monorepo.

A practical pattern is a root CLAUDE.md for company-wide rules, then smaller scoped files near the work. The root might say “never commit secrets” and “prefer small PRs.” The service-level file can say “database migrations require rollback notes” or “payments code needs a security reviewer.”

This matters because Claude Code for teams should reduce coordination cost, not flatten real ownership. The trap is one giant root memory file that quietly lies about half the repo.

For review-heavy repos, pair this with an explicit review workflow like A Team Claude Code Review Workflow. The point is to make review expectations visible before the agent edits code.

Put automation at the trust boundary

Use hooks for checks that should run consistently, not for every nice-to-have preference. A hook can run formatting, block obviously unsafe file edits, or remind the user when generated artifacts changed.

For example, a team might allow Claude Code to edit application code freely, but use a hook to stop changes under infra/prod unless the task says production infrastructure is in scope. That is a clean boundary. It turns a social rule into a repeatable guardrail.

The trap is using hooks as a second reviewer for everything. Hooks should be boring, fast, and legible. If a hook becomes a maze of hidden policy, engineers will route around it, and the agent will not know why work keeps failing.

Use MCP and skills as team assets

Use Model Context Protocol servers when Claude needs trusted access to external systems such as GitHub, Jira, Slack, docs, or a private knowledge base. MCP is an integration layer that lets tools expose context and actions to AI clients in a structured way.

For Claude Code agent teams, keep MCP permissions narrow. A read-only docs server is a very different risk from a server that can mutate tickets, merge PRs, or query production data. Write down what each server may access, who owns it, and what tasks it supports.

Use Claude skills for reusable workflows that are bigger than memory but smaller than an app. A skill can package a migration review checklist, an incident writeup format, or a release note workflow. The trap is stuffing procedural playbooks into CLAUDE.md; use memory for rules and skills for repeatable capabilities.

Slash commands fit nicely between the two. They are great for team rituals like /prep-pr, /write-test-plan, or /summarize-risk when you want a consistent prompt surface without building a full skill yet.

Adopt it when review habits are ready

Claude Code conventions are worth adopting when a team already knows what “good” looks like for a PR. If reviewers disagree on testing, ownership, or acceptable risk, the agent will amplify that ambiguity.

Start with one repo and one workflow: bug fixes, dependency upgrades, test repair, or PR prep. Measure whether the convention helps engineers produce smaller diffs, clearer review notes, and fewer avoidable back-and-forth comments.

Do not overbuild this for a throwaway prototype, a repo with no clear owner, or a team that is still changing architecture every week. In those cases, use lightweight prompts and keep durable memory minimal until the shape of the work settles.

Copyable starter checklist for Claude Code teams

Paste this into a new docs/claude-code-team-checklist.md, then link it from your root CLAUDE.md. Keep it boring. Boring is what makes it survive the second week.

# Claude Code team checklist

## Repository memory
- [ ] Root CLAUDE.md explains the app, owners, test commands, and review expectations.
- [ ] Scoped CLAUDE.md files exist for areas with different rules, such as infra, payments, mobile, or data.
- [ ] Durable rules are in memory; task-specific instructions stay in chat, slash commands, or skills.

## Review expectations
- [ ] Every Claude-assisted PR includes a short summary of intent, files changed, and test evidence.
- [ ] Risky changes name the risk directly: data migration, auth, billing, security, production infra, or public API.
- [ ] Reviewers can tell which checks were run without reading the whole session transcript.

## Hooks
- [ ] Formatting and fast tests run through hooks where they are reliable.
- [ ] Hooks protect high-risk paths such as infra/prod, generated files, or secrets.
- [ ] Hook failures explain the fix in plain language.

## MCP permissions
- [ ] Each MCP server has an owner and a written purpose.
- [ ] Read-only access is preferred unless mutation is clearly needed.
- [ ] Production data access is denied by default and documented separately if allowed.

## Skills and commands
- [ ] Repeated workflows have a slash command or Claude skill instead of a copied prompt.
- [ ] Skills include activation guidance, inputs, expected output, and review notes.
- [ ] Old skills and commands are removed when the workflow changes.

## Adoption
- [ ] Start with one repo and one workflow.
- [ ] Review the checklist after each Claude Code changelog item that affects team workflow.
- [ ] Retire rules that no one follows.

Common questions

• How should we set up Claude Code for a team?

  Start with a root CLAUDE.md, one scoped convention file for the highest-risk area, and a review checklist every PR can follow. That gives the agent shared memory, the engineer a clear workflow, and the reviewer evidence to check. Add hooks and MCP only after the first workflow is stable.

• What belongs in CLAUDE.md versus a skill?

  Put durable repository rules in CLAUDE.md and repeatable procedures in a Claude skill. A rule is “run payment tests before changing billing code.” A skill is “prepare a billing migration review packet.” If the content has steps, inputs, and an expected output, it probably wants to be a skill.

• Are hooks required for Claude Code teams?

  Hooks are not required, but they are useful when a rule should be enforced every time. Use them for fast, objective boundaries like formatting, protected paths, or generated-file checks. Avoid hooks for subjective review decisions, because those belong in the PR conversation where humans can explain tradeoffs.

• How much MCP access should Claude Code have?

  Give Claude Code the least MCP access that still completes the workflow. Read-only documentation or issue access is a safe starting point; write access to tickets, repositories, or production systems needs explicit ownership and audit expectations. Treat each MCP server like a real integration, not a convenience toggle.

• When should we not use a formal Claude Code workflow?

  Skip the formal workflow for short-lived spikes, unstable prototypes, and repos without clear owners. In those cases, heavy conventions create maintenance work before they create value. Use lightweight prompts, keep memory small, and write the durable rules only after the team repeats the same decision a few times.

Further reading

• Claude Code — getting started
• Claude Code — skills
• Claude Code — hooks
• Claude Code — permissions
• Model Context Protocol — specification
• Anthropic — Claude Code product page
• GitHub — anthropics/skills
• Claude Code — changelog

Start with one convention

Pick one repo, write the smallest useful CLAUDE.md, and require a review note that says what Claude changed and what was tested. Once that habit sticks, add hooks, MCP, and skills where they remove real friction.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.