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

一个真实的痛点你是否遇到过这样的场景写个正则表达式AI 秒杀我。写个独立脚本AI 真香。写个炫酷网页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.mdproject.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 时代团队开发的正确打开方式。