Subagent conventions for Claude Code teams

Use a Claude Code subagent when a bounded job can return a useful result independently, such as inspecting a failing test or reviewing an API change. Give it the task, relevant context, allowed tools and expected output before starting.

This guide combines our three June subagent notes into one proposed team exercise. It describes a way to evaluate a role in your repository; it does not claim measured productivity gains or that a written convention enforces permissions.

What makes a useful role?

Choose one responsibility. A test-failure investigator should identify the failing case, inspect the relevant implementation and report evidence. It should not also decide product behaviour, refactor the data layer and publish a release.

Write down the input and output before creating the agent. For example, the input can be a saved test failure plus the affected package. The output can be a suspected cause, supporting file locations, an uncertainty and the next check to run. If those cannot be stated clearly, keep the investigation in the main session until the task is better understood.

How do you configure the role?

Claude Code supports custom subagent definitions with a description, instructions and tool configuration. Project definitions can live in .claude/agents/. The official subagent documentation explains the supported fields and loading behaviour. Use its configuration surface rather than assuming a role name in CLAUDE.md creates an agent.

Keep durable repository guidance in CLAUDE.md, and include task-specific context in the delegation request. The subagent has its own context, so do not assume it knows everything discussed earlier in the parent conversation. Avoid copying unrelated chat history or secrets into that request.

For a read-only investigator, configure only the reading and search tools it needs. A sentence saying 'do not edit' is not equivalent to withholding an edit tool. Provider permissions still govern external MCP access, and shell access can introduce additional effects. Review the actual configuration as well as the role description.

What should a delegation request contain?

Use a small contract that another engineer can inspect:

Task: investigate the supplied failure; do not change files.
Scope: the affected package and its tests.
Context: failure output and relevant repository guidance.
Tools: the configured read-only tools for this role.
Return: suspected cause, file evidence, uncertainty, next check.
Stop: required evidence is outside scope or unavailable.
Reviewer: the engineer responsible for this task.

Paths in that request express task scope. They are not a filesystem sandbox. Apply runtime restrictions where the job requires isolation. Likewise, naming an MCP server in a request does not reduce the permissions of its credential.

How can you test the convention?

Use a small repository or disposable branch with a known failing test. Save the starting state, run the investigator and inspect both its answer and any file changes. A successful read-only run produces no patch and points to evidence that you can verify.

Run a second case where a required file is unavailable. The useful behaviour is to report the missing evidence and stop that part of the investigation, rather than inventing a cause. Have another engineer repeat the exercise before adopting the role for routine work. These are suggested checks, not reported test results.

If several agents contribute later, name who combines their results and runs the final checks. Independent reports do not prove that the combined patch works. Keep ownership with the engineer reviewing the change.

What belongs in the handoff?

The reviewer needs the requested job, inspected files, external context used, checks actually run and unresolved questions. Report a check as unrun when the role lacks the tool or permission to execute it. A confident summary is not a test result.

Add hooks only for a specific repeatable check that can be implemented and tested. Describing a hook in prose does not install it. The team conventions guide covers how to maintain these agreements alongside normal code review.

Editorial update

Updated 20 September 2026: consolidated three subagent playbooks, removed version-number filler, and added explicit tool configuration, missing-context and read-only verification checks.