Run Claude Code Agent Teams Safely

Start with a boundary, not with more agents. The Claude Code Agent SDK gives teams another way to build agent workflows around Claude Code, but Claude Code agent teams only help if the team agrees what an agent may do, what it must return, and who reviews the result.

I would treat the SDK as a production interface, not a clever local script. In a Claude Code workshop, I want teams to leave with one small convention they can use in a repo tomorrow: when to use Claude Code subagents, where MCP access is allowed, and what evidence must land in the pull request before anyone merges.

Put the SDK behind a team convention

The first convention should say when agent work is allowed. Do not start by wiring the SDK to every repo command, issue queue, and database. Start with one repeatable workflow that already has a human review point.

A good first workflow is PR preparation. For example, in a repo with apps/web and packages/api, one agent can inspect UI changes, another can check API contract changes, and the developer still owns the final commit and pull request text.

Keep durable rules in the same place your team keeps other Claude Code conventions. If you already use repository memory, a short CLAUDE.md note can point to the convention, but the convention itself should be explicit enough for a new teammate to follow without reading a long prompt history.

Decide which work becomes an agent

Use the Claude Code Agent SDK when the work has a clear input, a bounded workspace, and a reviewable output. Do not use it for vague ownership, such as “make the app better” or “clean up the backend”. That turns the review into archaeology.

This is the decision list I use before I let a workflow become agentic:

This is also where I connect it to our methodology: delegate the bounded task, review the evidence, then own the merge decision. The agent does not own the product change.

Keep subagents narrow enough to inspect

Claude Code subagents are useful when each one has a job a reviewer can name. “Frontend compatibility check” is reviewable. “Senior engineer” is not.

For a pull request that changes checkout pricing, I would rather run three narrow checks than one broad agent: one for changed UI states, one for API request and response shape, and one for tests that should be added or updated. Each agent should return its files touched, commands run, failures seen, and open questions.

MCP should be treated as a permission boundary in this workflow, not as a convenience switch. If the agent needs GitHub, Jira, or a document store, write down the reason and start read-only where possible. For a deeper MCP setup path, use Add MCP to Claude Code Safely before you wire external systems into agent work.

Paste this operating checklist into the repo

Put the convention where engineers will find it during code review. For many teams, that means a short markdown file under docs/engineering/ and a pointer from the repo’s Claude Code memory or onboarding notes.

# Claude Code Agent Team Convention

## Allowed first use case
- Use the Claude Code Agent SDK only for pull request preparation until this convention is reviewed again.
- Allowed tasks: scoped code inspection, test suggestion, small refactor proposal, documentation draft for changed code.
- Not allowed: production changes, dependency upgrades across the repo, secret handling, release decisions, or merging code.

## Agent boundaries
- Each agent gets one named job and one repo area.
- Each agent must list files inspected and files changed.
- Each agent must report commands run, including failures.
- Each agent must stop and ask when it needs access outside the named repo area.

## MCP and tool access
- Start with local repo access and read-only external access.
- Write down every MCP server the workflow needs before enabling it.
- Do not give write access to external systems until the team has reviewed two successful dry runs.

## Pull request evidence
- PR description includes the agent jobs used.
- PR description links or pastes the agent summaries.
- Human author states what they accepted, changed, or rejected.
- Reviewer can approve from the diff, tests, and summaries without replaying the chat.

## Review rule
- A PR using agents cannot merge unless a human reviewer confirms the evidence is present and the final diff matches the stated task.

Adoption should be small and named. One engineer proposes the first workflow, one reviewer checks the boundary, and the team stores the convention with the rest of its Team conventions. After two or three real pull requests, update the checklist based on what reviewers actually used.

The review rule is the enforcement point. If the PR does not show what the Claude agents did and what the human accepted, the reviewer sends it back. That is not bureaucracy. It is how you keep agent teams Claude Code can run from becoming invisible automation.

Roll it out without blocking the team

Do not ask every team to agree on a full platform before anyone tries the Claude Code SDK. Pick one repo, one workflow, and one review path. A safe pilot is a non-critical service or internal app where tests already run in CI.

The tradeoff is speed versus confidence. A tight convention will feel slower for the first week, because engineers have to write down scope and evidence. It pays back when reviewers stop asking, “What did the agent actually do?”

As of November 2026, I would avoid using the SDK as a replacement for team design review. Use it to package repeatable agent workflows around known engineering work. Keep architecture, security exceptions, and release ownership with people.

Further reading

• Claude Code docs
• Claude Code skills
• Claude Code hooks

Next step

Take one existing PR workflow and rewrite it using the checklist above before you automate it. If you want the team to practise that handoff together, run it in a Claude Code workflow session in hands-on training.