GSDD 落地手册:五个命令,管住 AI 开发的全周期
从 /gsdd-init 到 /gsdd-audit,一套开源 skill 在真实项目里怎么转起来
发布于
aardpro aardpro
AI 让写代码越来越便宜,但没让软件开发变简单。GSDD 是我对这个问题的实践回答:装一个开源仓库,五个命令,从一个空目录跑到第一轮验收闭环。

AI 让编写代码变得越来越便宜。

一个开发者可以让 Agent 在几分钟内完成过去需要数小时的工作,也可以同时让多个 Agent 并行开发不同功能。

但代码生产速度的提升,并没有让软件开发变得同等简单。

需求可能被误解,架构可能逐渐偏移,多个功能之间可能产生冲突。Agent 完成了任务,却不一定完成了我们真正想要的事情。

更麻烦的是,代码生产得越快,人越容易失去对整个系统的掌控。

机器人不断吐纸成山,人只拿放大镜细看一张

我们正在面对一个新的问题:如何让 AI 持续、高效地开发软件,同时确保软件始终符合我们真正想要的东西?

GSDD 就是我对这个问题的一种实践回答。它落成了一个开源仓库:github.com/aardpro/skill-gsdd。五个命令,装进你现有的编程工具——ZCode、Claude Code、Cursor 都行。本文按项目生命周期走一遍:第一天干什么、日常怎么转、需求变了怎么办、交付前查什么、平时怎么体检。

一、装:两行命令

npx skills add aardpro/skill-gsdd -g          # 交互式选工具
npx skills add aardpro/skill-gsdd -a claude-code -g   # 或指定工具全局装

装完是五个 skill 目录:gsdd-init、gsdd-load、gsdd-change、gsdd-accept、gsdd-audit,全部手动触发(AI 不会自己乱跑它们),装完重启一次会话生效。五个命令对应五个时刻:开工、派活、变更、交付、体检。本文对应仓库 v0.2.1,命令行为随版本演进,以仓库 README 为准。

没装的时候,你的项目里 agent 与规范的关系是“口头约定”:你在 prompt 里千叮万嘱,下次会话它全忘了。装完之后,规范住进项目里的 ssot/ 目录,入口文件(CLAUDE.md、AGENTS.md)只干一件事:指路。agent 每次进门先看到“这里的规矩在哪儿”,而不是靠你今天的心情。

二、第一天:/gsdd-init

在一个项目根目录敲 /gsdd-init,它做三件事(已有 ssot/ 的老项目不会重建骨架,只补入口接线)。

第一件,建骨架。ssot/ 目录,三层分区、默认十文件:需求层放产品定位、需求清单、变更流水账;事实层放词法表、架构总览、数据库模式、技术栈、技术决策记录;流程层放验收标准与业务剧本。每个文件开头一段索引,装的是什么、去哪找,一眼见底。

第二件,接线。扫描项目里已有的工具入口文件,把一段 GSDD 指路追加进去;一个都没有就建 CLAUDE.md。指路文件只指路,不复制内容——agent 进门看到的是“规矩住在 ssot/,先读 README”,而不是一份抄来的副本。顺手还补一份 tests/README.md,约定自动化测试怎么标注所验收的编号——这是后面编号对账的锚点。

第三件,问答式收窄。这是第一天最重要的部分:AI 逐层提问,每轮先给草稿,你确认了才落盘。它问你的用户是谁、不做什么、每条需求的口径、每个术语的定义、用什么数据库为什么。你说“导出功能不允许读联系人以外的数据”,它写成验收项;你说“存储用 PG,因为团队只会 PG”,它连理由一起记进决策记录。

注意这个动作的方向:AI 只起草,人采纳才写入。第一天结束时你得到的不是一堆文档,是一套空房间——房间结构立好了,每件家具什么时候搬、谁搬,都有规矩。

有个小细节值得说:ssot/README.md 第一行写着“(GSDD 治理)”。目录不叫 gsdd/ 而叫 ssot/,因为 ssot 描述的是内容的本质(唯一事实来源),GSDD 是治理它的方法——目录跟着内容走,身份写在门口。哪天你不用这套方法了,目录里的东西还是有效的项目事实。

三、日常:/gsdd-load 与干活

开工派活的命令是 /gsdd-load。给它一句任务描述,它产出一份不超过两千 token 的任务简报:相关验收项的全文、涉及的术语口径、波及的剧本步骤、本任务的禁止事项。

为什么要简报?上下文是经济学。十文件的规范全文可能几万字,全塞给 agent,一来贵,二来它反而抓不住重点。索引先行、按需取段——文件超过三百行(阈值写在 ssot/README 头部,项目可调)就不许全文读,grep 到编号再取那一段。这是给 AI 的阅读纪律,也是给写规范的人的约束:规范本身要长成“可检索”的样子,不然自己先淹死。

有个容易忽略的设计:改表、换库、迁移类的任务,简报会强制附上 schema 条目、技术栈组件和相关决策记录,缺了就在简报开头标红“数据事实不完整”。AI 拿着一句“把这个字段改了”就动手改库的事故,多数死在这步——它不知道这个字段背后有过一个“为什么不能用 int”的决策。

