Code Agent Family Guide

Documentation Writer

Documentation generation. /code docs MUST route to the documentation family’s documentation-writer subagent: the code family defines no documentation agent of its own.

Attribute	Value
Agent name	documentation-writer
Model	Sonnet (frontmatter model: sonnet)
Command	/code docs
File	configs/claude/agents/docs/writer.md

Output:

• API documentation
• README sections
• Code comments
• Architecture diagrams (Mermaid)

Why: documentation already has a dedicated agent family, so the code family delegates instead of carrying a second definition that would drift from it. The code family therefore holds exactly eight agents, and /code docs is a cross-family route: an installation that omits agents/docs/writer.md leaves the subcommand with no agent to invoke, so installers MUST copy that file alongside the eight code agents.

---

Language-Specific Review Checklists

Code agents MUST apply language-specific checks based on the file type being reviewed.

Severity Levels

All findings use RFC 2119 severity levels:

Level	Keyword	Meaning	Action Required
Critical	MUST FIX	Security vulnerability, data loss risk	Block merge
High	MUST	Significant bug or issue	Fix before merge
Medium	SHOULD	Improvement needed	Fix soon
Low	MAY	Minor enhancement	Consider
Info	N/A	Observation only	Awareness

Output Format

All code agents MUST use this output format:

## Code Review: [Brief Title]

| Metric | Value |
|--------|-------|
| **Review Effort** | [1-5] |
| **Risk Level** | Low / Medium / High / Critical |
| **Change Size** | XS / S / M / L / XL |

### 🔴 Critical (must fix before merge)

- [ ] **[Category]**: [description] (`file:line`) — **[confidence]%**

  **Evidence**: [how we know this is an issue]

  **Before**:
  ```[lang]
  [problematic code]
  ```

  **After**:

  ```[lang]
  [fixed code]
  ```

  **Why**: [explanation]

### 🟡 Warning (should fix)

### 🔵 Suggestion (consider)

### ✅ Positive Observations

### Summary

[1-2 sentence overall assessment]

Cost Optimization

Agent	Model	Est. Cost/Invocation	Volume
Code Architect	Opus	$0.50	Per PR (major)
Code Reviewer	Sonnet	$0.20	Per PR
Code Reviewer Quick	Haiku	$0.02	Per commit
Performance Reviewer	Sonnet	$0.25	On request
Accessibility Reviewer	Sonnet	$0.20	Frontend PRs
API Reviewers	Sonnet	$0.20	API changes
Test Writer	Sonnet	$0.30	On request
Code Simplifier	Sonnet	$0.25	Post-feature
Documentation Writer	Sonnet	$0.20	On request

Estimates assume Claude API list prices — Opus 4.5 at $5/$25, Sonnet 4.5 at $3/$15 and Haiku 4.5 at $1/$5 per million input/output tokens — over a PR-sized context: roughly 10K in and 2K out for quick mode, 20K in and 8K out for one specialist, 40K in and 12K out for the Opus coordinator. Teams MUST re-derive them from their own provider’s price list.

Cost by Mode:

Mode	Typical Cost	Use Case
/code quick	~$0.02	Every commit
/code review	~$0.20	PR review
/code	~$0.80	Full assessment

Model Lifecycle

Every route MUST name an exact API model ID in the frontmatter of the subagent or skill that runs it, and that ID MUST be active on the provider the team bills through.

• The Haiku route used by /code quick MUST pin claude-haiku-4-5-20251001. It is active on the Claude API, with a tentative retirement not sooner than 15 October 2026.
• claude-3-5-haiku-20241022 (Haiku 3.5) MUST NOT be used. It was deprecated on 19 December 2025 and retired on the Claude API on 19 February 2026; requests to retired models fail.
• Those dates cover Anthropic-operated platforms only — the Claude API, Claude Platform on AWS, and Microsoft Foundry. Amazon Bedrock and Google Cloud set their own retirement schedules and still serve Haiku 3.5, so teams on a partner platform MUST take the lifecycle date from that platform’s own model table.
• Changing a model changes what the agent reports and what it costs. Teams MUST re-run the role’s evaluation and re-derive the estimates above before adopting a replacement.

Why: a retired ID is not a quality trade-off, it is an outage. The model deprecations table gives current status and replacement IDs, and pricing marks Haiku 3.5 as retired except on Bedrock and Google Cloud.

Install the Code Agent Family

Claude Code discovers subagents and slash commands by file location, not by a settings key. Installing the family means copying the definitions into a directory Claude Code scans; there is nothing to switch on afterwards.

A project install SHOULD be preferred, because the definitions are then version-controlled with the code they review:

# Run from the root of the project that will be reviewed.
# CREFFT points at a clone or unpacked release of this repository.
CREFFT="${CREFFT:-$HOME/src/crefft}"

