如何用 AI + OpenSpec 驱动团队迭代开发

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

一个真实的痛点

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

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

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

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

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

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

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

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

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

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

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

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

1.1 搭建"知识骨架"

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

bash 复制代码

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 发起提案：

需求变更 → 发起 OpenSpec 提案
- 开发新需求时，必须通过 OpenSpec 创建提案（changes/proposal-xxx.md）。
- 人工审查重点：核对 AI 生成的提案中 Why（背景）、What（目标）、Impact（影响） 是否清晰一致，确保人与 AI 的理解对齐。
AI 辅助实现
- AI 读取已通过的提案，结合 specs/ 中已有的能力规范，生成或修改代码及测试用例。
- 人工进行 Code Review。
知识沉淀（归档）
- 运行 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 驱动团队迭代开发

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