然后 agent 干活。它对 ssot/ 全层只读——这是整套流程的底座。说清楚这条约束的边界:它是写在治理规则里、由流程保证的纪律(越线有提案通道兜着),不是文件系统级的权限锁;要机器层强制,那是 04 篇讲的系统层隔离的活。AI 能顺手改规范,规范就不再独立于实现,“盯 SSOT”盯到的会是它自己的作业。发现规范有缺口?它只能走提案通道,不停工等答复,先按现行规矩干。

四、需求变了:/gsdd-change

项目唯一的常态是变更。变更的命令是 /gsdd-change,它是一个提案通道:AI 起草,人审,采纳了才落盘。

提案包含两样:一条 change-log 条目(日期、新需求、波及文件),以及每个波及文件的修订 diff。你点头之后,落盘顺序是锁死的:先追加流水账,再改文件。顺序不能反——账在前,文件在后,任何时刻翻账本都能对上文件的历史。

编号纪律在这里生效:需求编号 R、数据事实编号 S、验收项编号 A、决策编号 D,引用链只能自上而下。作废的编号不删除,标注作废、指向新编号——引用链不断,三个月后翻旧账还能对上。

有一类变更单独设卡:单向门。数据库引擎、云平台、鉴权方案、删列改类型这类不可逆或回退成本极高的决策,提案必须写清替代方案、回退成本、批准人,缺一项不得进入采纳环节,且要负责人亲自批。普通修改过第二双眼睛就行,单向门过负责人——门槛随爆炸半径走,不随噪音走。

行业里那句老梗“我们让 AI 重构了整个系统”之所以是恐怖片,就是因为没有这道门:改错了想退,退不回去。

五、交付:/gsdd-accept

agent 说“已完成”之后,跑 /gsdd-accept。它沿剧本逐步走查,能自动跑的跑测试,跑不了的按剧本手工验证并记录。产出是一份验收报告:编号、结果、证据位置,三栏。日志、截图、测试输出归档到 evidence/,不进 ssot/——证据是事实的影子,影子不冒充本体。

这里回应开头那个问题。“已完成”的三种语义里,GSDD 只认最后一种:每个验收项编号后面挂着证据,人核的是编号与证据的对照,不是八百行代码。

左边的机器人给自己的文件盖章打勾,右边的机器人拿放大镜独立审阅

有个细节容易被误会:测试失败时,仲裁方向是死的。测试断言与验收标准冲突,错的是测试或实现,永远不会是验收标准——标准是人写的、经过门槛的,测试是 AI 写的。要改标准,唯一入口是改 acceptance,走改动门槛。方向反了,整个体系就变成“谁嗓门大听谁的”。

慢测试不硬塞进每次交付:快速冒烟常驻,全量走查定期触发。验收要能天天做,才有人做。

六、平时:/gsdd-audit

跑了一段时间,规范会腐烂。索引和正文对不上、引用了作废编号、某个拆分文件没登记、change-log 被人手滑改过历史——这些都是慢性病,发作时项目已经病了很久。

/gsdd-audit 是体检:只读、只报告、不修改。它查结构(入口齐不齐、有没有孤儿文件)、编号通货(引用链上有没有断号)、索引一致性、只追加约束(账本历史在 git 里必须是只追加的)、单向门完备性(标记为单向门的决策,替代方案/回退成本/批准人齐不齐)、迁移对账(schema 登记的迁移号和代码库里的迁移能不能对上)、规模预警(哪个文件胖到该拆了)。

建议的节奏:每次大变更后跑一遍,每个迭代收尾跑一遍。体检报告按严重度排序,修也走提案通道——体检医生不开药,只出诊断书。

七、第一周的节奏

天 动作 产出
第 1 天 /gsdd-init 骨架 + 入口接线 + 首轮问答
第 2 天 继续收窄 首批需求 R、术语表、核心 schema 与决策
第 3 天 首批 acceptance 与 testcase 一条最核心流程的验收项与剧本
第 4 天 日常开发(/gsdd-load 派活) 第一轮实现
第 5 天 /gsdd-accept 完整证据链,第一轮闭环

一周只做一条业务流程,够了。闭环跑通比覆盖面重要——流程转起来了,第二条流程就是重复劳动。

八、什么时候别用

诚实段。三类项目不建议装:三天就扔的 demo,规范的成本收不回来;单人玩具项目,第二双眼睛和变更纪律都是纯开销(单人也有降级玩法:改动放一夜,隔天以审稿人身份自审,但收益确实打折);纯脚本和一次性爬虫,没有“事实”可治理。

够用是铁律。GSDD 治理的是“事实有没有唯一出处、改动有没有门槛”,你的项目里如果不存在会腐烂的事实,就不需要防腐。

尾声

代码生产的速度还会涨,掌控力不会自己跟着涨。这个差距用什么填,是这几年软件工程真正的问题。

填法有两种。一种是让机器自己给自己盖章——产出漂亮,直到客户退货那天。另一种是把“什么是对的”立成有出处、有门槛、有编号的事实,让机器在轨道里跑,人验证据不看代码。

小机器人开着小车行驶在高架轨道上,乘客翻开图纸看路线

GSDD 选第二种,五个命令就是这个选择的落地形态。仓库在 github.com/aardpro/skill-gsdd,装不装、什么时候装,取决于你的项目里有没有值得防腐的东西。

有,就别让机器自己盖章。

统计
© 2024-2026 Aard Blog ✉ hello@aard.ltd