Known 的代码有相当一部分由 AI 智能体在写。这套规范来自被踩过的坑,不是流程洁癖:绝大多数事故不是「代码写不对」,而是改完就走——功能能用但文档里查不到、用例全绿但断言只验了「不抛异常」、这一屏修好了换个入口又坏、索引与副本这类镜像没人同步于是静默失效。
规范的完整版随仓库发布,路径 Document/AI开发规范.md;本页是它的对外摘要。
一、先判定改动类型
开工第一件事不是写代码,是给自己归类——类型决定要走哪几道工序。
| 类型 | 识别特征 | 新增用例下限 | 文档必改 |
|---|---|---|---|
| 新功能 | 新页面 / 服务 / 组件 / 协议 / 新的对外契约 | ≥ 6 | 评估看板、官网、SKILL、页面帮助、memory |
| 功能增强 | 既有能力加参数、加分支 | ≥ 2(含 1 例证明旧行为没变) | 评估看板、SKILL |
| 缺陷修复 | 有明确错误现象 | ≥ 1,且要能先在旧代码上跑红 | 评估看板、memory |
| 纯重构 | 行为不变 | 0(既有用例数不得减少) | memory |
| 文档 / 配置 / 构建 | 只动 md、csproj、脚本 | 0(但要跑守卫用例) | 自身即文档 |
拿不准按更重的算。「顺手改的一点小东西」不构成跳步理由。
二、六道工序
0 · 读。 读对应模块的 SKILL 章节(那里每一条都是踩坑结论)、读评估看板确认这条链的现状、grep 三处确认没有第二份实现。
1 · 设计。 产出三句话:用户看到什么、数据从哪来到哪去、失败时显式表现什么。再列破坏面(谁在用、旧数据怎么办、契约放哪)。设计阶段必须回答:新增的开关消费点在哪?仓库里是否已有同类实现?这条链有几条渲染/取数路径(设计器、填写态、只读、打印各算一条)?
2 · 实现。 一条改动一个目的;不许留假件(长得像但契约不同的占位实现,比缺功能更糟);失败必须显式,不许吞异常或降级到更弱的算法;多租户桶、权限、审计三处别漏;生成物只跑工具生成,不手改。
3 · 测试。 缺陷先能红;断言钉可观察结果,Assert.DoesNotContain("Exception") 不算断言;四类必测——主链路、边界(空/超长/非法)、权限与租户、退化输入(脏名字、空配置、已删除的基线);替身只替外部边界,数据库与渲染尽量用真件;用例名写成中文句子。
4 · 文档。 四类各有触发条件:评估看板(任何功能改动都要改它的总表、统计行、验证段与进度记录)、官网 md(用户可见的变化)、页面帮助(新增 [Menu] 页面,登录注册页除外)、README(对外能力变了)。官网 md 改完必须重跑索引,否则页面不上网。
5 · 技能。 SKILL.md 是写给下一个 AI 的:只写「不写这条他就会踩坑」的内容(新契约、反直觉行为、静默失效的陷阱),不写「本次改了哪几个文件」。写完版本号末位 +1,并同步发布副本。
6 · 收尾。 build 0 警告 0 错误 + 全量测试全绿 + 文档齐 + memory 留痕;端到端照「缝」验一遍真实操作,而不是只看单测绿。
三、必跑命令
dotnet build Known.slnx # 0 警告 0 错误才算过
dotnet test Known.Tests/Known.Tests.csproj # 全量,汇报里写清通过数
dotnet run --project Website/Tools/DocGen -- Website/docs/md Website/docs/index/pages.json
cp Document/skills/*.md Website/docs/skills/known-framework/
四、几条红线
- 文档不同步 = 没交付:评估看板漏记等于白干,SKILL 漏记等于让下一个 AI 重踩。
- 不许「配了不生效」:新增参数 / 配置项 / 能力位必须有消费点与用例。
- 不许用假件冒充能力:占位实现的尺寸、样式、交互、失败语义与真件不一致,就是缺陷。
- 断言必须钉症状,不许为变绿删测试或跳过测试。
- 契约改动两侧同改:数据工具的双份实现、SKILL 的两份副本、协议能力位与 provider。
- 示例与出码里的 API 必须真实存在:曾有一整套出码引用了产品里一个都没有的类型,导致「参考实现」从来编不过——现在由编译探针守着。
五、为什么较真
真实反例(都发生过):出码「参考实现」编不过;设计器用自制 24px 输入框冒充框架 39.2px 控件,导致运行时字段标签被压没;官网文档改了但索引没重生成,站上永远看不见;技能发布副本落后二十多个版本。
这些都不是「写错了代码」,而是少走了一道工序。规范存在的唯一目的,是让换一个人(或换一天的 AI)拿这份仓库时,能只靠文档复现同样的结论。
扫码关注公众号
扫码加入 QQ 群