Claude Code subagents for read-only code inspection

When to use

• You want a separate investigation of a module that returns findings and evidence before the main session chooses changes.[1]

When not to use

• The task is tiny and already understood, or you expect automatic fixes while providing only read tools.[1]

Separate context needs a clear task

The documentation describes subagents as working in their own context windows, with results returned to the main conversation. Do not assume that every decision discussed in the main session is available. Include the module path, inspection question and expected output in the task. Supply missing background before acting on a report that misunderstood the project.[1]

Define a project-level inspector

---
name: inspection-notes
description: Inspect a specified module and report evidence-backed findings without editing files.
tools: Read, Grep, Glob
---

Inspect only the module named in the task.
For each finding, return a file path, the observed behavior,
why it matters, and a suggested follow-up check.
Do not claim a command was executed unless it actually was.

[1]

The tools field explicitly lists Read, Grep and Glob; this example does not expose editing or Bash tools. Frontmatter configures the agent while the body describes its work. A user-level definition can live in ~/.claude/agents/. Choose the scope according to whether the definition should be shared with your team.[1]

Make the output reviewable

• Example task: inspect retry handling in src/queue/ and report paths that may execute twice, with file locations and proposed checks.
• Separate observations, inferences and unanswered questions; a subagent without command execution should not report passing tests.
• Have the main session inspect the cited files and task scope before adding tests, changing implementation or declining a suggestion.

[1]

Verification and limits

Official file locations, frontmatter examples and tool configuration were reviewed. The example file received a structural check; no subagent was started, no project was inspected and no tests were executed. The tools list limits exposed capabilities, but read scope and organization permissions still depend on the session settings. If the task needs execution, redesign the task and permissions instead of inventing results.[1]