文档与代码一致性审计

解决什么问题

项目文档最常见的失效方式不是整篇过时，而是局部章节仍被当作事实来源。设计稿里写了 region 筛选，代码里字段存在却永远读取默认值；契约宣称 fail-closed 校验，实现里根本没有对应判断；迁移脚本新增了表，文档仍沿用旧字段名。这些不一致不会让构建失败，却会在评审、排障、发版和跨团队协作时制造昂贵的误解。

它如何工作

这个技能不修改文档或代码，只做证据化审计：

• 提取可验证声明：从目标文档中筛出具体的 API 端点、数据表、字段、配置项、环境变量、行为规则和断言性表述。
• 逐项进入代码取证：根据声明类型到路由、模型、迁移、配置、服务层或种子数据中查找，并用 grep / 直接阅读确认真实逻辑。
• 区分实现状态：结果分为已实现且生效、占位、未实现。占位最危险：类型存在，但值是写死常量，从不读取数据源或参与决策。
• 归入四类不一致：声明与实现矛盾、清单结构不符、占位伪装成生效、统计数字过时。
• 按严重度输出报告：高严重度优先，单独列出伪生效字段，并简列确认一致的部分，便于判断哪些文档可信。

适用边界

它依赖代码和文档都能被访问；对纯愿景、非技术性描述无法验证。若文档已诚实标注 TBD、目标态或未实现，技能不会把它当成 bug。审计范围较大时，应先聚焦模块和断言性声明，必要时并行分派子 agent。