Agent architecture

Agents use a two-tier model for efficiency:

• Opus agents handle synthesis, judgment, and trade-off decisions. They delegate Phase 1 mechanical scanning to parallel Sonnet sub-agents, keeping scanning cheap and synthesis high-quality.
• Sonnet agents handle pattern scanning, checklist execution, and code generation. Some use their own Sonnet sub-agents for parallelism (e.g. test-scaffold reads conventions and code-under-test in parallel).

Model selection guide

Use opus when the agent needs to…	Use sonnet when the agent needs to…
Synthesize findings across multiple files	Scan for patterns in code
Make judgment calls or trade-off decisions	Follow a checklist or ruleset
Reason about attack scenarios or edge cases	Generate code from templates
Inhabit a persona or produce empathetic analysis	Execute mechanical transformations

Skills vs agents

The template uses two extension points:

• Skills (.claude/skills/<name>/SKILL.md) — user-invocable workflows triggered by /name. Used for multi-step operations like opening MRs, running releases, or importing specs. Skills with disable-model-invocation: true can only be triggered by the user (not auto-invoked by Claude) — use this for actions with external side effects.
• Agents (.claude/agents/<name>.md) — proactively invoked by Claude when their trigger conditions are met. Used for review, analysis, and generation tasks that should run automatically as part of the development workflow.

Feature	Skills	Agents
Invocation	User types /name	Claude invokes proactively
Side effects	Can have external effects (GitLab, git push)	Typically read/analyze/generate
disable-model-invocation	Supported	N/A (agents are always model-invokable)
Frontmatter	Full schema (model, effort, argument-hint, etc.)	Limited (name, model, description, tools)
Supporting files	Can include templates/scripts in the skill directory	Single file only

Skills marked with ⛔ in the file tree have disable-model-invocation: true.

Adding a project-specific agent

Create a file in .claude/agents/:

---
name: my-agent
model: opus    # or sonnet — see model selection above
description: When to use this agent (be specific so Claude invokes it proactively).
tools: Read, Grep, Glob, Bash, Agent
---

# My Agent

[instructions — include sub-agent delegation if the agent does Phase 1 scanning]

If the agent delegates scanning work to sub-agents, include Agent in the tools list and structure the instructions with parallel sub-agent launches:

### Step 1 — Gather context (parallel sub-agents)

Launch **2 sub-agents in parallel** (both with `model: "sonnet"`). Wait for both.

**Sub-agent 1 — [scanning task]:**
> [instructions]

**Sub-agent 2 — [scanning task]:**
> [instructions]

### Step 2 — Synthesize (you do this — do NOT delegate)

[synthesis instructions using sub-agent results]

Adding a project-specific skill

Create a directory in .claude/skills/:

---
name: my-skill
description: What this does and when to use it.
disable-model-invocation: true    # only if it has external side effects
argument-hint: "[arg description]"
---

# My Skill

[instructions — same format as agents, with $ARGUMENTS for user input]

Global CLAUDE.md — enforce agent workflow

The template ships global-claude-md.example, a file that makes the agent workflow mandatory rather than suggested. It goes in your personal ~/.claude/CLAUDE.md, so it applies to every project you open. Copy it if you have no global file; append it if you do (see Start a project, step 7). Never copy over an existing file.

Without it, agents run only when Claude decides to invoke them. With it, Claude follows the Fast paths by change class table for every change. Each rule in the file says when it applies and when it doesn’t, so backend-only changes skip the UX agents and bug fixes skip the design phases.

Package-level CLAUDE.md for monorepos

For monorepos with distinct frontend/backend/worker packages, create package-level CLAUDE.md files to give agents stack-specific context:

my-project/
├── CLAUDE.md                # Project-wide conventions
├── frontend/CLAUDE.md       # React patterns, design tokens, component rules
├── backend/CLAUDE.md        # Django patterns, model conventions, API rules
└── worker/CLAUDE.md         # Queue patterns, retry policies, idempotency rules

Claude reads the nearest CLAUDE.md in the directory tree, so package-level rules supplement the project-level rules for files in that subtree. Use /import-design to generate frontend/CLAUDE.md from a design guide.