メニュー
Phased audit for spec-implementation alignment — spec / architecture / api / behavior / integration / issue-process / rule-coverage
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | audit |
| description | Phased audit for spec-implementation alignment — spec / architecture / api / behavior / integration / issue-process / rule-coverage |
| disable-model-invocation | true |
| installed-from | agent-dev-standard@cf04193 |
| installed-on | "2026-05-29T00:00:00.000Z" |
按 audit phase 协议（参考 protocols/issue-process.md + protocols/rule-coverage.md + rules/extension/audit-phases.md）对项目进行分阶段审查。
$ARGUMENTS：审查阶段，可选值：
prd — PRD 对齐审查（原型 / PRD → 共识文档 → 实现，三层对齐）spec — Spec 审查（共识文档 + 模块清单的完整性和追溯链）architecture — 架构审查api — 接口审查behavior — 行为审查integration — 集成审查issue-process — Issue 处理流程合规审查rule-coverage — 规则覆盖度审查（SA 月度跑）all — 全部 phase 顺序执行--module <name> 指定模块范围--window <N>d 限定 issue-process 审查窗口（默认 30 天）执行前读取项目 CLAUDE.md 中的 ## Audit 输入映射 段。
如果配置不存在，提示用户先运行 /install 配置审查输入映射。
配置格式：
## Audit 输入映射
### prd
- PRD/原型项目: `<path>`
- 共识文档: `<path>`
- 实现基线: build #xxx 或 commit hash
### spec
- 共识文档: `<path>`
- 模块清单: `<path>`
### architecture
- 共识文档: `<path>`
- 架构设计: `<path>`
- ADR: `<path>`
- 第三方约束: <列表>
### api
- 设计文档: `<path>`
- 数据模型: `<path>`
- Controller: `<path>`
- DTO/Entity: `<path>`
### behavior
- Issue 仓库: `<owner/repo>`
- 状态机: `<path>`
- 业务代码: `<path>`
### integration
- ADR: `<path>`
- Client 代码: `<path>`
### issue-process
- Issue 仓库: `<owner/repo>`
- 默认窗口: `30d`
- /release 历史: `<path>`
- 共享文档仓库: `<path>`
- 项目特定规则补充: `<CLAUDE.md 段或 path>`
所有阶段共享同一套执行骨架：
【前置门禁】创建任务清单 → 读取历史 → 确定范围 → 收集输入 → 正向比对 → 反向比对 → 安全语义升级 → Family-scan 合规 → 生成报告+日志 → 写入 Registry → 结束
这是硬性前置，不是可选步骤。任务清单文件不存在，禁止进入 Step 0。
检查 <audit_dir>/task-YYYY-MM-DD-<phase>.md 是否存在
任务清单创建完成后，进入 Step 0。
每完成一个 Step，立即勾选对应项 + 追加任务日志，然后再进入下一步。
为什么是前置门禁而不是建议： 没有任务清单，就没有 Check 步骤，就没有任何机制能拦截"审查过程中修复"的越界行为。清单是流程的骨架，不是事后的记录。
<audit_dir>/findings-registry.md 是否存在
## Audit 输入映射 段
/install--module <name>）：只查指定模块，窄而深 —— 除对齐检查外，自动叠加业务逻辑审查（场景树：正常 → 异常 → 边界 → 压力）从两侧收集，以模块清单追溯链为导航：
模块级范围时，追溯链限定扫描边界 —— 只查关联的 API / 数据模型 / ADR，不全量扫描。
定位: 在 Step 3 / 4 通道合规检查(problem-registry 是否存在 / handoff/pending 是否有内容 / 任务清单文件是否存在等)之前必做。识别项目是否声明"单人多角色豁免"+ 验证豁免有效性。
适用规则: rules/core/problem-handling-pattern.md / rules/core/artifact-based-handoff.md / rules/core/task-lifecycle.md 各自 §单人多角色场景豁免 段。
1. 识别豁免声明:
grep -A 20 "单人多角色豁免\|PM = EL = QA" <project>/CLAUDE.md
2. 若无豁免段 → 跳过本 Step / 按 standard 默认通道 audit。
3. 若有豁免段 → 验证 6 条触发条件:
# 对每个等价载体路径:
ls -la <equivalent-carrier> # 文件 / 目录存在?
wc -l <equivalent-carrier> # 非空?(> N 行)
git log --since="30 days ago" -- <equivalent-carrier> # 近 30 天有改动?
<project>/docs/problems/project-patterns.md 含对应 PP-XXX 条目4. 判定:
5. 反模式(audit 必报):
/Users/.../ 等) = 违反 standard 输出自包含 → 报违规6. 不属豁免范围(即使 6 条全过仍按 standard 默认 audit):
Spec 有的，代码有没有？ 发现遗漏。
逐项检查 Spec 侧列出的每一项在实现侧是否存在、是否一致。
代码有的，Spec 有没有？ 发现多余或未管理的产物。
逐项检查实现侧列出的每一项在 Spec 侧是否有对应。
先正向再反向 —— 遗漏比多余更危险。
比对完成后、生成报告前，执行两件事：
A. 安全基线扫描（每次必做，3 项固定检查）：
| # | 检查项 | 方法 |
|---|---|---|
| S1 | 裸接口扫描 | 所有 Controller 方法是否都有权限注解？无注解 = 未决策，标记为发现 |
| S2 | 凭证泄露扫描 | grep 代码中 key / secret / token / password / credential，是否有硬编码值或 URL 拼接？ |
| S3 | OAuth 完整性 | 认证流程是否有 state / nonce 防 CSRF？token 是否有服务端失效机制？ |
这三条是基线最小集。新增安全类问题时，项目可同步追加检查项到本地 SKILL 副本。
B. 发现的安全语义升级：
对 Step 3/4 的所有发现做安全语义扫描。涉及认证 / 授权 / 加密 / 凭证 / 输入校验的缺失或偏差，必须评估安全后果。安全后果非平凡的，升级为独立发现（严重度至少 Medium），不能淹没在聚合表格中。
触发判据： 任一发现命中 rules/core/fix-pattern-scan.md 触发场景 —— 状态转换 / 状态校验、参数校验 / 边界检查、异常处理 / 资源释放、一组同名方法、第三方 API 参数差异、身份隔离字段。命中即必做；未命中即跳过（task 日志注明"无 family-scan 命中场景"）。
两层扫描（强制，参考 rules/core/fix-pattern-scan.md §扩展段 + §二级 pattern 元规则）：
| 层 | 检查 | 输出格式 |
|---|---|---|
| 一级 | 抽象搜索模式 → grep 直接特征 → 列出"已修 / 未修 / 合理差集"三类 | **Family scan 一级：** grep <pattern> → N 处命中 → <清单> |
| 二级（命中下表 8 类时强制） | 进入入口点实现内部 → 二次 grep 嵌套层 / fallback 层 / backstop 层 | **Family scan 二级：** 进入 <入口> 实现 → grep <inner-pattern> → M 处命中 + 调用链 |
二级触发的 8 类：
异步 submission（lambda / closure 内）/ Backstop / Fallback（catch / orElse / recover）/ 嵌套 try-catch / 嵌套 Stream / Optional / 递归 / 回调 listener / Builder / Fluent / AOP / Interceptor。
报告中必须分一级 / 二级两层呈现 —— 只写一级 = 等价于规则未升级 = 违规。
FB 应用整改的家族扫描： 当审查发现某 FB 触发场景已修时，必须同时验证家族覆盖率，分层呈现"FB-XXX 整改覆盖率：触发 100%，家族漏网：F-XX-NNN"。
报告保存到：<audit_dir>/YYYY-MM-DD-<phase>.md
格式遵循 audit 输出规范，每个发现分类为缺失 / 偏差 / 风险，按严重程度排序。
执行日志保存到：<audit_dir>/YYYY-MM-DD-<phase>-log.md
执行日志边执行边写（不是事后补），必须包含：
报告和日志全部完成后，自动将所有发现批量写入 findings-registry 和 problem-registry，状态统一为 proposed。
Step 6.5 — 事件流追加（按需）：
如项目启用 jsonl 事件流（<workspace>/.events/audit-finding/YYYY-MM.jsonl），每条 finding INSERT 后同步 append 一行 jsonl 用于跨项目分析 / 趋势可视化。schema 见 templates/archive-frontmatter.schema.yaml 同源约定（项目可自定义 SCHEMA.md）。
subagent 模式（audit-agent）： 如果 audit-agent 被平台层拦截写 .jsonl，改为在 proposals 文件中加一段 ## 事件流追加建议 (jsonl)，由父会话代 append。
如有高优先级发现（HIGH / CRITICAL），执行 /notify audit 通知团队（如 notify skill 已装）。无高优先级发现则不通知。
审查到此结束。 后续由全局会话 review 报告 + 日志，再由 /fix 分拣决定每条发现的去向。
七步骨架不变，每个阶段的 Step 2~4 读取和比对的内容不同：
| 步骤 | Spec 侧 | 实现侧 |
|---|---|---|
| 收集 | 原型功能点清单（按页面 / 模块） | 共识文档 + 实现代码 / 接口 |
| 正向 | 每个原型功能点是否在共识文档覆盖？是否实现？ | — |
| 反向 | — | 实现是否都能在原型找到对应？ |
状态标注四类： ✅ 已实现 / 📋 共识文档已定义但延期 / 🔶 FE-only（不需后端接口）/ ❌ Gap（原型有，缺失）
| 步骤 | Spec 侧 | 实现侧 |
|---|---|---|
| 收集 | 共识文档功能章节列表 | 模块清单模块列表 |
| 正向 | 每个功能章节是否有模块承接 | — |
| 反向 | — | 每个模块是否有共识文档对应 |
额外检查：TBD 收敛情况、反哺标记覆盖率、追溯链完整性、状态时效性。
| 步骤 | Spec 侧 | 实现侧 |
|---|---|---|
| 收集 | 共识文档 + 模块清单 + 约束 | 架构设计文档 + ADR |
| 正向 | 每个模块是否在架构中有对应 | — |
| 反向 | — | 架构中的选型是否都有约束支撑 |
额外检查：ADR 决策是否在架构中体现、第三方依赖使用方式是否符合文档约束。
| 步骤 | Spec 侧 | 实现侧 |
|---|---|---|
| 收集 | 接口设计文档 + 数据模型文档 | Controller / DTO / Entity |
| 正向 | 每个设计接口是否有 Controller 实现 | — |
| 反向 | — | 每个 Controller 方法是否在设计文档中有定义 |
额外检查：字段一致性（名称 / 类型 / 必填性）、状态码 / 错误码对齐、数据模型字段一致。
数据建模质量检查（每次 api 审查必做）：
| # | 检查项 | 方法 |
|---|---|---|
| D1 | 隔离维度独立性 | 用于区分角色 / 租户 / 模块的字段，是否独立于业务类型？用业务枚举做身份隔离 = 脆弱 |
| D2 | 同类操作一致性 | 同性质的耗时操作是否使用相同的执行模式（同步 / 异步、重试策略）？ |
| D3 | 枚举演化安全性 | 枚举 / 状态字段将来跨角色或跨模块复用时，现有设计是否兼容？ |
| 步骤 | Spec 侧 | 实现侧 |
|---|---|---|
| 收集 | Issue 验收条件 + 状态机定义 | Service / Domain 代码 |
| 正向 | 每条验收条件是否有代码覆盖 | — |
| 反向 | — | 代码中的业务分支是否都有验收条件对应 |
额外检查：状态机完整性（合法转换 + 非法拦截）、边界条件处理。
| 步骤 | Spec 侧 | 实现侧 |
|---|---|---|
| 收集 | ADR + 第三方 API 文档 | Client 代码 + 配置 |
| 正向 | ADR 决策是否在代码中落地 | — |
| 反向 | — | 代码中的集成方式是否都有 ADR 覆盖 |
额外检查：错误处理覆盖（超时 / 限流 / 认证失败）、配置项硬编码风险、API 版本一致性。
参考 protocols/issue-process.md § 审查维度（5 维度）。
输入获取：
gh issue list --state closed --search "closed:>=$(date -v-30d +%Y-%m-%d)" --json number,title,labels,closedAt --limit 200gh issue list --state open --label [role]-in-progress,[role]-confirmed --json number,title,labels,updatedAt豁免 comment 识别（2026-05-25 加 / Issue #11 FB-006）:
维度 3 #14（文档先行 commit）/ 维度 #16（测试覆盖）等结构化检查必须先扫 Issue comment 语义豁免，命中则标 ✅（豁免）而非 🟡（偏差）/ 不机械化报违规。
# 维度 3 #14 文档先行检查前 — 先扫豁免 comment
gh issue view <N> --comments | grep -E "文档先行豁免|S 级豁免|bootstrap 豁免" && {
# 命中豁免关键词 → 验证豁免 comment 必填字段（豁免理由 / 项目阶段 / 后置承诺）
# 字段齐全 = 标 ✅（豁免合规）/ 不报违规
# 字段缺失 = 标 🟡（豁免依据不完整 / 不是不识别豁免）
}
# 维度 #16 测试覆盖检查前 — 同理扫 "测试豁免" 关键词
豁免关键词清单（与 issue SKILL §pm-reviewed Step 2 §文档先行豁免规则对齐）:
文档先行豁免 / S 级豁免 / bootstrap 豁免(文档先行)测试豁免(测试覆盖)配套规则: issue SKILL Step 2 §文档先行豁免规则定义"豁免 comment 必填字段" / audit 验证字段齐全性而非语义合理性(语义合理性需 review 人工判定)。
反向漏切检测（维度 1 #5c 关键）：
# 1. 拉所有 open [role]-in-progress 的 Issue
# 2. 对每条：从 comment 提取 commit hash（`commit: \`<hash>\`` 格式）
# 3. cross-check：每个 hash 是否是 release-history 中某 build 的 head_commit 的祖先
# git merge-base --is-ancestor <hash> <build-head-commit>
# 4. 退出码 0 = 已部署 → 但 events 无 labeled [role]-confirmed = 5c 反向违规
# 5. 持续时长 = build 部署时间 - issue 收尾 comment 时间
Closed issue 4 字段关联验证（2026-05-25 加 / Issue close-association 范式 v0 §3.5）:
适用于 standard 类项目(无 deploy 概念 / 用 CHANGELOG + release-log [Unreleased] 段累积 + SemVer cut)。closed issue 的 close comment 必含 4 字段(规约见 rules/core/task-lifecycle.md §/issue Step 6b)。
audit 维度 #N — Close comment 4 字段齐全度(语义层 LLM 必需 + 部分机器验证):
# 维度 1: commit hash 列表存在 + 真实
gh issue view <N> --json comments --jq '.comments[] | select(.body | contains("Issue closed")) | .body' \
| grep -oE '(code|docs)@[a-f0-9]{7,40}' \
| while IFS=@ read repo hash; do
git -C <project>/$repo cat-file -e $hash 2>/dev/null || echo "WARN: $repo@$hash 不存在"
done
# 维度 2: CHANGELOG `[Unreleased]` 段含对应 issue entry
sed -n '/^## \[Unreleased\]/,/^## \[/p' code/CHANGELOG.md | grep -E "#$N\b" || echo "WARN: CHANGELOG 未含 #$N entry"
# 维度 3: release-log `[Unreleased]` 段含对应 issue entry(若 close comment 未显式标"不涉及")
sed -n '/^## \[Unreleased\]/,/^## \[/p' docs/docs/release-log.md | grep -E "#$N\b" || \
gh issue view <N> --json comments --jq '.comments[].body' | grep -q "不涉及设计层" || \
echo "WARN: release-log 既未含 entry 也未显式标'不涉及'"
# 维度 4: 关联 artifact 字段存在(ADR / FB / handoff / 关联 issue 或显式"无关联")
gh issue view <N> --json comments --jq '.comments[].body' \
| grep -qE "关联 artifact|无关联|ADR-|FB-|handoff" \
|| echo "WARN: 关联 artifact 字段缺失"
判定: 任一字段缺失 → 标违规(轻度 LOW / 不阻塞 / 但应补)。closed 但 4 字段不全的 issue 在 IPR-NNN 编号 / 加 close-association-incomplete 子类。
反模式(audit 必报):
[Unreleased] 缺对应 entry(E 聚合层断链)git cat-file -e 暴露)finding 编号： IPR-NNN 单 Issue / IPR-T-NNN 趋势
多 dev 并发场景(ADR-008 / 2026-05-25 起): 新 IPR / IPR-T entry 用
IPR-YYYYMMDD-{hash}/IPR-T-YYYYMMDD-{hash}格式(通过code/scripts/generate-id.sh生成)。既有IPR-NNN保留 / 不迁移。同理 F-XXX-NNN / 详见 ADR-008。
参考 protocols/rule-coverage.md § 审查维度（6 维度）。
执行者： SA（不下推 EL）。
节奏： 每月初首工作日。
finding 编号： RC-NNN 单条 / RC-T-NNN 趋势
审查 = 自动化扫描 + 记录，不是工作流。 审查的职责是发现和记录问题，不做任何处理动作。
<audit_dir>/YYYY-MM-DD-<phase>.md。未生成报告文件 = 审查未完成<audit_dir>/YYYY-MM-DD-<phase>-log.md。未生成日志 = 审查不可验证proposed，去向由事后 /fix 决定rules/extension/audit-fix-dispatch.md）—— audit 自身不做 dispatch（保持"只记录不修"约束），但 SA 必须紧跟 dispatch handoff 显式处置每条 finding（5 选 1：resolve via fix / merge / dismiss / escalate / defer）。审查产出 ≠ 工作流结束，finding 不允许在 registry 沉底。all 模式并行 fan-outall 模式需跑多个 phase（prd / spec / architecture / api / behavior / integration / issue-process / rule-coverage）。各 phase 是互相独立的审查维度，天然适配 protocols/fan-out-synthesize.md 的扇出汇总模式——并行压缩墙钟，给每个 phase 干净隔离的上下文。
执行结构（串行 prelude → 并行 fan-out → 单点 join）：
findings-registry.md）+ Step 1（确定范围）。建立所有 phase 共用的历史状态与范围上下文，避免每个子代理重复读。Agent（general-purpose）子代理，独立执行 Step 2~5（收集输入 → 正反向比对 → 安全升级 → family-scan），各自写独立报告 <audit_dir>/YYYY-MM-DD-<phase>.md 与 -log.md（不同文件名，天然不冲突）。子代理返回消息只含报告路径 + 结构化 findings 摘要，不回贴报告正文。findings-registry.md / problem-registry.md（status=proposed），HIGH/CRITICAL 统一走 /notify。严守 registry INSERT-only + 单写者铁律——子代理只产出 findings，绝不直接写 registry（artifact-based-handoff 契约）。安全阀（沿用 fan-out-synthesize 协议）：
all）维持串行，不扇出。详见
protocols/fan-out-synthesize.md§ 单点 join 铁律 + § fan-out 子代理 prompt 契约。
审查报告末尾的"系统性建议"专段是 FB 候选的天然来源。报告生成后，agent 应对每条系统性建议做一次判断：
判断标准（满足以下三条则提示用户）：
判断为 FB 候选时，提示：
"系统性建议「[X]」可能具备跨项目普适性，建议上报为 FB 候选。运行
/submit-fb完成提交（如已装）。"
不做的事：
| 关联 | 关系 |
|---|---|
protocols/issue-process.md | issue-process phase 实施 |
protocols/rule-coverage.md | rule-coverage phase 实施 |
protocols/fan-out-synthesize.md | all 模式多 phase 并行扇出 + 单点 join |
rules/core/fix-pattern-scan.md | Step 4.6 family-scan 触发判据 + 二级 pattern 8 类 |
rules/extension/audit-phases.md（按需） | 各 phase 详细 step 完整版 |
rules/extension/audit-fix-dispatch.md（按需） | 24h SLA + dispatch handoff 5 选 1 决策 |
rules/core/artifact-based-handoff.md | audit 报告 / 日志 immutable + registry living artifact |
流程编排引擎。推进 task.json.flow 步骤（init/check/complete/reset）并维护任务级事件流 task.json.events（emit/check/recent）。触发关键词：flow advance、推进流程、当前步骤、初始化流程、emit event、查事件、task.json.events、flow-engine。
TAPD 统一入口 skill。工单拉取、共识管理、子任务回填、事件驱动同步。触发关键词：tapd、初始化、ticket sync、共识、Wiki 评审、子任务、工时回填、QA 通过、QA 打回、TAPD 事件、契约推送、同步工单、拉工单。
产出结构化 handoff 工件，让新 session 无痕接续当前任务。ctx-guard 阻断或主动切换 session 时使用。触发关键词：context reset、上下文重置、新开 session、切换 session、handoff。
运行架构适应度函数检查代码结构、契约、依赖方向。在代码修改前后使用，确保不引入架构违规。触发关键词：fitness、架构检查、适应度、lint、代码质量检查。
工作流熵管理。清理 stale TAPD cache、孤立 _index 条目、过期 task report。每日定时或手动触发。触发关键词：gc、垃圾回收、清理、cleanup、定时清理。
Git 操作统一入口。分支生命周期（create/merge/cleanup）、worktree（create/remove）、提交推送（commit-push）。按 docs/git-brance-spec.md + Conventional Commits 中文规范执行。触发关键词：创建分支、合并到 dev、合并到 uat、删除分支、清理分支、git push、commit、推送代码、worktree、提交代码。