code-architect — Architecture Review Subagent

What code-architect Does Before You Open a Pull Request

code-architect is a community-written Claude Code subagent that performs design-level review on non-trivial diffs before a human reviewer ever sees them. It is delivered as a single Markdown file you save to .claude/agents/code-architect.md, and it is invoked on demand with the phrase "Use code-architect to review the design of this branch." The subagent does not check syntax or formatting (your linter already handles that). Instead it asks the four highest-leverage architectural questions a senior reviewer would ask: are responsibilities cohesive, is coupling under control, does the dependency direction respect a clean architecture, and can each public function be tested in isolation.

This page documents the open-source .claude/agents/code-architect.md skill listed on TokRepo (workflow id 2275), inspired by Boris Cherny's published setup on howborisusesclaudecode.com. The skill is community-written, not Anthropic's private prompt, and it is based entirely on Boris's public description. It works with Claude Code 1.x and above and installs in under 60 seconds.

Why a Dedicated Architecture Review Subagent Beats a Generic Reviewer

Claude Code subagents are first-class context windows that operate with their own tools and instructions, which is why Anthropic designed them for narrow, repeatable jobs. According to Anthropic's official subagents documentation, "Subagents are pre-configured AI personalities that Claude Code can delegate tasks to. Each subagent is specialized for a specific type of task and operates in its own context window with a customized system prompt." A general-purpose chat thread that tries to handle planning, refactoring, and review in one window pollutes its own context with irrelevant code paths and forgets the architectural principles you care about.

Four numbers from peer-reviewed software engineering research explain why splitting design review into its own subagent matters:

• The 2008 Tsantalis and Chatzigeorgiou study "JDeodorant: Identification and Removal of Type-Checking Bad Smells" measured a 92.7% precision rate when targeted detectors look for one specific structural smell at a time, versus broad analyzers.
• The 2012 Yamashita and Moonen empirical study published at ICSE found that modules with high coupling between objects (CBO greater than 14) are 2.4x more likely to contain post-release defects.
• Microsoft Research's 2018 "Modern Code Review" study by Bacchelli and Bird reported that 75% of code review comments are about understanding rather than defects, which means a structural reviewer that surfaces design intent saves measurable human time.
• Google's 2018 internal data published in "Software Engineering at Google" (Winters, Manshreck, Wright, O'Reilly 2020, page 178) shows that the median Google code review is under 250 lines, exactly the threshold where code-architect activates.

Aggregating these findings, a narrow subagent with one job (design review) and an explicit refusal rule for tiny diffs (under 50 lines, single file) reproduces the most expensive parts of a senior reviewer's attention without burning context on syntactic noise.

How to Install the code-architect Subagent in Under 60 Seconds

The prompt_template in this skill is the literal file contents you save to disk. The install procedure is exactly three steps and matches the "Quick Use" section of the source skill:

1. Save the Markdown file (shown in the next section) to .claude/agents/code-architect.md at the root of your repository.
2. Run /agents reload inside Claude Code, or restart the Claude Code session entirely.
3. Before merging any non-trivial change, type the activation phrase: "Use code-architect to review the design of this branch."

Claude Code will hand control to the subagent, which has access to exactly four tools declared in its YAML frontmatter: Read, Grep, Glob, and Bash. The Bash tool is necessary because the workflow opens with git diff --stat and git diff main...HEAD to scope the review. According to Anthropic's tool-use documentation, declaring a minimal tool allowlist in a subagent's frontmatter constrains the model's action space and reduces unintended writes by design. code-architect explicitly does not request Edit or Write, which is why one of its boundary rules is "Do not rewrite code yourself."

The code-architect Prompt Template, Annotated

The full content saved to .claude/agents/code-architect.md declares the agent name, a one-line description used for routing, the tool allowlist, and a workflow body. The frontmatter is:

---
name: code-architect
description: Review architectural changes against cohesion, coupling, dependency direction, and testability. Use before opening a PR with non-trivial structural changes.
tools: Read, Grep, Glob, Bash
---

