如何用 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 搭建“知识骨架”

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

1. cd /path/to/your-project
2. openspec init

复制代码

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

1. openspec/
2. ├── AGENTS.md       # 【大脑指令】AI 工作指南（开发规范、测试策略、错误码设计等）
3. ├── project.md      # 【长期记忆】项目上下文（目标、核心术语、文档索引）
4. ├── specs/          # 【技能树】已实现能力的规范（做了什么）
5. ├── changes/        # 【短期记忆】待处理的变更提案（要做什么）
6. └── 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，还是整个项目共用一套？
我们的经验则是：基于知识独立性进行判断。

• 如果某个模块（如用户中心）的业务知识与其他模块重合度很低（例如70%），共用一套OpenSpec 更能保证知识的一致性和 AI 的理解效率。
  

不同的业务架构需要灵活采用不同的策略。
走向“人 + AI”的团队协作

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

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

未来的高效团队协作，是 “人 + AI” 的深度融合。让 AI 成为团队忠实的“知识伙伴”而不仅仅是临时的“代码助手”，这，才是 AI 时代团队开发的正确打开方式。
欢迎日常交流
AI 驱动团队开发是这个时代的新命题，欢迎大家加微信互相交流心得。


来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！