264 lines
15 KiB
Markdown
264 lines
15 KiB
Markdown
# 一份CLAUDEmd统治一个AI团队Spec架构设计的四层模型
|
||
|
||
**TL;DR：**
|
||
----------
|
||
|
||
1. AI 原生开发的 Spec 不是传统的需求文档——它是"给 Agent 的操作系统"，决定了 AI 如何理解项目、如何执行任务、如何自我约束
|
||
2. 好的 Spec 架构分四层：宪法层（项目级配置）→ 技能层（可组合的执行模块）→ 知识层（共享领域知识）→ 状态层（持久化记忆），每层各司其职
|
||
3. Spec 写作的核心原则是"少即是多"——200 行精心设计的 Markdown 远胜 2000 行面面俱到的文档
|
||
|
||
---
|
||
|
||
|
||
|
||
### **一、背景：传统需求文档为什么对 AI 不管用**
|
||
|
||
把一份 50 页的 PRD 丢给 AI，让它"照着做"——这大概是 2025 年最常见的 AI 编程失败模式之一。
|
||
|
||
原因很简单：**传统需求文档是写给人看的，它假设读者有上下文、有判断力、会主动填补信息缺口**。AI 没有这些能力。你写"参考现有模块的设计风格"，人类工程师知道去看 git log 和代码风格，AI 只会猜。你写"考虑边界情况"，人类知道哪些边界重要，AI 不知道——要么忽略，要么过度防御。
|
||
|
||
Addy Osmani（Google Chrome 团队工程师）在 2026 年初发表了一篇关于"如何为 AI Agent 写好 Spec"的深度指南，核心观点是：**AI 需要的不是"需求文档"，而是"执行环境"**。这个"执行环境"需要回答三个问题：
|
||
|
||
1. **我是谁？**（项目定位、技术栈、代码风格）
|
||
2. **我能做什么？**（允许的操作、禁止的操作、边界）
|
||
3. **我怎么做？**（工作流程、验证标准、交付格式）
|
||
|
||
这三个问题，恰好对应了一种新的 Spec 架构模型。
|
||
|
||
### **二、Spec 架构的四层模型**
|
||
|
||
从多个 AI 原生开发实践中，我观察到一个共同的分层模式。不管用什么工具——Claude Code、Cursor、Copilot——最终有效的 Spec 架构都在趋向同一种四层结构。
|
||
|
||
|
||
|
||
### **2.1. 宪法层：项目级配置文件**
|
||
|
||
**代表形式：** CLAUDE.md、.cursorrules、GEMINI.md、Copilot Instructions
|
||
|
||
这是整个 AI 开发环境的"宪法"——定义项目的基本法则，所有 Agent 行为都受其约束。
|
||
|
||
**一个有效的宪法层应包含：**
|
||
|
||
```
|
||
# 项目定位（一句话说清楚这是什么）
|
||
# 技术栈（具体版本号，不是"最新"）
|
||
# 开发命令（可直接执行的命令，不是"参考文档"）
|
||
# 代码风格（用代码示例，不是文字描述）
|
||
# 硬性约束（Git 提交授权、禁止操作、安全边界）
|
||
```
|
||
|
||
**关键原则——Addy Osmani 的"三层边界系统"：**
|
||
|
||
* ✅ **总是做**：无需询问的安全操作（如运行测试、格式化代码）
|
||
* ⚠️ **先询问**：需要人类审批的高影响变更（如 Git 提交、删除文件）
|
||
* 🚫 **绝不做**：硬性禁止（如提交密钥、修改生产配置）
|
||
|
||
我在实践中发现，**把 Git 提交列为"先询问"级别是最关键的一条约束**。没有这条，AI 会在你不知情的情况下创建大量低质量提交，污染 git history。
|
||
|
||
**宪法层的大忌：** 写太多。200 行是上限。超过 200 行的宪法文件，AI 的遵从率会显著下降——这与 Martin Fowler 团队发现的"规范冗长度和 AI 遵从度之间没有线性关系"完全一致。
|
||
|
||
### **2.2. 技能层：可组合的执行模块**
|
||
|
||
**代表形式：** Superpowers Skills、Claude Code Custom Commands、Cursor Rules
|
||
|
||
技能层的核心思想是：**不要在一个 Spec 里塞所有东西，而是按任务类型拆分成独立的执行模块**。
|
||
|
||
比如一个 AI 辅助的 SaaS 项目管理工具，可能有这些技能模块：
|
||
|
||
* 需求分析（定义用户故事格式、验收标准模板、优先级评估框架）
|
||
* API 设计（定义 RESTful 规范、请求/响应格式、错误码体系）
|
||
* 代码审查（定义检查清单、严重度分级、修复流程）
|
||
* 发布部署（定义版本号规则、变更日志格式、回滚预案）
|
||
|
||
每个技能是**自包含的**——它知道自己的输入、流程和输出，不依赖其他技能的上下文。技能之间通过共享知识层和状态层实现松耦合。
|
||
|
||
**为什么技能层比单体 Spec 更有效？**
|
||
|
||
Osmani 提出了一个概念叫"指令诅咒"（Instruction Curse）——**同时给 AI 太多指令，会降低 AI 遵守每条指令的能力**。技能层通过"按需激活"解决这个问题：AI 在执行某个任务时，只看到与该任务相关的技能 Spec，不会被其他无关指令干扰。
|
||
|
||
Superpowers 把这个原则做到了极致——技能文件用 Markdown 编写，在 Agent 启动时自动注入，形成了"Markdown 即插件"的模式。Jesse Vincent 的测试表明，这种方式下 Agent 对技能指令的遵从率远高于把所有指令塞进一个大文件。
|
||
|
||
### **2.3. 知识层：共享领域知识库**
|
||
|
||
**代表形式：** 项目内的 docs/ 目录、.claude/docs/、context7 MCP
|
||
|
||
知识层存放的是**多个技能共享的领域知识**——分析框架、标签体系、质量标准等。
|
||
|
||
为什么要把知识单独分层？因为**同一套知识会被不同技能反复引用**。比如一套"RESTful API 设计规范"（URL 命名、分页约定、错误码体系、版本策略）可能同时被需求分析、API 设计和代码审查三个技能引用。如果把这套规范复制到每个技能文件里，维护成本会爆炸——改一处需要同步改多处。
|
||
|
||
**知识层的组织原则：**
|
||
|
||
* 每个知识文件聚焦一个主题（分析框架、质量标准、标签体系）
|
||
* 技能层通过"执行前读取 xxx 文件"的方式按需引用
|
||
* 知识文件是 **append-only 倾向** 的——新增知识追加，旧知识只在明确过时时才删除
|
||
|
||
### **2.4. 状态层：让 AI 拥有"记忆"**
|
||
|
||
**代表形式：** 项目内的 data/ 目录、Memory MCP Server、.memory/ 目录
|
||
|
||
状态层是四层模型中最容易被忽视、但对长期项目最关键的一层。
|
||
|
||
**问题场景：** AI 每次开始新对话时，对项目的理解是从零开始的。没有状态层，AI 会反复做相同的调研、提出相同的建议、犯相同的错误。
|
||
|
||
**两种状态管理模式：**
|
||
|
||
| 模式 | 实现方式 | 优势 | 劣势 |
|
||
| --- | --- | --- | --- |
|
||
| 文件驱动 | YAML/Markdown 文件在项目仓库内 | 版本可控、人类可读、可审查 | 需要手动定义文件格式和更新规则 |
|
||
| MCP 驱动 | Memory MCP Server（JSONL 存储） | 自动化、结构化、支持实体关系 | 黑盒程度高、不易人工审查 |
|
||
|
||
我的实践结论是：**两者混用效果最好**。
|
||
|
||
* **结构化状态**（功能路线图、依赖跟踪、架构决策日志）→ 用文件驱动，存放在 data/ 目录，YAML/Markdown 格式
|
||
* **非结构化记忆**（项目上下文、临时发现、环境信息）→ 用 MCP Memory Server
|
||
|
||
状态层还需要**冷热分离**——热区保持精简（只保留最近 30-60 天的活跃数据），冷数据归档到 archive/ 目录。否则状态文件会无限膨胀，最终超过 AI 的上下文窗口，反而起反效果。
|
||
|
||
### **三、Addy Osmani 的 Spec 写作五原则实战**
|
||
|
||
Osmani 总结了五条 Spec 写作核心原则，每一条我都在实践中得到了验证（或打脸）：
|
||
|
||
### **3.1. 高层次愿景优先，细节由 AI 补充**
|
||
|
||
**原则：** 人类定义"做什么"和"为什么"，AI 负责扩展"怎么做"的细节。
|
||
|
||
**实战体验：** 这条在原型阶段100% 成立。给 AI 一个高层次目标（"构建一个 Spring Boot 风格的 Python IoC 容器"），它能自主设计出完整的装饰器系统、依赖注入引擎、配置管理模块。但在维护阶段，高层次指令往往不够——AI 需要更精确的约束才能避免破坏已有架构。
|
||
|
||
### **3.2. 结构化设计（PRD 风格）**
|
||
|
||
**原则：** Spec 应涵盖六个核心领域——命令、测试、项目结构、代码风格、Git 工作流、边界。
|
||
|
||
**实战体验：** 六个领域中，**命令和边界是 ROI 最高的两个**。把"运行测试"写成 `uv run pytest`（可直接执行的命令）比写成"使用项目配置的测试框架运行测试"有效 10 倍。边界（尤其是"绝不做"列表）是防止 AI 做蠢事的最后一道防线。
|
||
|
||
### **3.3. 模块化任务分解**
|
||
|
||
**原则：** 拆分为小的专项任务比放在一个大提示中更有效。
|
||
|
||
**实战体验：** 这是所有原则中最重要的一条。一个真实案例——让 AI "构建一个完整的 Web 框架"，结果是一团乱麻。但把同样的目标拆成"先实现 IoC 容器""再实现路由器""再实现配置管理"——每个子任务独立实现、独立测试——最终产出了 96 个通过的测试和清晰的分层架构。
|
||
|
||
### **3.4. 内置自检和约束**
|
||
|
||
**原则：** 让 AI 在完成后对比 Spec 检查需求合规性。
|
||
|
||
**实战体验：** Superpowers 的双阶段审查（先检查 Spec 合规性，再检查代码质量）是这条原则的最佳实现。但自检的可靠性取决于 Spec 的清晰度——模糊的 Spec 产生模糊的自检，形成"两个瞎子互相确认"的局面。
|
||
|
||
### **3.5. 持续测试、迭代和演进**
|
||
|
||
**原则：** Spec 是活文档，随项目演进持续更新。
|
||
|
||
**实战体验：** 这条原则的实践比听起来难得多。Spec 的更新有两个陷阱：一是"忘了更新"（代码改了但 Spec 没跟上），二是"过度更新"（每次对话都修改 Spec，导致 Spec 偏移原始意图）。我的解决方案是**把 Spec 纳入 Git 版本控制**，每次修改 Spec 都需要人类审批——和代码变更同等对待。
|
||
|
||
### **四、三种 Spec 组织模式对比**
|
||
|
||
不同项目规模和团队成熟度适合不同的 Spec 组织模式。
|
||
|
||
### **4.1. 单体模式：一个文件搞定一切**
|
||
|
||
```
|
||
project/
|
||
├── CLAUDE.md # 所有规范集中在一个文件
|
||
└── src/
|
||
```
|
||
|
||
**适用场景：** 单人、单功能、< 1000 行的小项目。
|
||
|
||
**优势：** 零认知负担，打开一个文件就能看到所有规则。**劣势：** 超过 200 行后 AI 遵从率下降，超过 500 行基本失控。
|
||
|
||
### **4.2. 模块化模式：多层分离**
|
||
|
||
```
|
||
project/
|
||
├── CLAUDE.md # 宪法层（< 200 行）
|
||
├── .claude/
|
||
│ ├── skills/ # 技能层（按任务类型）
|
||
│ │ ├── api-design.md
|
||
│ │ ├── coding.md
|
||
│ │ └── review.md
|
||
│ └── docs/ # 知识层（共享知识）
|
||
│ ├── coding-standards.md
|
||
│ └── api-guidelines.md
|
||
├── data/ # 状态层
|
||
│ ├── roadmap.yaml
|
||
│ └── decisions.md
|
||
└── src/
|
||
```
|
||
|
||
**适用场景：** 多功能项目、需要 AI 执行多种任务的场景。
|
||
|
||
**优势：** 各层独立维护，技能按需加载，避免"指令诅咒"。**劣势：** 初始搭建成本高，需要设计层间引用关系。
|
||
|
||
### **4.3. 流水线模式：Spec Kit 四阶段**
|
||
|
||
```
|
||
project/
|
||
├── .speckit/
|
||
│ ├── constitution.md # 宪法（全局约束）
|
||
│ ├── features/
|
||
│ │ ├── auth/
|
||
│ │ │ ├── spec.md # 功能规格
|
||
│ │ │ ├── plan.md # 技术方案
|
||
│ │ │ └── tasks.md # 任务分解
|
||
│ │ └── dashboard/
|
||
│ │ ├── spec.md
|
||
│ │ ├── plan.md
|
||
│ │ └── tasks.md
|
||
└── src/
|
||
```
|
||
|
||
**适用场景：** 大型团队、多人协作、需要流程可审计。
|
||
|
||
**优势：** 每个功能的 Spec 全生命周期可追溯。**劣势：** Martin Fowler 团队的批评——"审查这些 Markdown 比审查代码更累"。
|
||
|
||
|
||
|
||
### **4.4. 模式选择决策树**
|
||
|
||
| 条件 | 推荐模式 |
|
||
| --- | --- |
|
||
| 个人项目 + 单一功能 | 单体模式 |
|
||
| 个人/小团队 + 多功能 | 模块化模式 |
|
||
| 中大团队 + 新建项目 | 流水线模式 |
|
||
| 任何规模 + 已有代码库 | 模块化模式（Brownfield 友好） |
|
||
|
||
### **五、我的判断**
|
||
|
||
**Spec 架构设计的核心矛盾是"完备性 vs 简洁性"——写太少 AI 不知道怎么做，写太多 AI 记不住。**
|
||
|
||
我的实践结论是：**模块化模式是大多数场景的最优解**。
|
||
|
||
原因有三：
|
||
|
||
1. **宪法层控制在 200 行以内**，AI 遵从率最高
|
||
2. **技能层按需加载**，避免了"指令诅咒"和审查过载
|
||
3. **知识层和状态层提供了"长期记忆"**，解决了 AI"每次从零开始"的问题
|
||
|
||
流水线模式（Spec Kit）在理论上更完备，但实践中审查成本太高。除非团队有专职的 Spec 审查流程，否则流水线模式的规范文件最终会变成"写了但没人看"的废纸。
|
||
|
||
**一个反直觉的发现：写 Spec 的能力比选工具更重要。** 同样用 Claude Code，一个会写 Spec 的工程师和一个不会写的，产出质量差距可以到 5-10 倍。工具只是加速器，Spec 设计能力才是核心竞争力。
|
||
|
||
**给想开始的人一个最小起步方案：**
|
||
|
||
1. 创建 CLAUDE.md（或对应工具的配置文件），写清楚项目定位、技术栈、开发命令、硬性约束（< 100 行）
|
||
2. 把 Git 提交设为"先询问"
|
||
3. 跑两个迭代，观察 AI 在哪里犯错——把犯错点写进 Spec 作为新约束
|
||
4. 当 CLAUDE.md 超过 200 行，开始拆分为模块化模式
|
||
|
||
这四步大概需要 2 小时初始投入，但能在后续节省数十小时的返工时间。
|
||
|
||
### **六、对不同人的影响**
|
||
|
||
**技术负责人 / CTO：** Spec 架构是 AI 原生团队的"基础设施投资"。和 CI/CD 一样——前期搭建有成本，但长期回报巨大。考虑在团队中建立 Spec 模板库，让不同项目复用成熟的 Spec 架构模式。
|
||
|
||
**工程师 / 架构师：** 把"写好 Spec"当作一项新的工程技能来修炼。这不是写文档——这是在设计 AI 的执行环境。Spec 的质量直接决定了 AI 的产出质量。从 Addy Osmani 的五原则开始，在日常 AI 编程中刻意练习。
|
||
|
||
**普通用户：** 即使不用任何框架，只做一件事——在让 AI 写代码前，用 3-5 句话写清楚"我要什么、不要什么、用什么技术"——AI 的表现就会明显提升。这就是 Spec 的最小形态。
|
||
|
||
### **参考资料**
|
||
|
||
1. Addy Osmani. *How to Write a Good Spec for AI Agents*. addyosmani.com, 2026.
|
||
2. Addy Osmani. *Going into 2026: My LLM coding workflow*. addyosmani.com, 2026.
|
||
3. Jesse Vincent. *Superpowers*. blog.fsck.com, 2025.
|
||
4. Martin Fowler 团队. *Understanding SDD: Kiro, spec-kit, and Tessl*. martinfowler.com, 2025.
|
||
5. GitHub. *Spec Kit — Spec-Driven Development*. [http://github.com/github/spec-kit](https://link.zhihu.com/?target=http%3A//github.com/github/spec-kit).
|
||
6. Anthropic. *Claude Code Documentation: CLAUDE.md*. docs.anthropic.com.
|
||
7. Phodal. *AI 友好架构：AI 编程最佳实践范式*. phodal.com, 2026. |