AI Coding Guidelines

Appearance

Using Subagents ​

Subagents are how you delegate a focused task—a security audit, a refactor across files, a piece of research—without filling your main conversation with the work. Each subagent runs in its own isolated context window with a custom system prompt and tailored tool permissions, then reports back its findings.

Official Documentation: Claude Code Sub-agents — comprehensive technical reference

External Resources ​

How Subagents Work ​

Each subagent runs with its own isolated context window, preserving your main conversation. You define what it does by writing a system prompt — the brief that scopes the subagent's role and tools. You can limit tool access (e.g., read-only for an auditor), and subagent configurations are version-controlled and shareable across your team.

Creating Subagents ​

Subagents are defined as Markdown files with YAML frontmatter:

File location: .claude/agents/ (project) or ~/.claude/agents/ (global)

yaml
---
name: security-expert
description: Security vulnerability analysis and remediation
tools: Read, Grep, Bash  # Optional - omit to inherit all tools
model: sonnet  # Optional — accepts alias (sonnet/opus/haiku), full ID (e.g. claude-opus-4-7), or "inherit". Default: inherit.
---

You are a security expert specializing in vulnerability analysis...

Use /agents for interactive creation or manage files directly.

Practical Example: Multi-Specialist Analysis ​

Create .claude/agents/security-analyst.md, performance-auditor.md, and ux-reviewer.md with specialized prompts, then invoke:

bash
> Review our checkout system using security-analyst for vulnerabilities,
performance-auditor for bottlenecks, and ux-reviewer for UX issues.

Claude automatically routes work to the appropriate subagent based on your request.

Context Isolation ​

Each subagent runs with its own isolated context window, preserving your main conversation from context pollution.

A Note on "Done" ​

A subagent reports what it wrote, not what it ran. This is a model-level fact: text-output agents see the code they generate, but not the runtime—no logs, no exit codes, no test output unless you ask them to read it afterward. So if you ask a subagent to "refactor the auth module," you get refactored code that's syntactically correct and typed properly, with no verification that it actually compiles or passes tests.

If you want certainty about runtime behavior—"install dependencies fresh, run the test suite, confirm the server starts"—say so explicitly in the brief. Otherwise, plan on a quick verification pass in your main context after the subagent reports back.

Resources ​

Built with VitePress and powered by Claude Code

MIT Licensed