AI 辅助开发的可维护性与团队规范统一：从 Rules 到 SDD 的工程化方案

AI 写代码已经越来越强，但真正放到生产环境里，问题变成了：代码能不能长期维护、团队多人多工具协作时风格能不能统一。这篇文章讨论的正是这两个痛点，以及 2026 年业界正在收敛的解法——用 AGENTS.md + Rules 统一代码规范，用 SDD 统一开发流程。

文章不仅讲理念，更给出可以直接复制使用的模板、选型对比和分阶段落地路线。所有抽象术语都配了生活化类比，确保你能看懂、能上手。

一、问题本质：两个层面

AI 辅助开发的痛点，对应两个独立但相关的工程层次：

痛点	本质	解决层
代码可读性/可维护性差	AI 生成代码风格漂移、结构混乱、隐含假设	代码规范层
不同人不同工具效果不同	流程不可控，每次会话都在重新发明开发过程	开发流程层

结论：不能靠一个工具全解决，要分层治理。

一句话类比：代码规范层管的是「AI 写出来的代码长什么样」，开发流程层管的是「AI 干活时先做什么后做什么」。前者像给 AI 发员工手册，后者像给它画流水线。

二、第一层：`AGENTS.md` + Rules 管代码长什么样

这是最基础、成本最低、必须最先做的一层。

`AGENTS.md` 是什么

一句话：README.md 是给人类看的项目介绍，AGENTS.md 是给 AI 读的项目专属「宪法」。

生活化类比：AGENTS.md 就像你给新来的 AI 实习生发的《员工手册》。里面写清楚：这个项目是干嘛的、代码放在哪、怎么启动、命名规矩是什么、哪些事绝对不能碰。AI 每次开工前先读一遍，就不会乱来。

它是 OpenAI 在 2025 年 8 月推出的跨工具 AI 编程代理配置标准，目前由 Linux 基金会下的 Agentic AI Foundation（AAIF）中立治理，已被超 6 万个开源项目采用。几乎所有主流 AI 编码工具（Codex、Cursor、Copilot、Claude Code 等）都原生支持。

核心设计原则

人机文档分离：README.md 面向人类，AGENTS.md 专供 AI

轻量无依赖：纯 Markdown，零配置语法

最小必要上下文：只给可执行指令，拒绝哲学化描述

分层优先级：支持根目录全局规则 + 子目录专属规则

可执行性优先：所有指令必须具体、可落地

可直接复用的模板

关键原则：规则必须量化

模糊表述是 AGENTS.md 最大的敌人。对比：

模糊表述 ❌	量化表述 ✅
编写高质量代码	函数行数不超过 50 行
代码要简洁	圈复杂度上限为 10
注意代码风格	注释率不低于 20%

类比：告诉 AI「写得好一点」等于没告诉；告诉它「函数不超过 50 行」它才真的知道怎么做。就像教人做饭，说「做得好吃」没用，说「盐放 2 克、炒 3 分钟」才行。

Monorepo 分层写法

大型项目采用「全局 + 局部」嵌套：

子目录规则优先级高于根目录。OpenAI 主仓库实际使用了 88 个 AGENTS.md 文件，分别对应不同业务模块。

类比：根目录的 AGENTS.md 像公司总制度，子目录的像各部门细则。部门细则和总制度冲突时，以部门细则为准。

规则优先级

当前项目已有约定

项目级规则

全局语言规则

模型默认习惯

三、第二层：SDD 框架管开发怎么走

业界共识是 Spec First, Code Later——把约束外化，让所有 AI 和所有人读同一份规范、走同一条流程。

SDD（Spec-Driven Development）一句话类比：像盖楼先画图纸再施工，而不是边盖边改。传统 AI 编程是「你说需求，它直接写代码」，SDD 是「先写一份规格说明（Spec），大家确认了再写代码」。

三个主流选择，核心差异在于工程哲学。

OpenSpec：最轻量

只管需求 → spec → 变更 → 归档这一条 Spec 生命周期。没有状态机、没有强制流程，适合「我只想有个地方管 Spec」的团队。

类比：OpenSpec 就像一个「需求变更登记簿」。你只负责把需求写下来、记录每次改了什么，但它不管你接下来怎么干活。轻到几乎感觉不到存在。

Trellis：注入派

核心直觉：Agent 变靠谱，前提是它看得见你的规范。

规范写在 .trellis/spec/，每次会话自动注入相关 Spec

四阶段循环：Plan → Implement → Verify → Finish

trellis-update-spec 会把新发现的规则反哺回 Spec，规范是活的

记忆机制叫 journal，像工作日志，由 Agent 自行总结

环境要求：Python 3.9+ + Node.js 18+

类比：Trellis 像给 AI 配了一个「随叫随到的贴身顾问」。每次 AI 一开工，顾问就把相关的规范、上次做到哪了自动塞到它眼前。AI 不用自己去翻文件，该知道的都摆在桌面上了。但它只是「让你看到」，你若不照做，它也没法硬拦你。

