# code-architect — Architecture Review Subagent

> Open-source Claude Code subagent that reviews architectural changes for cohesion, coupling, and testability. Inspired by Boris Cherny's setup.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# code-architect — Architecture Review Subagent

## Quick Use

1. Save the file below to `.claude/agents/code-architect.md`.
2. Restart Claude Code (or `/agents reload`).
3. Before merging non-trivial changes, say:
   > "Use code-architect to review the design of this branch."

You will get a structured architecture review covering cohesion, coupling, dependency direction, and testability.

> Inspired by Boris Cherny's setup (howborisusesclaudecode.com). Community-written equivalent — not Anthropic's private prompt — based on Boris's public description.

---

## Intro

code-architect is a Claude Code subagent that does design review on non-trivial changes before they reach a human reviewer. It does not check syntax or style (that is the linter's job) — it asks higher-order questions: are modules properly decoupled, is the dependency direction sane, are public surfaces minimal, can each unit be tested in isolation.

Boris Cherny lists architecture-review subagents on his setup page as part of his daily workflow. This entry captures that pattern as an open-source `.claude/agents/code-architect.md` file you can drop into any project.

Works with: Claude Code 1.x and above. Setup: under 1 minute.

---

## How code-architect Works

Save to `.claude/agents/code-architect.md`:

```markdown
---
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
---

You are the code-architect subagent. You review structural changes — not syntax or style — and report design risks.

## Workflow

1. Identify the change scope: `git diff --stat` and `git diff main...HEAD`.
2. For each modified module, evaluate four dimensions:
   - **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?
3. Score each dimension 1-5 with one-line evidence.
4. List up to 5 specific risks (with file:line) and a suggested mitigation for each.
5. Emit the structured report below.

## Output format

code-architect review
=====================
Files reviewed: N
Cohesion:    ★★★★☆ — <evidence>
Coupling:    ★★☆☆☆ — <evidence>
Direction:   ★★★★★ — <evidence>
Testability: ★★★☆☆ — <evidence>

Top risks:
1. <file:line> — <risk> → <suggested mitigation>
2. ...

## Boundaries

- Do not rewrite code yourself.
- Do not flag style issues — pair with a linter for that.
- If the diff is < 50 lines AND touches one file, decline gently: "This change is too small for an architecture review."
```

### When to use

- Before merging a feature branch that touches > 3 files or > 200 lines.
- After a major refactor — to verify it actually improved something.
- When introducing a new module/package boundary.

### When not to use

- For tiny bugfixes — too much overhead.
- For UI tweaks that do not change structure.

---

## Example session

```
You:    "Review this branch with code-architect — I just refactored the billing module."
Claude: -> reads diff (12 files, 380 lines)
        -> evaluates 4 dimensions
        -> reports:
           Cohesion ★★★★★, Coupling ★★☆☆☆ (billing now imports auth — direction inverted),
           Direction ★★★☆☆, Testability ★★★★☆
           Top risk: src/billing/charge.ts:42 imports src/auth/session.ts.
                    Mitigation: pass userId in directly, let caller resolve session.
```

---

## FAQ

**Q: How is this different from a linter?**
A: A linter checks syntax and style. code-architect asks structural questions — module boundaries, dependency direction, testability — that are not statically detectable.

**Q: Will it run on every PR?**
A: Only when you invoke it. It is heavier than a linter; use it for non-trivial changes.

**Q: Does it require any specific build system?**
A: No. It reads source files and `git diff`. Works on any language.

**Q: Can I extend the dimensions?**
A: Yes — edit the Workflow section. Common additions: error-handling discipline, observability hooks, config surface.

**Q: Is this Boris Cherny's actual subagent?**
A: No — it is a community-written equivalent based on his public description on howborisusesclaudecode.com.

---

## Source & Thanks

> Inspired by Boris Cherny's architecture-review subagent on howborisusesclaudecode.com.

Citations:
- howborisusesclaudecode.com
- Pragmatic Engineer interview: https://newsletter.pragmaticengineer.com/p/building-claude-code-with-boris-cherny
- @bcherny X thread: https://x.com/bcherny/status/2007179832300581177

<!-- ZH -->

## 快速使用

1. 把下文文件落到 `.claude/agents/code-architect.md`
2. `/agents reload`
3. 大改动 PR 之前问 Claude："Use code-architect to review the design of this branch."

会拿到 4 个维度（内聚/耦合/依赖方向/可测试性）的星级评分 + 5 条具体风险点 + 建议改法。

## 边界

- 不查语法风格（lint 的事）
- 不动手改代码
- 改动 < 50 行 + 单文件直接拒绝（杀鸡焉用牛刀）


---
Source: https://tokrepo.com/en/workflows/code-architect-architecture-review-subagent-9baa69dd
Author: Skill Factory