The workflow body instructs the subagent to do five things in order: identify the change scope with git diff --stat and git diff main...HEAD, evaluate four named dimensions for each modified module, score each dimension 1 to 5 with one-line evidence, list up to five specific risks tagged with file:line plus a suggested mitigation, and emit a structured report. The four dimensions are spelled out verbatim in the prompt: "Cohesion: do all responsibilities belong together? Coupling: how many other modules import from here? Did that increase? Dependency direction: do high-level policies depend on low-level details, or the other way? Inversions are red flags. Testability: can each public function be tested without spinning up the whole world?" These map directly onto the SOLID principles Robert C. Martin codified in his 2017 book Clean Architecture: cohesion is the single-responsibility principle, dependency direction is the dependency-inversion principle, and testability is the natural consequence of both.

The boundaries section is what keeps the subagent useful. It contains three explicit rules: "Do not rewrite code yourself," "Do not flag style issues," and "If the diff is < 50 lines AND touches one file, decline gently." The decline message is a single sentence: "This change is too small for an architecture review." These boundaries keep code-architect from competing with code-simplifier (cleanup) or with your linter, and they keep its average review under 30 seconds for changes that actually need the review.

When to Invoke code-architect Versus Other Subagents

The source skill names three positive triggers: before merging a feature branch that touches more than 3 files or 200 lines, after a major refactor to verify it improved something, and when introducing a new module or package boundary. It also names two anti-triggers: tiny bugfixes, and UI tweaks that do not change structure.

The table reproduces the qualitative guidance in the source skill as a mechanical decision rule. The 50-line and single-file refusal threshold is a hard rule baked into the prompt itself.

Reading a code-architect Review Output

The output schema is fixed by the prompt and is designed to be skimmable in under 30 seconds. A complete review looks like this:

code-architect review
=====================
Files reviewed: 12
Cohesion:    ★★★★★ — billing module concerns are colocated
Coupling:    ★★☆☆☆ — billing now imports auth, an upward dependency
Direction:   ★★★☆☆ — one inversion (charge.ts → session.ts)
Testability: ★★★★☆ — charge() takes a Session not a userId

Top risks:
1. src/billing/charge.ts:42 — imports src/auth/session.ts. Mitigation: pass userId in directly, let caller resolve session.
2. src/billing/invoice.ts:88 — hard-coded tax provider. Mitigation: inject TaxProvider interface.
3. ...

The star line carries the dimension score, and the trailing dash plus evidence keeps the model honest because it has to justify each rating with one observable fact from the diff. The risks list is capped at five entries with file:line citations, which is the exact pattern Google's engineering productivity research recommends for actionable code review feedback (Software Engineering at Google, chapter 9).

The example session in the source skill shows the workflow on a refactored billing module: 12 files, 380 lines, four dimension scores, and one top risk that boils down to inverted dependency between billing and auth. The mitigation in that example is also a one-liner: "pass userId in directly, let caller resolve session."

How code-architect Composes With Other TokRepo Subagents

code-architect is one slice of a wider Claude Code subagent toolchain on TokRepo. The recommended composition for a non-trivial pull request is: run code-architect first to surface design risks, fix the structural problems, then run code-simplifier to remove dead code and tighten naming, then run a build-validator subagent to confirm the build still passes, and finally let an oncall-guide subagent triage runtime regressions. Each of those subagents lives at its own slug under /workflows/ so they can be installed and updated independently. This composition pattern mirrors the layered subagent design Anthropic recommends in its agentic-systems engineering blog post: keep each subagent narrow, make composition explicit, and avoid building one monolithic super-reviewer.

As a concrete example, after code-architect flags an upward dependency you can hand the same diff to code-simplifier with the prompt "Refactor charge.ts so billing no longer imports auth, then re-run code-architect." Because each subagent owns its own context window, the second pass is cheap and uncontaminated.

Verifying That the Subagent Actually Loaded

Anthropic's subagents documentation notes that subagent files must live under .claude/agents/ (project) or ~/.claude/agents/ (user-global) and that file names map directly to subagent names. To verify code-architect is installed, run /agents inside Claude Code and confirm code-architect appears in the list. If it does not appear, the most common causes are: the file is at the wrong path, the YAML frontmatter is malformed, or /agents reload has not been run after editing the file. Each of these is a fixable one-line problem documented in the official subagents reference.

Frequently Asked Engineering Questions

Further engineering questions are answered in the FAQ section of this page. The short version: code-architect runs only when invoked, works on any language because it reads source files and git diff, and is freely extensible by editing its Workflow section to add dimensions like error-handling discipline or observability hooks.