适合：1-3 人小团队、个人开发者、痛点是「Agent 不知道规范」而非「Agent 不遵守流程」。

局限：流程可靠性依赖 Agent 对文本的理解，没有硬拦截；journal 总结质量不稳定；目前没有 Eval 量化体系。

Comet：状态机派

核心直觉：Agent 会 drift，所以流程本身必须对 Agent 不可绕过。

五阶段：Open → Design → Build → Verify → Archive

用 .comet.yaml + state-events.jsonl 记录确定性状态，而非自然语言

comet-guard.mjs 强制校验阶段前置条件，不满足就 HARD STOP

Guard 脚本用 TypeScript 写，把流程控制从 Prompt 文本中抽离出来

阶段交接时用 SHA256 hash + 上下文压缩，降低 25%-30% 输入 token

环境要求：Node.js 20+（无 Python 依赖）

类比：Comet 像工厂流水线上的「安检闸机」。你必须先设计（Design）、再施工（Build）、再验收（Verify）、最后归档（Archive）。想跳过验收直接归档？闸机不让你过，硬性拦截。它不赌 AI 自觉，而是让流程本身无法被绕过。

适合：3-10 人团队、多人多 Agent 协作、长程任务、需要审计的流程。

局限：学习曲线陡峭，状态机/YAML/Guard 认知成本高；阶段守护最有效的平台有限；目前仍是 0.4.0-beta，有 schema 迁移风险。

选型对比

维度	OpenSpec	Trellis	Comet
定位	Spec 生命周期管理	规范注入 + 任务编排	状态机 + 流程强制
学习成本	最低	低	中高
Agent 自由度	高	高	中（被约束在轨道上）
偏离风险	高	较高	低（Guard 硬拦截）
断点恢复	无	journal 重建	YAML + JSONL 精确恢复
审计能力	弱	中	强
适用团队	1-2 人	1-3 人	3-10 人

一句话：Trellis 解决「Agent 不知道该知道什么」，Comet 解决「Agent 做事没有轨道」。

再打个比方：Trellis 是「把地图铺在司机面前」，Comet 是「在路上装护栏和红绿灯」。前者帮司机认路，后者强制司机按路线走。

不要两个都装

Trellis 和 Comet 的 Spec 目录结构、任务文件格式、阶段定义都不一样，同时启用意味着 Agent 面对两套指令体系。先独立试用一个，吃透设计理念，再决定要不要补另一个的长处。

四、分阶段落地路线

阶段 0：先写 `AGENTS.md` + Rules（第 1 周）

零依赖、所有工具天然支持，这是必须最先做的一步。

用上面的模板填充：技术栈、目录结构、标准命令、代码规范、权限边界

把模糊表述全部换成量化指标

让团队每个成员用 AI 跑同一个任务，对比输出差异，把不一致的地方补进规则

把 AGENTS.md 纳入代码评审——改规则和改代码一样走 PR

阶段 1：选一个 SDD 框架试点（第 2-4 周）

小团队先试 Trellis：装完就能跑，学习成本低

多人长流程再上 Comet：需要审计、需要断点恢复时

选一个不太关键的中型需求试点，不要一上来就在核心链路用

阶段 2：沉淀与推广（第 2 个月起）

每次 AI 出错、踩坑后，把约束规则补进 AGENTS.md

定期复盘：这个 Spec 版本对 Agent 产出有没有量化影响

团队扩大后，把流程经验沉淀为可复用的 Skill

五、常见反模式

规则写哲学不写指令：「代码应该整洁」没有用，要写「函数不超过 50 行」

AGENTS.md 写完就再也不改：规则是活的，每次踩坑都要反哺

同时装两个 SDD 框架：两套指令体系会让 Agent 混乱

跳过 AGENTS.md 直接上 SDD：没有代码规范层的约束，SDD 流程再严也只是规范了一堆烂代码

把 AGENTS.md 当成一次性配置：它不是配置，是持续演进的团队知识沉淀

六、参考资料

AGENTS.md 官方规范：https://agents.md/

OpenSpec GitHub：https://github.com/Fission-AI/OpenSpec

Trellis 官方文档：https://docs.trytrellis.app/

Trellis GitHub：https://github.com/mindfold-ai/Trellis

Comet GitHub：https://github.com/rpamis/comet

总结

最正确的方向：先 AGENTS.md + Rules 统一代码长什么样，再用一个 SDD 框架统一开发怎么走。

人定架构边界和规则，AI 在边界内填空。AGENTS.md 解决「AI 知道什么」，SDD 解决「AI 怎么做」，两者缺一不可，但顺序不能反。

记住三个类比就够了：AGENTS.md 是员工手册，Trellis 是随身顾问，Comet 是流水线闸机。最后友情提醒一句：流程每隆重一分，token 账单就厚一沓——别让 AI 还没写几行代码，先烧掉了你的奶茶钱。