Chapter 16 | Writing Agent Files

Chapter 16: Writing Agent Files

Learning Objectives

Write agent files that can actually be found and dispatched by the main Claude.

File Structure

flowchart TB
    File[".claude/agents/.md"] --> FM["frontmatter
(name/description/tools/model)"]
    File --> Body["system prompt
(role definition + workflow + constraints)"]

    FM --> N["name: unique identifier"]
    FM --> Desc["description: when to be called"]
    FM --> Tools["tools: allowed tools"]
    FM --> Model["model: opus / sonnet / haiku"]

    style FM fill:#fff9c4
    style Body fill:#c8e6c9

Frontmatter Field Details

---
name: developer
description: Implements one group of tasks from the active OpenSpec change's tasks.md. Also fixes issues when sent back from tester or reviewer.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
---

The Critical Role of description

The main Claude reads the description to decide "whether to dispatch this agent now." Therefore:

❌ "Helps with development"
   → Too broad, dispatches for everything → wasted dispatches
   
✅ "Implements one group of tasks from active OpenSpec change's tasks.md.
    Also fixes issues when sent back from tester (test failures) or
    reviewer (rejection)."
   → Specifically states "when to call me" → accurate dispatches

description writing formula: <what to do> + <when to be called>.

Key Points for Writing System Prompts

Four-part structure:

flowchart TB
    SP["system prompt"] --> S1["1. Who you are
(identity + boundaries)"]
    SP --> S2["2. Your input
(what the briefing provides)"]
    SP --> S3["3. Your workflow
(steps + constraints)"]
    SP --> S4["4. Your output format
(report schema)"]

    style SP fill:#fff9c4

Example: Dissecting developer.md

---
name: developer
description: Implements one group of tasks ...
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
---

# You are the doc2video Implementation Engineer

[1. Identity + Boundaries]
Your job: Transform a set of OpenSpec tasks specified by the orchestrator into runnable code.

[2. Input]
## Chapter 16: Input (provided by the orchestrator in the prompt)
- active change path
- group number + group name
- all - [ ] task text for this group
- Mandatory read files: design.md / spec.md
- Previous round feedback (only if sent back for rework)

[3. Workflow]
## Chapter 16: Workflow
1. Read mandatory files
2. Understand task scope
3. Implement
4. Local verification
5. Commit

[3-bis. Strict Constraints = Anti-pattern List]
## Chapter 16: Strict Constraints
- Do not write tests (that's the tester's job)
- Do not modify specifications (specs/ design.md proposal.md are off-limits)
- Do not unilaterally expand scope
- Do not automatically fix command errors (design D6)

[4. Output]
## Chapter 16: Report upon Completion (Structured)
\`\`\`
## Chapter 16: Developer Report — Group N
**Status:** done | blocked
...
\`\`\`

→ The 4-part structure ensures the agent knows what to do, what not to do, and how to report.

Testing Agent Effectiveness

After writing a new agent, manually dispatch it once to observe its output:

You: Use the developer agent to implement group 1
   ↓
Observe:
- Which files did it read? (Check Read calls)
- Which files did it modify? (git diff)
- Is the report format correct? (Check output)
- Did it overstep its bounds? (Did it modify what it shouldn't have?)

If anything is incorrect, modify the agent file instead of repeatedly instructing it — the system prompt is its DNA, reread with every dispatch.

Anti-patterns

❌ description written like an advertisement ("Super powerful implementation agent")
❌ system prompt lacks a "Strict Constraints" section
❌ No structured output format (main Claude won't know how to parse it)
❌ Copying the entire CLAUDE.md into the agent prompt (duplication + maintenance nightmare)
❌ Giving an agent tools it shouldn't have (e.g., giving Edit to a reviewer)

Common Toolset Recipes

→ More tools are not always better — fewer = predictable behavior.

What You Can Do Now

• Write an agent file that can be found by the main Claude
• Clearly define responsibilities using a 4-part system prompt
• Verify agent behavior through dispatch testing

The next chapter will assign models to each role — finding the optimal balance of cost and capability.