15 KiB

Raw Blame History

一份CLAUDEmd统治一个AI团队Spec架构设计的四层模型

TL;DR：

AI 原生开发的 Spec 不是传统的需求文档——它是"给 Agent 的操作系统"，决定了 AI 如何理解项目、如何执行任务、如何自我约束
好的 Spec 架构分四层：宪法层（项目级配置）→ 技能层（可组合的执行模块）→ 知识层（共享领域知识）→ 状态层（持久化记忆），每层各司其职
Spec 写作的核心原则是"少即是多"——200 行精心设计的 Markdown 远胜 2000 行面面俱到的文档

一、背景：传统需求文档为什么对 AI 不管用

把一份 50 页的 PRD 丢给 AI，让它"照着做"——这大概是 2025 年最常见的 AI 编程失败模式之一。

原因很简单：传统需求文档是写给人看的，它假设读者有上下文、有判断力、会主动填补信息缺口。AI 没有这些能力。你写"参考现有模块的设计风格"，人类工程师知道去看 git log 和代码风格，AI 只会猜。你写"考虑边界情况"，人类知道哪些边界重要，AI 不知道——要么忽略，要么过度防御。

Addy Osmani（Google Chrome 团队工程师）在 2026 年初发表了一篇关于"如何为 AI Agent 写好 Spec"的深度指南，核心观点是：AI 需要的不是"需求文档"，而是"执行环境"。这个"执行环境"需要回答三个问题：

我是谁？（项目定位、技术栈、代码风格）
我能做什么？（允许的操作、禁止的操作、边界）
我怎么做？（工作流程、验证标准、交付格式）

这三个问题，恰好对应了一种新的 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 记不住。

我的实践结论是：模块化模式是大多数场景的最优解。

原因有三：

宪法层控制在 200 行以内，AI 遵从率最高
技能层按需加载，避免了"指令诅咒"和审查过载
知识层和状态层提供了"长期记忆"，解决了 AI"每次从零开始"的问题

流水线模式（Spec Kit）在理论上更完备，但实践中审查成本太高。除非团队有专职的 Spec 审查流程，否则流水线模式的规范文件最终会变成"写了但没人看"的废纸。

一个反直觉的发现：写 Spec 的能力比选工具更重要。 同样用 Claude Code，一个会写 Spec 的工程师和一个不会写的，产出质量差距可以到 5-10 倍。工具只是加速器，Spec 设计能力才是核心竞争力。

给想开始的人一个最小起步方案：

创建 CLAUDE.md（或对应工具的配置文件），写清楚项目定位、技术栈、开发命令、硬性约束（< 100 行）
把 Git 提交设为"先询问"
跑两个迭代，观察 AI 在哪里犯错——把犯错点写进 Spec 作为新约束
当 CLAUDE.md 超过 200 行，开始拆分为模块化模式

这四步大概需要 2 小时初始投入，但能在后续节省数十小时的返工时间。

六、对不同人的影响

技术负责人 / CTO： Spec 架构是 AI 原生团队的"基础设施投资"。和 CI/CD 一样——前期搭建有成本，但长期回报巨大。考虑在团队中建立 Spec 模板库，让不同项目复用成熟的 Spec 架构模式。

工程师 / 架构师： 把"写好 Spec"当作一项新的工程技能来修炼。这不是写文档——这是在设计 AI 的执行环境。Spec 的质量直接决定了 AI 的产出质量。从 Addy Osmani 的五原则开始，在日常 AI 编程中刻意练习。

普通用户： 即使不用任何框架，只做一件事——在让 AI 写代码前，用 3-5 句话写清楚"我要什么、不要什么、用什么技术"——AI 的表现就会明显提升。这就是 Spec 的最小形态。

参考资料

Addy Osmani. How to Write a Good Spec for AI Agents. addyosmani.com, 2026.
Addy Osmani. Going into 2026: My LLM coding workflow. addyosmani.com, 2026.
Jesse Vincent. Superpowers. blog.fsck.com, 2025.
Martin Fowler 团队. Understanding SDD: Kiro, spec-kit, and Tessl. martinfowler.com, 2025.
GitHub. Spec Kit — Spec-Driven Development. http://github.com/github/spec-kit.
Anthropic. Claude Code Documentation: CLAUDE.md. docs.anthropic.com.
Phodal. AI 友好架构：AI 编程最佳实践范式. phodal.com, 2026.

15 KiB Raw Blame History Unescape Escape