用 CI 检查编码智能体有没有漏掉需求
作者用 .NET 10 编写 CI 门禁,交叉检查需求、计划、任务和团队规范,介绍六类仅统计完成勾选无法发现的缺口。以密码重置为例,即使发送邮件、表单和令牌存储任务全部完成,30 分钟过期要求也可能遗漏。
AI 深度解读
AI 编程代理把 tasks.md 里的 23 项任务全部勾完,CI 也亮了绿灯。同一批文件交给作者用 .NET 10 写的规格检查器,却报出 11 个问题,其中 5 个是严重级别。作者用自建样例做了这次对照,检查器抓到了他预先埋入的全部 10 个缺陷。
两种检查回答的是不同的问题。数勾只能确认任务清单走完了。从规格反查,才能发现有些需求从未进入清单。对已经让 AI 拆任务、写代码的团队,这个区别直接影响 CI 能发现哪些漏项。
从需求反查,才能找到没进入清单的工作
拿密码重置举例。FR-003 要求重置链接在 30 分钟后失效。代理拆出了发邮件、重置表单和令牌表三项任务,三项都能做完,链接过期却压根没人负责。只遍历任务清单,永远遇不到缺失的那一项。
作者的做法是从 spec.md 出发,为每条需要实现的需求找至少一项明确引用它的任务。下面的代码展示了检查方向。
IEnumerable<Finding> CheckCoverage(SpecDocument spec, IReadOnlyList<TaskItem> tasks)
{
foreach (var req in spec.Requirements.Where(r => r.NeedsBuildableWork))
{
if (tasks.Any(t => t.Cites(req.Id))) continue;
// functional requirement with no task => CRITICAL finding
// ... severity rules, location and suggested fix in the complete project
}
}
关键是 t.Cites(req.Id) 这一行。作者要求在任务末尾显式标注 (FR-003),关键词匹配只用来提示候选任务。反过来也要查,一条任务引用 (FR-014),而规格只写到 FR-010,这个引用就无法解析。解析完文档,还能检查两项标了 [P]、声称可以并行的任务是否会编辑同一个文件。
有了任务,还要确认需求能验收
GitHub Spec Kit 允许用 [NEEDS CLARIFICATION: ...] 记录待确认事项。起草时留着很正常,但提交到 CI 时如果标记还在,团队就很难判断代理是按哪个口径实现的。作者把未关闭的标记记为 HIGH。
另一类问题更隐蔽。「必须快速发送重置邮件」看起来像条需求,却很难写出一条能判定失败的测试。作者用下面这段规则筛查含糊措辞。
if (ContainsNumber(req.Text)) yield break; // measurable, fine
var hits = VagueWords.Where(words.Contains); // whole-word match only
// HIGH for words like "fast"/"secure", MEDIUM for "simple"/"easy"
// ... word lists and severity mapping in the complete project
第一行决定了规则的边界。需求里只要出现数字,就会跳过后面的整词匹配。补上 (p95 < 2 s) 可以过关,验收时还得说清楚从哪一刻开始计时、到哪一刻结束。规则会把 fast、secure 等词记为 HIGH,把 simple、easy 记为 MEDIUM,适合把可疑条目挑出来交给人看。
团队规则写进代码,模型只做补充
门禁读取 spec.md、plan.md、tasks.md 和团队章程。章程里的大写 MUST / MUST NOT 只有符合已实现的规则形态,才会被自动检查。例如,对每个用户故事比较首个测试任务和首个实现任务的顺序,检查任务有没有引用需求 ID,或者检查 plan.md 里是否用了禁用库。暂时无法自动验证的条款会列出来,让评审者知道还有哪些需要人工核对。
发现项也需要能跨提交追踪。StableId 用 FindingCategory 和问题自身的键生成 ID,例如 requirement|FR-003、vague|FR-005 或 parallel|T014|T015。结果由短前缀和 6 位十六进制字符组成,例如 COV-xxxxxx。这样在文件顶部加一段文字,已有豁免和 PR 评论依然找得到原来的问题。
CI 先用确定性规则决定通过或失败,再通过 Microsoft.Extensions.AI 让模型看一遍静态规则没标记的需求,追问「按什么标准判定正确」。模型输出存成建议,服务不可用时也不影响构建结果。
我的判断
我赞成把需求覆盖和引用完整性接进 CI。人工评审更适合看需求和实现是否对得上,而逐条核对 FR-003 有没有下游任务,交给程序更省力。显式 ID 比关键词匹配多一点维护成本,前提是团队本来就在维护规格和任务清单。若需求只散落在工单和 PR 描述里,得先确定哪个地方是需求的准本。
这套门禁能验证到什么程度,要看每条规则实际读了什么。首个测试任务排在实现前,只能证明文档里的次序。需求里出现 30,也可能只是别的数字,和「快速」的验收标准毫无关系。覆盖检查同样只确认引用存在,链接是否在 30 分钟后失效,仍要靠行为测试验证。
作者报告,样例分析耗时不到 1.5 毫秒,100 次运行都返回相同的 ID。完整项目采用 Clean Architecture,提供 ASP.NET Core API 和 CLI,作者称有 177 项离线测试通过。这些是样例结果和作者报告的测试规模。原文没有真实项目上的误报率、人工评审对照或维护成本数据,至于哪些规则适合直接卡合并,还是经验之谈。
能拿来做什么
- 如果团队已用 Markdown 维护需求和任务,可以先写个 Node 脚本接进 PR 检查。对每个需要实现的需求查任务引用,再对每个任务引用查需求是否存在。
- 让 AI 拆完任务后保留明确的需求 ID。对密码重置这类功能,把
FR-003同时写到对应的测试任务上,评审时就能顺着 ID 找到过期行为的验证。 - 先把未关闭的澄清标记列入 CI 检查。对「快速」「安全」这类词,可以先给警告,再由团队补齐时间阈值、计量口径或具体的安全约束。
- 如果还想用模型帮忙审规格,可以把建议放进 CI 报告,并用一次模型调用失败的运行确认构建判定保持一致。