Architecture
In one line: Global specialists carry broad expertise; project reviewers enforce a codebase's exact contracts — and the project tier is the load-bearing one.
What: Two tiers. Global specialist agents (an OPTIONAL pattern — some projects forbid them, preferring direct work to preserve context) live in ~/.claude/agents/ and provide broad domain expertise: security, database design, AI/ML, frontend, testing. Project-specific reviewer agents live in PROJECT/.claude/agents/ and provide checklists calibrated to the project's patterns, conventions, and requirements.
Why: Same reason as the instruction hierarchy (Section 4): different scopes need different specificity.
A global security agent knows OWASP Top 10, JWT validation, injection prevention, PII protection — applicable anywhere. But it does not know that this project authenticates via a specific dependency, accesses the database through a tenant-scoped session helper, or enforces row-level security on its tenant tables. A project security reviewer knows these conventions and checks them explicitly.
Global agents catch categories of issues (missing authentication); project reviewers catch convention violations (using the unscoped session helper instead of the tenant-scoped one). Project reviewers are the load-bearing tier; global specialists are optional reinforcement.
Global Specialist Agents (optional):
| Agent | Domain | When to Dispatch |
|---|---|---|
| Code Architect | System architecture, DDD, module boundaries | New feature design, refactoring strategy |
| AI Engineer | LLM integration, ML pipelines, RAG, vector databases | AI feature implementation |
| Security Engineer | Auth, authorization, injection prevention, PII | Security-sensitive changes |
| Database Engineer | Schema design, query optimization, migrations | Database changes |
| Frontend Developer | React, Next.js, component architecture | Frontend implementation |
| UI Designer | Visual design, layout, design system application | UI component creation |
| UX Researcher | User flows, interaction patterns, accessibility | UX design decisions |
| Python Expert | Python idioms, async patterns, performance | Complex Python implementation |
| Test Writer & Fixer | Test coverage, failure analysis, test repair | Test creation and debugging |
| Code Reviewer | General code quality, patterns, maintainability | Code review |
| Debugger | Root cause analysis, systematic investigation | Complex bugs |
| Deployment Engineer | CI/CD, containerization, infrastructure | Deployment and ops |
| MCP Expert | MCP server integration, tool configuration | MCP setup and troubleshooting |
| Research Agent | Information gathering, technology evaluation | Research tasks |
Project-Specific Reviewer Agents (4):
These are detailed in Section 5.3.
Evidence: Each agent is a markdown file with YAML frontmatter (name, description, model, tools), a role, a domain checklist, and an output format. Project reviewers are calibrated to the project's patterns — the API reviewer checks the tenant-context dependency, the migration reviewer checks for row-level-security clauses, the compliance reviewer checks the project's regulatory requirements. Reproducible: the checks live in the agent's SKILL.md/definition, not in a reviewer's head. See Section 5.3.
How: Agent definitions are markdown files with YAML frontmatter placed in ~/.claude/agents/ (global) or PROJECT/.claude/agents/ (project). Claude Code discovers them automatically. For the full agent architecture specification, see Section 5.