Team Conventions for Claude Agents

Claude Code, Anthropic's coding agent, works best on teams when you treat agents, SDK scripts, hooks, and MCP as governed repo behavior, not personal shortcuts. The right convention is simple: put durable rules in CLAUDE.md, gate risky actions with hooks and permissions, and review any claude code subagents like code.

A Claude Code team convention is a shared rule that tells humans and Claude how work should be done in a repository. For teams evaluating the claude code agent sdk, the practical question is not whether agents can act; it is how the team keeps agent work reviewable, repeatable, and safe.

Use version bumps as audit moments

The official Claude Code changelog entry for 2.1.195 is dated June 26, 2026. Without inventing details beyond that public release marker, the useful team habit is clear: every Claude Code update should trigger a short convention review.

Do not turn each release into a process rewrite. Use it as a checkpoint for the things that drift quietly: CLAUDE.md, permissions, MCP access, hooks, slash commands, skills, and subagent definitions.

A good Claude Code workflow has one owner for the convention file and many contributors to examples. In a real repo, that usually means the platform or developer-experience lead proposes changes, code owners review them, and feature teams add local notes near the code they maintain.

The trap is letting one engineer's local setup become the team's hidden operating model. If the behavior matters in review, CI, security, or production architecture, it belongs in the repo.

Put durable context in CLAUDE.md

Start with CLAUDE.md because it is the easiest place to make Claude Code feel like part of the team. Use it for stable facts: architecture boundaries, testing expectations, review style, migration rules, and where Claude should ask before changing behavior.

Keep it short. A root CLAUDE.md should explain the repo-wide contract, not every package detail. Put package-specific rules closer to the package when the local rule is stronger than the root rule.

For example, a payments service might say that Claude may edit tests and adapters freely, but must ask before changing settlement math. That is useful because it names the boundary in the same place humans already review code.

The trap is using CLAUDE.md as a prompt junk drawer. Task-specific goals, one-off bug notes, and personal preferences age badly there. Durable memory should survive the next sprint.

For a broader workshop path, this belongs in the related training topic.

Treat agents and SDK scripts as repo assets

Claude agents, subagents, and SDK-driven workflows are more like build tooling than chat prompts. They can save time, but only when the team can see what they are allowed to do, what inputs they use, and what output counts as done.

For claude code agent teams, define roles by reviewable responsibility. A test agent can propose missing coverage. A migration agent can inspect schema changes. A docs agent can update examples after an API change. Each role should have a narrow success condition.

If your team uses the Claude Code SDK to script agent work, keep the wrapper small and boring. The script should call a named workflow, pass explicit context, and leave an artifact that reviewers can inspect.

The trap is creating agent teams Claude Code users cannot reason about. If a subagent can touch unrelated files, call broad MCP tools, and auto-apply changes without a receipt, it will feel fast right up to the first confusing pull request.

Gate integrations with MCP, hooks, and permissions

MCP is the integration layer that lets Claude connect to external systems such as source control, issue trackers, databases, document stores, and internal knowledge bases. Treat MCP access like production access: name it, scope it, and review it.

A practical pattern is to separate read paths from write paths. Read-only GitHub or Jira context can be broadly useful. Write access to issues, branches, deployments, or customer data should require an explicit team convention and a human review step.

Hooks are the guardrails around the workflow. Use them to block dangerous edits, require tests before completion, or remind Claude to include a receipt. If you want a deeper hook pattern, see Claude Code Hook Conventions.

The trap is making hooks too clever. A hook should enforce a boundary, not become a second agent with hidden judgment. Keep the rule easy to explain in a code review comment.

Paste this team convention

Use this as a starter artifact. Put the first section in root CLAUDE.md, then split package-specific rules into nested CLAUDE.md files as your repo grows.

# Claude Code team convention

## Purpose
Claude Code may help with implementation, tests, refactors, docs, and review prep. Agent work must be understandable to a human reviewer without rerunning the session.

## Shared context
- Root CLAUDE.md owns repo-wide rules.
- Nested CLAUDE.md files own local package rules.
- Task prompts may add temporary context, but must not override security, data, or review rules.

## Agent boundaries
- Claude may edit application code, tests, docs, and scripts in the current task scope.
- Claude must ask before changing auth, payments, migrations, permissions, encryption, or production deploy paths.
- Claude Code subagents must have one named job, one expected output, and one reviewer-visible receipt.

## MCP access
- Read-only MCP tools may be used for issue, pull request, and documentation context.
- Write-capable MCP tools require a named workflow and human approval.
- Customer data, secrets, and production credentials are out of scope unless the security owner approves the workflow.

## Hooks and permissions
- Hooks may block secret edits, require tests, and require a summary before completion.
- Hooks should be simple enough to explain in one review comment.
- Permission changes must be reviewed with the same care as CI or deploy changes.

## Review checklist
- The pull request names any Claude agent, skill, MCP tool, or SDK script used.
- The diff stays inside the task scope.
- Tests or a clear reason for missing tests are included.
- The reviewer can see what Claude assumed, changed, and could not verify.
- Any convention change updates CLAUDE.md in the same pull request.

Adopt it the same way you adopt build rules. A developer proposes the convention in a pull request, code owners review it, and the merged file becomes the shared contract.

Then enforce one review rule: any change to agents, hooks, MCP permissions, skills, or SDK wrappers must include either a CLAUDE.md update or a note saying no convention changed. That keeps the operating model from drifting into private dotfiles.

Common questions

• Should we use the Claude Code Agent SDK or just subagents?

  Use subagents when the work is interactive and repo-local; use the SDK when the workflow needs to be scripted, repeated, or triggered outside a normal session. The citable rule is simple: if humans must review the workflow itself, put the wrapper in the repo and treat it like build tooling.

• How should Claude Code subagents fit with CLAUDE.md?

  Claude Code subagents should inherit the team rules in CLAUDE.md and add only the role-specific instructions they need. One good artifact is a short subagent definition that names the job, allowed files, expected output, and when to stop and ask a human.

• Can Claude Code agent teams work in one shared repo?

  Yes, Claude Code agent teams can work in a shared repo if the team scopes each agent and reviews the coordination rules. The caveat is that parallel work increases merge and ownership risk, so use worktrees, narrow file scopes, and reviewer-visible receipts before expanding autonomy.

• Where do MCP permissions belong in review?

  MCP permissions belong beside the workflow that uses them, usually in repo settings, team documentation, or a reviewed configuration file. The important number is one owner per integration path; broad, ownerless access is what makes an integration hard to debug and hard to trust.

• How much should we put in CLAUDE.md?

  Put only durable team rules in CLAUDE.md: architecture constraints, review expectations, test commands, safety boundaries, and local package rules. A useful limit is that a new teammate should be able to scan the root file in a few minutes and know how Claude should behave.

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

Make the convention real

Pick one repo, add the convention block, and require it on the next pull request that changes agents, MCP, hooks, skills, or SDK scripts. Small, reviewed conventions beat perfect private setups every time.

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.