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

如何用 AI + OpenSpec 驱动团队迭代开发 如何用 AI + OpenSpec 驱动团队迭代开发 Modified January 5 🔗 原文链接： https://mp.weixin.qq.com/s/CJPCsYoQ... 原创 数字生命贾克斯 数字生命贾克斯2026年1月3日 14:00 上海 读完需要6分钟 速读仅需 2 分钟 从混乱到有序，从口口相传到知识沉淀，我们用一次实践探索了 AI 辅助团队开发的完整架构。 1 一个真实的痛点 你是否遇到过这样的场景： 1. 写个正则表达式？AI 秒杀我。 2. 写个独立脚本？AI 真香。 3. 写个炫酷网页？AI 真牛 X！ 但是一旦将 AI 扔进一个庞大的微服务项目里，它似乎立刻降智为了“新手小白” ？ 由于 AI 无法理解 三年前写下的那段“奇葩代码”究竟为何，导致 每次对话都像“开盲盒”，Review AI 生成代码的时间，比自己重写一遍还要长。 这些问题的本质其实是：缺乏一个结构化的、AI 可理解的知识管理体系。 最近，我们在一个复杂的微服务项目中，探索并实践了一套 “人机协同迭代开发”的完整架构。整个过程没有额外编写一行工具代码，仅通过对话和现有工具链，就让 AI 从“项目小白”成长为“熟悉业务的开发伙伴”。 本文将完整还原这一过程，并总结出可复制的方法论。 2 第一步：建立 AI 可理解的“项目大脑” 大多数团队的文档是写给人看的，而非 AI： • ❌ 飞书/Confluence/Wiki 里的设计文档太多，太杂。 • ❌ 散落在各处的 README → AI 抓不住重点。 • ❌ 资深员工脑中的隐性知识 → AI 永远学不会。 我们的解法是引入 OpenSpec 规范，并基于它构建一整套“知识迭代体系”。 OpenSpec 核心理念极其简单： 让 AI 明确知道“知识在哪、如何用、以及为什么这样做”。 2.1 1.1 搭建“知识骨架” 无论是新项目还是历史项目，第一步都是通过命令行初始化一个标准的知识目录结构： Code block Plain Text Copy cd /path/to/your projectopenspec init 生成的目录结构，便是项目的“知识骨架”： Code block Plain Text Copy openspec/ ├── AGENTS.md 【大脑指令】AI 工作指南（开发规范、测试策略、错误码设计等） ├── project.md 【长期记忆】项目上下文（目标、核心术语、文档索引） ├── specs/ 【技能树】已实现能力的规范（做了什么） ├── changes/ 【短期记忆】待处理的变更提案（要做什么） └── docs/ 【知识库】详细文档（为什么这样做） 此举的核心在于为 AI 提供一个 明确的结构化索引 ，而非一股脑地塞入所有文档。 其中 docs 并非OpenSpec规范，而是自行创建的目录，后续用作详细索引时使用，需要手动创建。 2.2 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 每次迭代时都能遵循，从而保障业务知识的持续有效性和一致性。 3 第二步：协作机制——像管理代码一样管理“知识” 建立了初始知识库，还需让知识随着项目迭代而更新。我们引入了一套 Change Driven（变更驱动） 的协作流程，并将其作为团队核心准则严格执行。 所有新的需求或变更，都必须严格通过 OpenSpec 发起提案： 1. 需求变更 → 发起 OpenSpec 提案 ◦ 开发新需求时，必须通过 OpenSpec 创建提案（ changes/proposal xxx.md ）。 ◦ 人工审查重点 ：核对 AI 生成的提案中 Why（背景）、What（目标）、Impact（影响） 是否清晰一致，确保人与 AI 的理解对齐 。 2. AI 辅助实现 ◦ AI 读取已通过的提案，结合 specs/ 中已有的能力规范，生成或修改代码及测试用例。 ◦ 人工进行 Code View 3. 知识沉淀（归档） • 运行 openspec archive 命令。 • AI 将自动把 本次变更所涉及的新知识、新规范，更新到 specs/ 和 docs/ 中，完成知识入库。 通过这个流程，每一次需求迭代及其产生的代码，都完整地闭环并沉淀到 OpenSpec 体系里。AI 在处理后续需求时，便有了可追溯和借鉴的“历史经验”。 4 实践建议与场景考量 在实际操作中，你还会遇到一些具体问题，例如： Q: 微服务项目下子服务众多，应该每个服务初始化一套 OpenSpec，还是整个项目共用一套？ 我们的经验则是 ：基于知识独立性进行判断。 • 如果某个模块（如用户中心）的业务知识与其他模块重合度很低（例如<30%）， 独立初始化一 个 OpenSpec 目录是更清晰的选择。 • 如果多个服务共享大量共性业务知识（重合度 70%）， 共用一套O penSpec 更能保证知识的一致性和 AI 的理解效率。 不同的业务架构需要灵活采用不同的策略。 5 走向“人 + AI”的团队协作 当这套以知识为核心的迭代体系稳固运行后，你会发现： • 隐性知识被彻底显性化 。 • 新成员（包括 AI） 学习成本大幅降低 。 • 在后续编写接口文档、架构迭代或代码重构时， AI 的效能将被成倍放大 。 未来的高效团队协作，是 “人 + AI” 的深 度融合。让 AI 成为团队忠实的“知识伙伴”而不仅仅是临时的“代码助手”，这，才是 AI 时代团队开发的正确打开方式。 好文章值得被更多人看见！既然看到这里了，随手点个赞👍和关注，并转发给更多的朋友吧！感谢。 作者：数字生命贾克斯、微信：x h886688 https://mp.weixin.qq.com/s/CJPCsYoQ... 🔗 原文链接： https://mp.weixin.qq.com/s/CJPCsYoQ... https://mp.weixin.qq.com/s/CJPCsYoQ... 原创 数字生命贾克斯 数字生命贾克斯2026年1月3日 14:00 上海 读完需要6分钟 速读仅需 2 分钟 从混乱到有序，从口口相传到知识沉淀，我们用一次实践探索了 AI 辅助团队开发的完整架构。 1 一个真实的痛点 你是否遇到过这样的场景： 1. 写个正则表达式？AI 秒杀我。 2. 写个独立脚本？AI 真香。 3. 写个炫酷网页？AI 真牛 X！ 但是一旦将 AI 扔进一个庞大的微服务项目里，它似乎立刻降智为了“新手小白” ？ 由于 AI 无法理解 三年前写下的那段“奇葩代码”究竟为何，导致 每次对话都像“开盲盒”，Review AI 生成代码的时间，比自己重写一遍还要长。 这些问题的本质其实是：缺乏一个结构化的、AI 可理解的知识管理体系。 最近，我们在一个复杂的微服务项目中，探索并实践了一套 “人机协同迭代开发”的完整架构。整个过程没有额外编写一行工具代码，仅通过对话和现有工具链，就让 AI 从“项目小白”成长为“熟悉业务的开发伙伴”。 本文将完整还原这一过程，并总结出可复制的方法论。 2 第一步：建立 AI 可理解的“项目大脑” 大多数团队的文档是写给人看的，而非 AI： • ❌ 飞书/Confluence/Wiki 里的设计文档太多，太杂。 • ❌ 散落在各处的 README → AI 抓不住重点。 • ❌ 资深员工脑中的隐性知识 → AI 永远学不会。 我们的解法是引入 OpenSpec 规范，并基于它构建一整套“知识迭代体系”。 OpenSpec 核心理念极其简单： 让 AI 明确知道“知识在哪、如何用、以及为什么这样做”。 2.1 1.1 搭建“知识骨架” 无论是新项目还是历史项目，第一步都是通过命令行初始化一个标准的知识目录结构： 生成的目录结构，便是项目的“知识骨架”： 此举的核心在于为 AI 提供一个 明确的结构化索引 ，而非一股脑地塞入所有文档。 其中 docs 并非OpenSpec规范，而是自行创建的目录，后续用作详细索引时使用，需要手动创建。 2.2 1.2 让 AI “认识”你的项目 对于已有项目，AI 起初面对一片空白。我们采用 “索引层 + 明细层” 的双层结构来填充知识。 • 索引层（ AGENTS.md & project.md ） • 这 里不写长篇大论，只提供“地图”。 ◦ AGENTS.md ：定义 AI 的核心开发规范（如命名、错误码、测试策略）。 ◦ project.md ：阐述业务共性知识（如项目目标、核心术语、需求概要），并指明各项项详细文档在 docs/ 中的位置索引。 ◦ AGENTS.md ：定义 AI 的核心开发规范（如命名、错误码、测试策略）。 ◦ project.md ：阐述业务共性知识（如项目目标、核心术语、需求概要），并指明各项项详细文档在 docs/ 中的位置索引。 • 明细层（ openspec/docs/ ）： 这里存放真正的“干货”：详细的架构设计、复杂的需求文档、业务逻辑说明。 工作流形成闭环： 当 AI 接到任务 → 先读 AGENTS.md （获取规范）→ 再读 project.md （获取业务背景）→ 根据索引定位到 docs/ 下的具体文档 → 深刻理解上下文后开始工作。 最棒的是： 你无需手动编写这些索引。只需发起一个 OpenSpec 提案，通过对话引导 AI 自己去梳理项目架构和业务，它便能自动生成初始的 project.md 内容。 知识迭代提示：后续在 docs/ 下维护新知识时，需引导 AI 基于更新后的知识库，重新总结生成新的 project.md。为此，我们可以定义一个《文档管理指南》作为准则，确保 AI 每次迭代时都能遵循，从而保障业务知识的持续有效性和一致性。 3 第二步：协作机制——像管理代码一样管理“知识” 建立了初始知识库，还需让知识随着项目迭代而更新。我们引入了一套 Change Driven（变更驱动） 的协作流程，并将其作为团队核心准则严格执行。 所有新的需求或变更，都必须严格通过 OpenSpec 发起提案： 1. 需求变更 → 发起 OpenSpec 提案 ◦ 开发新需求时，必须通过 OpenSpec 创建提案（ changes/proposal xxx.md ）。 ◦ 人工审查重点 ：核对 AI 生成的提案中 Why（背景）、What（目标）、Impact（影响） 是否清晰一致，确保人与 AI 的理解对齐 。 ◦ 开发新需求时，必须通过 OpenSpec 创建提案（ changes/proposal xxx.md ）。 ◦ 人工审查重点 ：核对 AI 生成的提案中 Why（背景）、What（目标）、Impact（影响） 是否清晰一致，确保人与 AI 的理解对齐 。 2. AI 辅助实现 ◦ AI 读取已通过的提案，结合 specs/ 中已有的能力规范，生成或修改代码及测试用例。 ◦ 人工进行 Code View ◦ AI 读取已通过的提案，结合 specs/ 中已有的能力规范，生成或修改代码及测试用例。 ◦ 人工进行 Code View 3. 知识沉淀（归档） • 运行 openspec archive 命令。 • AI 将自动把 本次变更所涉及的新知识、新规范，更新到 specs/ 和 docs/ 中，完成知识入库。 通过这个流程，每一次需求迭代及其产生的代码，都完整地闭环并沉淀到 OpenSpec 体系里。AI 在处理后续需求时，便有了可追溯和借鉴的“历史经验”。 4 实践建议与场景考量 在实际操作中，你还会遇到一些具体问题，例如： Q: 微服务项目下子服务众多，应该每个服务初始化一套 OpenSpec，还是整个项目共用一套？ 我们的经验则是 ：基于知识独立性进行判断。 • 如果某个模块（如用户中心）的业务知识与其他模块重合度很低（例如<30%）， 独立初始化一 个 OpenSpec 目录是更清晰的选择。 • 如果多个服务共享大量共性业务知识（重合度 70%）， 共用一套O penSpec 更能保证知识的一致性和 AI 的理解效率。 不同的业务架构需要灵活采用不同的策略。 5 走向“人 + AI”的团队协作 当这套以知识为核心的迭代体系稳固运行后，你会发现： • 隐性知识被彻底显性化 。 • 新成员（包括 AI） 学习成本大幅降低 。 • 在后续编写接口文档、架构迭代或代码重构时， AI 的效能将被成倍放大 。 未来的高效团队协作，是 “人 + AI” 的深 度融合。让 AI 成为团队忠实的“知识伙伴”而不仅仅是临时的“代码助手”，这，才是 AI 时代团队开发的正确打开方式。 好文章值得被更多人看见！既然看到这里了，随手点个赞👍和关注，并转发给更多的朋友吧！感谢。 作者：数字生命贾克斯、微信：x h886688