mkdir -p .claude/agents/code .claude/agents/docs .claude/commands
cp "$CREFFT"/agents/code/*.md .claude/agents/code/
cp "$CREFFT"/agents/docs/writer.md .claude/agents/docs/
cp "$CREFFT"/commands/code.md .claude/commands/code.md

The result:

project/
├── .claude/
│   ├── agents/
│   │   ├── code/
│   │   │   ├── accessibility.md   # accessibility-reviewer
│   │   │   ├── api-graphql.md     # graphql-api-reviewer
│   │   │   ├── api-rest.md        # rest-api-reviewer
│   │   │   ├── architect.md       # code-architect
│   │   │   ├── performance.md     # performance-reviewer
│   │   │   ├── reviewer.md        # code-reviewer
│   │   │   ├── simplifier.md      # code-simplifier
│   │   │   └── test-writer.md     # test-writer
│   │   └── docs/
│   │       └── writer.md          # documentation-writer, for /code docs
│   └── commands/
│       └── code.md                # /code
└── AGENTS.md

Copy the eight code agents and agents/docs/writer.md: /code docs delegates to the documentation family, so an install that skips that file advertises a subcommand with no agent behind it.

Why the subdirectories are safe: Claude Code scans .claude/agents/ recursively and takes a subagent’s identity from its name frontmatter field, not from its path, so code/ and docs/ are organization only and do not change how an agent is invoked.¹

Installation Scopes

Scope	Location	Use when
Project	.claude/agents/, .claude/commands/	The team shares the family
Personal	~/.claude/agents/, ~/.claude/commands/	Every project on one machine
Session	claude --agents '<json>'	One-off trials and CI scripts
Plugin	The plugin’s agents/ and skills/ directories	Fleet-wide distribution

Project definitions win over personal ones of the same name, and managed settings or --agents outrank both. Skills resolve the other way: a personal skill overrides a project skill of the same name. Plugin agents are namespaced as plugin-name:agent-name, so an explicit invocation MUST use the scoped identifier.^{1 2}

A session-scoped install saves nothing to disk and is RECOMMENDED for trying a definition before committing it:

claude --agents '{
  "code-reviewer": {
    "description": "crefft standard code review. Use after code changes.",
    "prompt": "You are the crefft code-reviewer agent. Report findings by severity.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

For new work, a skill SHOULD be preferred over a command file: custom commands have been merged into skills, .claude/skills/code/SKILL.md and .claude/commands/code.md both provide /code, and the skill wins when both exist. A skill directory also carries supporting files and controls whether Claude may invoke it without being asked.²

Verify, Update, and Remove

Restart Claude Code after creating .claude/agents/ for the first time: a running session does not pick up an agents directory that did not exist when it started. Then confirm the install:

ls .claude/agents/code .claude/agents/docs .claude/commands
grep -h '^name:' .claude/agents/code/*.md .claude/agents/docs/writer.md

Nine name: lines MUST appear — the eight code agents and documentation-writer. Duplicate names in one directory are resolved by filesystem read order rather than a documented precedence, so keep them unique; /doctor reports duplicates.¹

Update by re-running the copy against a newer pinned release, and remove by deleting the same paths:

# Update: pin an explicit release tag, then re-copy over the installed files.
git -C "$CREFFT" fetch --tags
git -C "$CREFFT" tag --list          # pick the release to pin
git -C "$CREFFT" checkout v2.9.0
cp "$CREFFT"/agents/code/*.md .claude/agents/code/
cp "$CREFFT"/agents/docs/writer.md .claude/agents/docs/
cp "$CREFFT"/commands/code.md .claude/commands/code.md

# Remove.
rm -rf .claude/agents/code .claude/agents/docs/writer.md .claude/commands/code.md

What settings.json Does Not Do

.claude/settings.json MUST NOT be used to enable or install this family. The settings schema has no agents key: the top-level agent key it does define selects one agent for the main thread and does not register anything. Settings change runtime behavior — permissions, hooks, sandboxing, plugin enablement — for definitions that are already installed:

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

Why: the schema accepts additional properties, so an invented block such as "agents": {"code": {"enabled": true}} validates, is silently ignored, and leaves a team believing review is switched on when no agent or command has been installed at all. Deny the Agent tool outright to stop delegation entirely, or name a subagent to block just that one.¹

DO

• MUST run /code review on all PRs
• MUST run /code a11y on frontend changes
• MUST address Critical and High findings before merge
• SHOULD use /code quick for rapid iteration
• SHOULD run /code tests for new features
• MAY use /code simplify after feature completion

DON’T

• MUST NOT ignore Critical findings
• MUST NOT skip review for “small” changes
• SHOULD NOT rely solely on quick mode for final review
• SHOULD NOT skip A11y review for user-facing changes