sdd-auditoria-harness

Harness SDD 的只读审计

首次响应此 Skill 时，只在开头添加以下一行： sdd-auditoria-harness v1.0.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

快速开始

1. 将 REPO_ROOT 设置为受审计仓库的根目录。
2. 首先执行此 Skill 的 Safety Gate。
3. 阅读 SDD 的事实来源：项目指令文件（CLAUDE.md 和/或 AGENTS.md）、SDD 索引/自述文件以及引擎配置（.claude/settings.json / .claude/settings.local.json、.codex/config.toml）。
4. 可选：仅在 stdout 中生成结构化证据： python scripts/collect_evidence.py "$REPO_ROOT"。
5. 按照 references/AUDIT_PROTOCOL.md 进行分析。
6. 仅创建新的报告 AUDITORIA_SDD_<AAAA-MM-DD>.md，使用 references/REPORT_TEMPLATE.md。
7. 在聊天中以执行摘要、报告路径以及以下句子结束： nenhuma alteração foi feita — a faxina em si é decisão humana.

适用场景 / 不适用场景

适用场景

使用此 Skill 审计仓库的 SDD harness，不论使用哪种引擎。不同工具对应的路径可能不同；请审计实际存在的部分：

组成部分	Claude Code	Codex / Kimi CLI
项目指令	CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md	AGENTS.md（开放标准；从 2.1.277 起，Claude Code 也会在回退时读取该文件）
Skills	.claude/skills/*/SKILL.md	.agents/skills/*/SKILL.md、.codex/skills/*/SKILL.md
命令	.claude/commands/**/*.md	.codex/prompts/**/*.md
Agent/子 Agent	.claude/agents/**/*.md	.agents/agents/**/*.md
配置	.claude/settings.json、.claude/settings.local.json	.codex/config.toml
Harness 脚本	.claude/scripts/**	.agents/scripts/**、.codex/scripts/**

还要审计：

• harness 引用的 hooks、权限和脚本；
• 流程文档、操作手册、记忆笔记和规格目录；
• 官方 SDD 流程与遗留、重复或缺乏使用证据的项目之间的差异。

不适用场景

请勿使用此 Skill 来：

• 删除、编辑、重命名、移动、格式化或重新整理现有文件；
• 自动修复发现的问题；
• 执行 git add、commit、push、pull、fetch、checkout、restore、reset、clean、rm 或 mv；
• 安装依赖项、执行部署或运行有副作用的命令；
• 审计指定仓库根目录以外的内容；
• 仅因某项内容看起来陈旧或很少使用，就断定其“未使用”。

所需数据

必填

• REPO_ROOT：包含待审计 harness 的仓库根目录。
• 对仓库的读取权限，以及在可用时访问 Git 历史记录的权限。

自动推导

• REPORT_DATE：执行时的本地日期，格式为 AAAA-MM-DD。
• REPORT_DIR：SDD 报告目录（如果有明确指定）；否则为仓库根目录。
• REPORT_PATH：REPORT_DIR/AUDITORIA_SDD_<REPORT_DATE>.md。

如果 REPO_ROOT 不明确，只需询问： Qual é a raiz do repositório SDD que devo auditar?

分步流程

0. 阻断式安全检查

执行任何命令前：

1. 确认操作仅为读取。
2. 拒绝任何可能写入、删除、移动、重命名、安装、同步或更改 Git／项目状态的命令。
3. 优先使用检查类命令，例如 git log、git status、git diff、git ls-files、git grep、rg、grep、不带破坏性操作的 find、cat、不带 -i 的 sed、awk、head、tail、wc，以及原生工具的读取功能。
4. 审计期间不要使用 find -delete、带有变更命令的 find -exec、sed -i、重定向符 >／>>、tee、touch、mkdir、cp、rsync，也不要运行会写入文件的脚本。
5. 唯一允许的写入操作，是在计算出的路径下新建最终报告。
6. 如果 REPORT_PATH 已存在，不要覆盖。停止写入，在聊天中提供摘要，并明确要求提供新的授权名称。

1. 确定主要 SDD

按以下顺序读取：

1. 根目录中的项目说明文件——CLAUDE.md 或 AGENTS.md，读取存在的文件（两者可能同时存在）；
2. harness 相关子目录中的同类文件；
3. SDD 目录的索引／readme，例如 sdd/_index.md、.claude/sdd/_index.md 或同类文件；
4. 引擎配置：.claude/settings.json 和 .claude/settings.local.json，和／或 .codex/config.toml，包括 hooks 和权限设置。

⚠️ 如果仓库有 AGENTS.md，但没有 CLAUDE.md，这不构成缺失：自 Claude Code 2.1.277 起，会通过回退机制读取 AGENTS.md；Codex／Cursor／Gemini CLI 也早已原生支持。不要将缺少 CLAUDE.md 列为发现项。

⚠️ 如果两者都存在，请记录实际的优先级：默认情况下，Claude Code 只读取 CLAUDE.md 文件，忽略 AGENTS.md，除非 CLAUDE.md 通过 @AGENTS.md 导入它，或 Project instructions 设置为 claude-md-and-agents-md。学员认为生效、实际却未被读取的指令属于冲突，也是这项审计中最有价值的发现之一。

生成一份 5–10 行的摘要，包含：

• 官方阶段；
• 调用各阶段的命令；
• 产出物的路径；
• 已声明的优先级规则／事实来源。

以这份摘要为标准，将问题归类为含糊不清和冲突。

2. 全面盘点 harness

每行列出一项：

• 命令／斜杠命令；
• Agent；
• skill；
• hook 和权限；
• 辅助脚本；
• 流程文档和规格目录；
• harness 引用了引擎目录（.claude/、.agents/、.codex/）之外的脚本。

每项记录： 路径 | 类型 | 声明用途 | 表观语言／来源。

没有具体证据时，不要标记为“复制自模板”。无法证实来源时，填写“无法确定”。

3. 衡量使用情况与活跃度

对每项收集：

1. 交叉引用：harness 其他部分中的引用。
2. 近期情况：git log -1 --format=%cs -- <文件>。
3. 执行迹象：如有，记录 SDD 报告／日志中的提及。
4. 重复：与其他项在用途／输出方面存在的客观重叠。
5. 漂移：引用不存在的文件、阶段、模型、命令或路径。

辅助脚本 scripts/collect_evidence.py 可以加快第 1–3 项的收集，并指出第 5 项的候选内容。它只读取文件，并将 JSON 写入 stdout。

没有入站引用且没有执行迹象，只是考虑归类为未使用的最低条件。如果某项按设计可能很少使用，应归类为待确认，而非确定结论。

4. 对发现进行分类

仅使用以下标签，且必须完全一致：

• EXCESSO
• OBSOLETO
• SUPÉRFLUO
• NÃO UTILIZADO
• AMBÍGUO
• CONFLITANTE

一项发现可以有多个标签。

每项发现都必须包含：

• 文件；
• 行号（当证据来自文本内容时）；
• 具体证据；
• 建议。

没有可验证证据的发现不得列入发现表；应放入“向仓库负责人提出的问题”。

详细标准和注意事项见 references/AUDIT_PROTOCOL.md。

5. 提出建议，不执行

为每项发现选择且仅选择一项建议操作：

• MANTER
• APOSENTAR — 附带 tombstone/指针；绝不建议直接删除；
• FUNDIR com <item>
• ESCLARECER
• ARQUIVAR
• REDUZIR

建议应描述仓库负责人之后可以采取的措施；不要执行更改。

6. 创建最终报告

使用 references/REPORT_TEMPLATE.md。

位置：

1. 如果存在 SDD 报告文件夹，且它明确是存放报告的位置，则放在那里；
2. 否则放在仓库根目录。

名称： AUDITORIA_SDD_<AAAA-MM-DD>.md

只有在完成全部分析后，且该文件尚不存在时，才创建该文件。

7. 最终验证

完成前：

1. 确认没有修改任何现有文件；
2. 确认只创建了新的最终报告；
3. 确认每项发现都包含证据；
4. 确认标签和操作仅使用允许的值；
5. 确认未经证实的问题未列入发现表；
6. 在聊天中展示执行摘要和报告路径；
7. 重申：未进行任何更改——是否进行清理由人决定。

验证与质量检查清单

• 在列出发现之前，已总结主要 SDD。
• 所有 harness 项目均已纳入清单。
• 每个项目均包含路径、类型、用途和表观语言/来源。
• 已通过客观证据衡量交叉引用。
• 历史记录可用时，已收集 Git 最近一次变更。
• 在指出偏差前，已核实引用的路径。
• 必要时，将设计上不常见的项目作为疑问处理。
• 每项发现仅使用允许的标签。
• 每项发现均引用具体证据，并在适用时注明行号。
• 每项建议仅使用允许的操作。
• 报告包含六个必需部分。
• 执行摘要不超过 10 行。
• 未修改任何现有文件。
• 最终报告未覆盖预先存在的文件。
• 最终消息明确说明，是否进行清理取决于人工决定。

异常处理

• 无法使用 Git → 将时效性标记为 无法验证；不要编造日期。
• 没有报告/日志目录 → 不要仅凭缺少信号就认定已弃用。
• 没有引用，但看起来是季节性或仅用于发布的条目 → 移至“待确认”。
• 两份文档看起来重复，但没有足够证据确定优先级 → 只有在它们客观上争夺同一角色时才标记为 有歧义；否则移至“待确认”。
• 引用的路径包含变量/通配符 → 仅在上下文明确无误时解析；否则移至“待确认”。
• 文件过大或为二进制文件 → 列入清单，但注明阅读限制。
• 包含数千个流程产物的代码仓库 → collect_evidence.py 的交叉引用检查复杂度为平方级：每个条目都会在其他所有条目的正文中搜索。 实测：27 个条目约需 0.5 秒；在 sdd/ 或 reports/ 等目录中超过约 5,000 个文件时，将无法在合理时间内完成。在这种情况下，不要等待脚本：每次仅指定一个子目录运行（例如只检查 .claude/commands 和 .claude/agents），或使用 git ls-files 盘点，并用 git grep -c 统计引用。该脚本只是可选的加速工具——审计不依赖它。
• REPORT_PATH 已存在 → 不要覆盖，也不要悄悄改用其他名称。
• 所需命令会产生副作用 → 不要执行；在“待确认”中注明限制。

示例

有效发现示例

条目	标签	证据	建议
.claude/commands/old-release.md	已过时、冲突	第 18 行将规格写入 docs/specs/，而主 SDD 指定 .claude/sdd/specs/；旧路径不存在；最后一次提交：2025-11-03。	退役

应列为待确认的示例

某个 Agent 没有任何入站引用，日志中近期也没有提及，但其描述称它仅用于年度发布。不要确定地将其归类为 未使用；请将其记录在“留给代码仓库负责人确认的问题”中。

---

摘自 SDD Open by RDD — https://github.com/robertodiasduarte/sdd-open