---
name: architecture-standards
description: Clean Architecture 词汇层 — 层归属、依赖规则（Dependency Rule）、port/adapter 边界、use-case 中心设计。Use when designing module boundaries, deciding where code belongs, checking dependency direction, or when another skill needs to enforce layered architecture.
---

# Architecture Standards (Clean Architecture)

层与依赖方向的词汇，垫在其他技能下面。与 `domain-modeling`（术语）和 `codebase-design`（深模块）互补：**domain-modeling 管语言，codebase-design 管层内模块形态，本技能管层与依赖方向。**

## 四层（由内向外）

1. **Entities（企业业务规则）** — 与业务价值直接相关、与技术无关的核心领域对象与规则。禁止依赖任何外层。
2. **Use Cases（应用业务规则）** — 编排业务场景：一个用例一个类/函数，用业务动词短语命名（`checkoutCart`、`approveInvoice`）。依赖 Entities；**定义 ports（接口）**。
3. **Adapters（接口适配器）** — controllers / gateways / presenters：实现 Use Cases 定义的 ports，把外部世界（HTTP/DB/UI）翻译成用例语言。
4. **Frameworks & Drivers** — DB 驱动、Web 框架、UI、第三方 SDK。最外层。

## 依赖规则（Dependency Rule）

- 源代码依赖**只指向内层**。外层可依赖内层，内层**绝不**依赖外层。
- 硬违规标志：Entities / Use Cases 里出现框架 import（`sqlalchemy` / `django` / `express` / `axios` / UI 类型 / DB 驱动）。

## 跨边界：ports & adapters（依赖反转）

- 内层定义接口（port）：`interface OrderRepository { ... }`
- 外层实现 adapter：`class PostgresOrderRepository implements OrderRepository`
- 内层绝不 new 外层实现；接线（依赖注入）发生在组合根 / 最外层。

## Use-case 中心

- 每个业务场景一个显式用例（类/函数），名字是业务动词短语
- 用例参数与返回值是**领域类型**，不是框架类型
- 用例不直接碰框架 API

## 反模式（审查时直接匹配）

- 实体/用例里 import 框架或驱动（依赖规则违规）
- use case 直接 new 外部服务
- 依赖方向反转（内层感知外层）
- 业务规则散落在 controller / UI 层
- 无 port 直接调用具体实现（可测性死亡）

## 验证方法（每层 import 白名单）

- **Entities**：标准库 + 同层领域类型
- **Use Cases**：+ Entities
- **Adapters**：+ Use Cases（实现其 ports）
- **Frameworks**：无限制（最外层）

## 与 codebase-design 的关系

- **层内**模块形态用 codebase-design：深模块、小接口、干净的缝
- **层间**边界就是"缝"：port/adapter 是跨层的干净缝
- 本技能回答"代码该在哪层、依赖该往哪指"；codebase-design 回答"层内模块长什么样"
- 规则优先级：repo 的 `ARCHITECTURE.md`（由 setup-matt-pocock-skills 生成）覆盖本基线