原文地址：如何用 AI + OpenSpec 驱动团队迭代开发

从混乱到有序，从口口相传到知识沉淀，我们用一次实践探索了 AI 辅助团队开发的完整架构

一个真实的痛点

你是否遇到过这样的场景：

1. 写个正则表达式？ AI 秒杀我。
2. 写个独立脚本？ AI 真香。
3. 写个炫酷网页？ AI 真牛 X ！

但是一旦将 AI 扔进一个庞大的微服务项目里，它似乎立刻降智为了“新手小白”？

由于 AI 无法理解三年前写下的那段“奇葩代码”究竟为何，导致每次对话都像“开盲盒”，Review AI 生成代码的时间，比自己重写一遍还要长。

这些问题的本质其实是：缺乏一个结构化的、AI 可理解的知识管理体系。

最近，我们在一个复杂的微服务项目中，探索并实践了一套 “人机协同迭代开发”的完整架构。整个过程没有额外编写一行工具代码，仅通过对话和现有工具链，就让 AI 从“项目小白”成长为“熟悉业务的开发伙伴”。

本文将完整还原这一过程，并总结出可复制的方法论。

第一步：建立 AI 可理解的“项目大脑”

大多数团队的文档是写给人看的，而非 AI：

• ❌ 飞书/Confluence/Wiki 里的设计文档太多，太杂。
• ❌ 散落在各处的 README → AI 抓不住重点。
• ❌ 资深员工脑中的隐性知识 → AI 永远学不会。

我们的解法是引入 OpenSpec 规范，并基于它构建一整套“知识迭代体系”。

OpenSpec 核心理念极其简单：让 AI 明确知道“知识在哪、如何用、以及为什么这样做”。

1.1 搭建“知识骨架”

无论是新项目还是历史项目，第一步都是通过命令行初始化一个标准的知识目录结构：

cd /path/to/your-project
openspec init

生成的目录结构，便是项目的“知识骨架”：

openspec/
 ├── AGENTS.md       #  [大脑指令]  AI 工作指南（开发规范、测试策略、错误码设计等）
 ├── project.md      #  [长期记忆] 项目上下文（目标、核心术语、文档索引）
 ├── specs/          #  [技能树] 已实现能力的规范（做了什么）
 ├── changes/        #  [短期记忆] 待处理的变更提案（要做什么）
 └── docs/           #  [知识库] 详细文档（为什么这样做）

此举的核心在于为 AI 提供一个明确的结构化索引，而非一股脑地塞入所有文档。

其中 docs 并非 OpenSpec 规范，而是自行创建的目录，后续用作详细索引时使用，需要手动创建。

1.2 让 AI “认识”你的项目

对于已有项目，AI 起初面对一片空白。我们采用 “索引层 + 明细层” 的双层结构来填充知识。

索引层（AGENTS.md & project.md）

这里不写长篇大论，只提供“地图”。

• AGENTS.md：定义 AI 的核心开发规范（如命名、错误码、测试策略）。
• project.md：阐述业务共性知识（如项目目标、核心术语、需求概要），并指明各项详细文档在 docs/ 中的位置索引。

明细层（openspec/docs/）：这里存放真正的“干货”：详细的架构设计、复杂的需求文档、业务逻辑说明。

工作流形成闭环：当 AI 接到任务 → 先读 AGENTS.md（获取规范）→ 再读 project.md（获取业务背景）→ 根据索引定位到 docs/ 下的具体文档 → 深刻理解上下文后开始工作。

最棒的是：你无需手动编写这些索引。只需发起一个 OpenSpec 提案，通过对话引导 AI 自己去梳理项目架构和业务，它便能自动生成初始的 project.md 内容。

知识迭代提示：后续在 docs/ 下维护新知识时，需引导 AI 基于更新后的知识库，重新总结生成新的 project.md 。为此，我们可以定义一个《文档管理指南》作为准则，确保 AI 每次迭代时都能遵循，从而保障业务知识的持续有效性和一致性。

第二步：协作机制——像管理代码一样管理“知识”

建立了初始知识库，还需让知识随着项目迭代而更新。我们引入了一套 Change-Driven （变更驱动） 的协作流程，并将其作为团队核心准则严格执行。

所有新的需求或变更，都必须严格通过 OpenSpec 发起提案：

1. 需求变更 → 发起 OpenSpec 提案
   • 开发新需求时，必须通过 OpenSpec 创建提案（changes/proposal-xxx.md）。
   • 人工审查重点：核对 AI 生成的提案中 Why （背景）、What （目标）、Impact （影响） 是否清晰一致，确保人与 AI 的理解对齐。
2. AI 辅助实现
   • AI 读取已通过的提案，结合 specs/ 中已有的能力规范，生成或修改代码及测试用例。
   • 人工进行 Code Review 。
3. 知识沉淀（归档）
   • 运行 openspec archive 命令。
   • AI 将自动把本次变更所涉及的新知识、新规范，更新到 specs/ 和 docs/ 中，完成知识入库。

通过这个流程，每一次需求迭代及其产生的代码，都完整地闭环并沉淀到 OpenSpec 体系里。AI 在处理后续需求时，便有了可追溯和借鉴的“历史经验”。

实践建议与场景考量

在实际操作中，你还会遇到一些具体问题，例如：

Q：微服务项目下子服务众多，应该每个服务初始化一套 OpenSpec ，还是整个项目共用一套？

我们的经验则是：基于知识独立性进行判断。

• 如果某个模块（如用户中心）的业务知识与其他模块重合度很低（例如<30%），独立初始化一个 OpenSpec 目录是更清晰的选择。
• 如果多个服务共享大量共性业务知识（重合度>70%），共用一套 OpenSpec 更能保证知识的一致性和 AI 的理解效率。

不同的业务架构需要灵活采用不同的策略。

走向“人 + AI”的团队协作

当这套以知识为核心的迭代体系稳固运行后，你会发现：

• 隐性知识被彻底显性化。
• 新成员（包括 AI ） 学习成本大幅降低。
• 在后续编写接口文档、架构迭代或代码重构时，AI 的效能将被成倍放大。

未来的高效团队协作，是 “人 + AI” 的深度融合。让 AI 成为团队忠实的“知识伙伴”而不仅仅是临时的“代码助手”，这，才是 AI 时代团队开发的正确打开方式。

欢迎日常交流

AI 驱动团队开发是这个时代的新命题，欢迎大家加微信互相交流心得。

👉 想要进群的朋友，扫码时备注 “AI 实验群”，看到消息后会第一时间拉你进群。

群定位：AI 工具提效/实战经验互助 群规则：不水群、不广告、干货优先

欢迎访问该链接获取群信息： https://zhaozhihao.com/archives/KRMxDLo4

好文章值得被更多人看见！既然看到这里了，随手点个赞👍和关注，并转发给更多的朋友吧！感谢。

作者：数字生命贾克斯、微信：x_h886688

个人网站文章地址：如何用 AI + OpenSpec 驱动团队迭代开发