夜雨聆风最近复盘 Atlas Knowledge Hub 的开发过程时，我发现一个很有意思的现象。
这个项目里最重要的早期资产，不是某个漂亮页面。
也不是某个后端接口。
而是一组看起来不太性感的文件：
• AGENTS.md• PROJECT_RULES.md• DEVELOPMENT_STANDARDS.md• docs/00-context/sdd-profile.md• .github/copilot-instructions.md
如果按传统软件项目的视角看，这些东西很容易被归类成“文档”。
但在 AI 时代，它们不是文档。
它们更像项目的运行环境。
因为真正的问题已经变了。
以前我们问的是：开发者怎么把代码写对？
现在还要多问一句：agent 怎么理解任务、怎么执行、怎么证明自己做对了？
Atlas 给我的最大启发是：
AI Coding 的核心，不是让模型多写几行代码，而是设计一套让 AI 稳定交付正确代码的系统。
先把几个词说清楚
这篇文章会反复出现几个词。
如果你已经熟悉 AI Coding 或 Agentic SDLC，可以直接往后读。
如果第一次看到，先用下面这组解释垫一下。
SDD，可以理解成 Spec-Driven Development，也就是“先把规格写清楚，再让代码对齐规格”。
这里的规格不是一份大而全的需求文档。
它更像一组可追踪的工程合同：需求是什么、用户故事是什么、系统行为是什么、接口怎么设计、数据怎么流、验收标准是什么。
模型可以写代码，但不能随便发明行为。
source of truth，就是“以谁为准”。
一个项目里可能有聊天记录、会议纪要、README、代码注释、测试、PR 讨论。
但当它们互相冲突时，必须有一个地方说了算。
在 Atlas 里，行为以 docs/03-spec/ 为准，任务以 docs/06-tasks/ 为准，执行证据以 traceability 文档为准。
Goal，不是一句“帮我做一下”。
它是一份本次执行合同：这次要交付什么、做哪些、不做哪些、参考哪些 SDD、怎么验收、跑什么检查、遇到什么情况必须停。
Goal 写得越清楚，agent 越不容易一路做散。
Loop Engineering，不是让 AI 无限重试。
它是把“实现、运行检查、修复失败、补充证据、再次验证”做成一个受控循环。
循环可以自动推进，但必须知道什么时候停，尤其不能绕过测试和 gate。
Gate，就是自动化红绿灯。
比如本地的 npm run agent:closeout，或者 CI 里的 required check。
它不关心 agent 写得多努力，只判断这次交付有没有通过同一套标准。
Lessons Learned，也不是写一篇复盘感想。
它的意思是：如果这次犯了错，就把这个错沉淀成下一次更难再犯的机制。
可能是补一条 spec，补一个 test，补一个 checklist，也可能是改一条 agent instruction。
这几个词背后，其实是同一个问题：
AI 可以很聪明，但项目必须更清楚。
先建项目规则，再让 AI 写代码
AI 时代开新项目，最容易做的事，是直接让模型 scaffold。
“帮我搭一个 Vue + Spring Boot 项目。”
“帮我写一个登录模块。”
“帮我把这个页面补出来。”
这些都能做。
而且一开始会显得很快。
但 Atlas 的经验刚好相反。
越是准备让 AI 深度参与开发，越要先把项目规则立起来。
AGENTS.md 告诉 agent 怎么工作。
PROJECT_RULES.md 定义产品、架构、安全、SDD 的硬约束，也就是哪些行为不能靠模型临场发挥。
DEVELOPMENT_STANDARDS.md 定义测试、CI、review 和工程质量标准。
sdd-profile.md 定义这个项目自己的 SDD 形态：一条需求从规格、设计到任务，应该长成什么样。
.github/copilot-instructions.md 则给公司内部常用的 GitHub Copilot Chat 一个稳定入口。
这些文件做的不是“说明情况”。
它们是在降低模型每次临场发挥的空间。
没有这些规则，模型只能根据当前 prompt 猜项目习惯。
换一个人、换一个模型、换一个 IDE，输出风格和判断标准就会漂移。
短期看，它很灵活。
长期看，它会变成混乱。
有了这些规则，模型不是凭感觉工作，而是在项目定义好的边界里工作。
所以 AI 时代的项目初始化，不应该只问“用什么技术栈”。
还要问：
• agent 应该先读哪些文件？ • 哪些行为绝对不能做？ • SDD 的 source of truth 在哪里？ • 什么叫完成？ • 什么情况必须停下来？ • 经验教训沉淀到哪里？
这不是流程洁癖。
这是给 AI 开发建立“项目宪法”。
SDD 的价值，是让模型少猜
Atlas 不是从一句 prompt 直接跳到代码。
我们把一个 feature slice 拆成一条 SDD 链路。
这里的 feature slice，可以理解成一块可独立交付的小功能。
比如不是“把整个知识库系统做完”，而是“先把 wiki ingest 这一个端到端流程做完”。
它的 SDD 链路大概长这样：
requirements-> user stories-> spec-> architecture-> data flow-> data model-> design-> API implementation guide-> tasks-> implementation这里最关键的不是“文档很多”。
而是 source of truth 很清楚。
在 Atlas 里：
• docs/03-spec/是行为 source of truth。• docs/06-tasks/是实现 checklist。• docs/00-context/{slice}-traceability.md记录执行证据和状态。• 新增或更新的 SDD 文档，要保持英文和简体中文同步。
这几类文档分工不同。
spec 说“系统应该表现成什么样”。
tasks 说“实现时要按哪些步骤收口”。
traceability 说“这次执行到底做了什么、跑了什么、证据在哪里”。
这套机制解决的是 AI Coding 里一个很常见的问题：
模型很擅长补全，也很容易补过头。
如果没有 SDD，用户一句“帮我实现 wiki ingest”，模型可能会顺手加权限、加数据库、加外部服务、加复杂抽象。
看起来很完整。
但未必是当前阶段需要的东西。
Atlas 的规则是：
实现不能超过已接受的 SDD。
如果代码行为和 spec 不一致，要么先更新 SDD，要么停止并报告 mismatch。
这样一来，开发就不再是“模型觉得应该这么做”。
而是“实现必须对齐已接受的行为合同”。
SDD 的价值不是写厚文档。
它的价值是把模糊空间变小。
模糊空间越小，agent 越少猜。
Goal 决定边界，Loop 负责推进，Gate 负责刹车
一个好的 AI 开发任务，不应该只是：
帮我实现 wiki ingest。这句话太轻了。
它没有告诉 agent 边界在哪里，也没有告诉 agent 怎么证明完成。
在 Atlas 里，我更愿意把它转换成一个 goal。
所谓 goal，不是给模型一句更完整的 prompt。
它是把这次任务写成一张“交付卡”。
一个 goal 至少要说清楚：
• Goal：要交付什么用户可见结果。 • Slice：属于哪个稳定 slice。 • Scope：包含什么。 • Out of scope：不包含什么。 • Source of truth：哪些 SDD 文件是准绳。 • Acceptance：什么现象证明完成。 • Verification：要跑哪些命令和检查。 • Constraints：哪些安全、数据、架构边界不能突破。
这就是 Goal 模式的本质。
它不是一句需求。
它是一份执行合同。
在 Codex Agent Goal Mode 里，Codex 可以作为 loop runner：
读规则，读 SDD，执行任务，跑测试，修失败，再跑 gate，直到完成或遇到 blocker。
Loop Engineering 的价值也在这里体现出来。
Loop Engineering 听起来有点抽象，其实就是不把 AI 开发当成“一次生成”。
它把 AI 的工作拆成一个循环：
实现一点-> 跑检查-> 看失败原因-> 修复-> 再验证-> 留下证据也就是说，AI 开发不是一次生成完就结束。
它应该不断验证、修复、补证据。
但 loop 不能绕过 gate。
一句话：
Goal 决定边界，Loop 负责推进，Gate 负责刹车。
没有 Goal，agent 会越做越散。
没有 Loop，SDD 只是一堆静态文档。
没有 Gate，自动化会变成失控的自动化。
Atlas 现在用 npm run agent:closeout 和 GitHub Actions 的 Agent Workflow Gate 把 closeout 变成红灯/绿灯。
这里的 closeout，可以理解成“交付前结案检查”。
代码可以写完，但只有 closeout 通过，才算这次任务有证据地完成。
agent 可以循环修复。
但最终要接受 gate 的裁判。
这一步很重要。
因为团队真正需要的不是“AI 看起来很努力”。
团队需要的是：它有没有用同一套标准证明自己完成了。
稳定输出不是靠模型自觉
很多团队推广 AI 开发时，会本能地把希望放在 prompt 上。
仿佛只要写出一个足够完整的 prompt，就能让不同人、不同模型、不同环境得到稳定输出。
Atlas 的经验是：
prompt 是入口。
不是制度。
真正稳定的东西，应该分布在模型外部。
比如：
1. Repository instructions： AGENTS.md、.github/copilot-instructions.md、PROJECT_RULES.md。2. SDD source of truth： docs/03-spec/、docs/06-tasks/、traceability docs。3. Local gates：本地红绿灯，比如 npm run agent:check-sdd、npm run agent:closeout。4. CI gate：远端红绿灯，比如 GitHub Actions Agent Workflow Gate。5. Branch protection：把 Agent Workflow Gate设置成 required check。
这样，即使团队里有人用 Codex，有人用 GitHub Copilot Chat，有人只让模型改一个小文件，结果也会被拉回同一条轨道。
工具可以不同。
完成标准不能不同。
这也是为什么公司内部只使用 GitHub Copilot Chat，并不妨碍这套 workflow 落地。
Copilot Chat 不一定有 Codex 的 goal state。
也不一定能执行项目本地 .agents/skills。
但它可以读取 .github/copilot-instructions.md，按 SDD 实现，让开发者运行命令，最后由 npm run agent:closeout 和 CI gate 判断是否通过。
真正稳定的不是某个模型。
而是模型外面的工程系统。
Lessons Learned 不是复盘文档，是系统升级入口
AI 开发最浪费的事情，是同一个错误在不同对话里反复发生。
这件事很隐蔽。
因为每一次单独看，都像“这次 prompt 没写清楚”。
但如果错误会重复出现，它就不是单次沟通问题。
它是系统没有吸收教训。
Atlas 的规则是：当评审发现 mismatch 时，不只是解释，也不只是修当前代码。
还要判断它是不是一个可复用教训。
如果是，就沉淀到：
• docs/00-context/lessons-learned.md• 对应的 SDD 文档 • task verification • development standards • project rules • agent instructions • checklist • tests
背后的原则很简单：
一次错误，至少要改进一个预防机制。
如果只是把经验留在聊天记录里，下一次换模型、换人、换上下文，错误还会回来。
真正有用的 lesson learned，不是“我们以后注意”。
而是追问：
• 哪个 requirement 应该补？ • 哪个 spec 应该改？ • 哪个 task 应该增加验收项？ • 哪个 gate 应该检查？ • 哪个 test 应该覆盖？ • 哪条 agent instruction 应该写死？
这才是 agent 持续进化的方式。
不是期待模型永远不犯错。
而是让每次犯错，都让系统更难犯同样的错。
Codex Agent 和 Copilot Chat，要分清责任边界
Atlas 现在把两种模式分得很清楚。
第一种是 Codex Agent Goal Mode。
它适合个人电脑、外部开发环境，或者 agent 能完整运行命令和修复循环的场景。
在这个模式下，Codex 是 loop runner：
• 读取项目规则和 SDD。 • 创建或复用 execution manifest。 • 使用 goal prompt。 • 必要时使用项目本地 SDD skills。 • 实现一个 slice。 • 跑测试和 gate。 • 修复失败。 • 输出 closeout evidence。
这种模式适合完整 slice、长任务、SDD-to-code、复杂验证。
第二种是 GitHub Copilot Chat Mode。
它更适合公司内部默认环境。
在这个模式下，Copilot 是 implementation assistant，人是 loop operator，repo gate 是 controller。
Copilot Chat 应该做的是：
• 读取 .github/copilot-instructions.md。• 读取 AGENTS.md、PROJECT_RULES.md、DEVELOPMENT_STANDARDS.md。• 读取相关 SDD。 • 小步实现。 • 告诉开发者要运行哪些命令。 • 不把未跑过的 gate 说成通过。
它不应该假设自己拥有 Codex goal state。
也不应该假装已经跑过项目本地 SDD skill chain。
这不是降低标准。
这是把责任边界说清楚。
Codex Agent 是更强的自动执行模式。
Copilot Chat 是更普遍的团队协作模式。
两者共享同一套 SDD、规则、gate 和 lessons learned。
团队推广 AI，不该只培训 prompt
如果要把这套方式在团队里大规模推广，重点不应该是教大家“怎么和 AI 聊天”。
当然，prompt 能力有用。
但它不是最应该标准化的东西。
更应该标准化的是：
• repo 初始化模板 • AGENTS.md• .github/copilot-instructions.md• PROJECT_RULES.md• DEVELOPMENT_STANDARDS.md• SDD profile • SDD artifact templates • goal prompt templates • Copilot Chat 启动 prompt • closeout checklist • agent:check-sdd• agent:closeout• GitHub Actions gate • branch protection required check • lessons learned loop
团队可以允许不同的人使用不同工具。
但不能允许每个人使用不同的完成标准。
这是 AI 时代开发管理的变化。
过去重点是规范人怎么写代码。
现在还要规范 agent 怎么理解任务、怎么执行、怎么证明完成。
最终目标不是让每个人都成为 prompt expert。
最终目标是让项目本身足够清楚、足够可验证、足够能吸收教训。
这样，不同人、不同模型进入项目后，才会沿着同一条轨道工作。
结语
如果用一句话总结 Atlas 当前的模式，我会说：
Spec-driven + agent-executed + CI-governed software delivery.
更通俗一点：
让 AI 写代码，但让项目系统决定什么算正确。
这套模式不是传统敏捷，也不是简单 AI Coding。
它是把 AI 放进一个工程闭环里：
Project Rules-> SDD-> Goal-> Loop-> Implementation-> Verification-> CI Gate-> Lessons Learned-> Updated Rules / SDD / Tests每一环都不是装饰。
Project Rules 让模型知道边界。
SDD 让模型知道事实。
Goal 让模型知道本次任务。
Loop 让模型能推进和修复。
Verification 让结果有证据。
CI Gate 让失败变红灯。
Lessons Learned 让系统持续变好。
模型会变。
工具会变。
团队环境也会变。
但只要项目有清楚的规则、稳定的 SDD、明确的 goal、可循环的执行方式、自动化 gate、可沉淀的 lessons learned，它就能持续吸收不同 agent 的能力。
而不是被不同 agent 的差异拖着走。
AI 时代，优秀开发团队的核心能力会从“写代码”扩展为：
设计一个让 AI 稳定产出正确代码的系统。
Atlas Knowledge Hub 正在变成这样一个系统。
来源
本文基于 Atlas Knowledge Hub 项目复盘原稿整理改写：/Users/leo/wwa-lab/GitHub/atlas-knowledge-hub/docs/00-context/ai-era-development-retrospective.zh-CN.md。
往期推荐：