用途
forge-survey 用于审查代码库的整体设计,而不是某一次改动。它关注的是单次 diff 看不到的问题:同一规则在多处重复、模块依赖方向混乱、一个变更真实代价是多少,以及每条发现本应被哪条规则或检查拦下却没有。
主要能力
- 按给定的设计问题类别调查:重复决策、依赖方向、过宽接口、为测试而生的代码、纯转发层、被取代的机制、过时文本、死重。
- 接受可选范围参数(路径或区域);默认为整个仓库,可用
-- <additional context>给出关注指引。 - 在全新上下文中审查,并可把范围切分为三到六个可整体阅读的区域,分别交予子代理;另有子代理跨区域分析模块导入关系与共同变更文件(git log --name-only)。运行时若无子代理,则顺序执行相同的遍次。
- 每条候选发现都要求给出证据(file:line)、当前典型改动的代价、最简修复方案;同时列出应保持不动的深层模块,以及按代码阅读推测、未复现的疑似缺陷(单独列出)。
- 明确规定不报告风格、命名偏好、项目 linter 已报告的内容,也不提出重写。
- 核验阶段由人工打开每条候选的引用行确认,剔除无法确认和已被未关闭 Issue 覆盖的项,标注与既往调查重复出现的项,并按放弃代价与区域变更频率排序。
- 为每类发现指出“放行者”:应当捕获它的规则、评审步骤或检查,并判断其属于缺失、未强制执行,还是规则本身会导出该发现。
- 若本次与既往调查都发现同一类别,则给出护栏(guardrail):一个防止该类问题再次出现的检查或规则变更,而不是为每个实例再开一个 Issue。
使用方式
作为技能调用,可带范围参数与关注指引:
/forge-survey
/forge-survey src/billing src/quota -- look hardest at how the tests are shaped
流程为:
- 读取已知信息:AGENTS.md 及其质量门禁、CONTEXT.md 与决策记录(若有)、docs/surveys/ 下历次调查,并按 issue-operations 搜索未关闭 Issue,避免重复发现已知问题;保留状态为 open 的既往发现。
- 分区域调查(委派):按应用或顶层模块把范围切分为三到六个区域,交予全新上下文的子代理;另有一个子代理跨区域分析导入关系与共同变更文件。
- 核验与排序:亲自打开引用行确认候选,剔除无法确认或已被开放 Issue 覆盖者;按放弃代价与变更频率排序;标注放行原因。
- 记录调查:写入 docs/surveys/<YYYY-MM-DD>.md;从已获取的默认分支切出 docs/survey-<YYYY-MM-DD> 临时 worktree 分支提交、推送并开 PR,使记录不留在单一检出中,当前检出保持自身分支。
- 与用户逐条裁定:通过 AskUserQuestion 展示发现与护栏,选择归档、拒绝或保持开放;为每条归档项按 issue-operations 创建 Issue 并在正文写入其 ID,将决定写入 Status 列并推送。
输出格式
记录文件按以下结构书写:
- 标题为
# Survey <YYYY-MM-DD> - 元信息:
**Scope:** <paths> at <short SHA>与**Earlier surveys:** <dates, or none> ## Findings表格,列为 ID、Class、Finding、Evidence、Let through by、Remedy、Status;Status 取值为 open、filed #<n>、declined: <why> 或 recurs from <ID>## Guardrails:按类别列出检查或规则变更及其覆盖的跨调查 ID## Possible bugs:<file>:<line>及说明,注明为代码阅读所得、未复现## Leave alone:<module>及其所隐藏的内容
适用场景
需要在不依赖具体改动的情况下,对代码库设计做一次系统体检,并把结论沉淀为仓库内的持久记录和 PR,同时为反复出现的问题建立预防性护栏时使用。
限制
- 调查结果必须有证据;无位置的发现不予记录。
- 调查短小、未发现问题是可接受的结果,不人为制造发现。
- 不报告风格与命名偏好,不报告 linter 已报告的问题,不提出重写。
- 疑似缺陷仅按代码阅读标注,不作复现。
相关技能
对需要先选定方案的发现,使用 forge-create-issue;要把护栏写入项目指引,使用 forge-setup-project。