Super Audit（SA）

给编码 Agent 的本地工程方法包：先理解，再决策，后执行，用直接证据验证交付。

Super Audit（SA）为 Codex、Claude Code、Cursor 和 OpenCode 提供一组可组合的工程 Skill，覆盖需求澄清、项目理解、方案设计、代码执行、故障调试、变更审查和完成验证。SA 不引入新的编辑器或运行时服务，只定义一套让 Agent 在真实项目中按清晰工程边界工作的方法：先说明准备改变什么，再执行；用直接证据，而不是感觉，确认完成。

快速开始

npm i super-audit

安装时自动探测宿主（Codex / Claude Code / Cursor / OpenCode）并写入对应 Skill 目录，不需要额外执行 setup 命令；未检测到支持的宿主时安装失败，详见安装。

安装后直接描述工程任务：

SA 先分析这个权限模块为什么越来越难维护。        # 单阶段：只分析
SA 审查这次修改，只报告有真实影响的问题。        # 单阶段：只审查
SA 修复这个空指针错误，并完成匹配的回归验证。    # 闭环：修复 + 回归
SA flow：重构这个模块，解决职责混乱并完成验证。  # 显式闭环：动态 Workflow

它解决什么问题

编码 Agent 可以很快把一句自然语言变成代码动作，但“代码能运行”并不等于“任务做对了”。当项目、目标、范围或成功标准没有确认时，过早执行会把 Agent 的猜测放大成方案、代码、测试和后续补丁。

SA 将这些判断显式放在执行之前：

理解问题
  ↓
确认目标、范围和完成条件
  ↓
讨论并收敛方案
  ↓
列出执行清单
  ↓
修改代码或文档
  ↓
用直接证据完成验证

关键未知会改变实现、风险或验收时，SA 先停下来讨论，不把自己的猜测当成用户决定。

工作方式

触发

• 用户把 SA、sa 或 Super Audit 作为独立称呼时显式触发；
• 真实仓库或工程项目需要工程决策、工程动作或正式评估时隐式触发；
• 普通问答、学习、翻译和总结不触发。

响应协议

SA 触发后，首次用户可见响应以 # SUPER AUDIT 开始，固定输出八个字段：本轮概述、触发路由、工程模式、风险等级、响应策略、当前阶段、当前状态、项目约束。后续进度沿用该协议，不重复建立。

路由

只要求分析、审查、定位、解释或方案时，直接进入对应方法并在该阶段结束；要求修复、实现、开发、重构、优化或完成交付时，默认进入动态 Workflow。明确写出“只分析”“只审查”“只定位”“只给方案”或“不要修改”时，仍保持单阶段。Workflow 根据目标、证据、风险和当前阶段选择最小充分的方法，不把流程写死；发现原有假设被代码事实推翻时，会暂停并重新讨论。

理解

Agent 先确认当前项目、目标模块、已有行为、影响范围和成功证据。需求不清时，输出自己的理解并继续交互，不直接修改仓库。

决策

如果存在多种合理实现，Agent 根据代码、配置、调用关系和项目约束比较方案，说明影响和取舍，等待方向收敛。

执行

目标、范围和方案确认后，Agent 在写入代码、配置、测试或文档前列出执行清单，说明准备修改什么、为什么修改以及明确不处理什么。

验证

完成判断必须对应直接证据。测试通过只是证据的一部分，不能自动证明目标、范围和任务结果都正确。

核心能力

| 能力 | 解决的问题 | | --- | --- | | 需求澄清 | 把模糊陈述整理成可确认的目标、范围和成功标准；关键未知未收敛时不执行 | | 项目上下文 | 读取当前项目结构、模块职责、术语、调用链和关键路径 | | 方案研讨 | 在接口、数据、架构、兼容和影响范围存在分歧时比较方案 | | 产品调研 | 研究外部对象并形成独立的适用性判断 | | 动态 Workflow | 根据当前证据选择最小充分的方法，不把流程写死 | | 任务拆解 | 把已确认方案拆成依赖明确、可验证的任务 | | 独立工作树 | 在用户确认后创建、交付或清理独立 Git 工作树 | | 接口回归 | 从用户目标、SA 分析或已有请求材料进入接口回归，确认请求关系后执行并分析完整响应 | | 执行前检查 | 在修改代码、配置、测试或文档前展示改动清单和非目标 | | 故障调试 | 从可观察症状、错误输出和回归结果追踪到根因 | | 测试先行 | 在明确要求时执行 RED-GREEN-REFACTOR，并保护真实行为契约 | | 代码审查 | 只报告有证据、有真实影响且可执行的问题 | | 架构审查 | 识别职责混乱、重复事实所有者、补丁堆叠和扩展性缺陷 | | 审查意见核验 | 核验其他 Agent、审查者或外部文档提出的意见是否适用于当前项目 | | 完成验证 | 将完成条件与直接证据对应，区分完成、未完成和受限完成 | | 项目约束 | 保存当前项目专属的长期规则，不污染其他仓库 | | 快捷问题 | 保存个人跨项目重复使用的提问和工作偏好 | | 文档记录 | 将已经收敛的方案、任务、决策和验收结果整理成自包含文档 | | 任务续接 | 根据任务快照和当前证据恢复中断任务，并检查状态漂移 | | 经验沉淀 | 归因重复出现的 Agent 偏差，判断是否需要形成改进规则 |

Skill 索引

以下方法由 super-audit 动态路由并按需读取。宿主只发现顶层 super-audit，不单独安装或发现这些内部方法；每个方法仍保留自己的前置条件和输出契约。

理解与决策

• clarify-requirements：需求目标、范围或完成标准尚未明确时使用。
• project-context：需要读取项目结构、职责或关键路径时使用。
• project-constraints：需要建立、查看、修改、合并或压缩项目规则时使用。
• design-research：需求明确但实现方案尚未收敛时使用。
• product-research：需要研究外部产品、技术或竞品并形成独立适用性判断时使用。
• decompose-tasks：目标和方案确认后，需要拆成可执行任务时使用。
• api-regression：需要回归一个或多个 HTTP 接口时使用；目标可以来自用户要求、SA 分析或已有接口材料。

执行与验证

• execute-plan：按已确认方案修改代码、配置、测试或文档。
• git-worktree：从合入基线再开一个工作目录，并说明从哪个目录启动。
• debug-issues：定位具体错误、回归、性能异常或状态不一致。
• test-first：用户明确要求测试优先或 RED-GREEN-REFACTOR 时使用。
• verify-complete：根据完成条件和直接证据判断任务是否完成。

审查与交接

• code-review：审查已有变更、补丁或提交范围。
• architecture-review：判断是否存在需要整体处理的结构性问题。
• review-feedback：核验其他 Agent、审查者或外部文档提出的意见。
• workflow-orchestrator：根据闭环交付意图动态编排多个工程阶段；SA flow 是显式入口。
• resume-task：恢复已有快照、计划或未完成任务。

记录与沉淀

• record-document：记录已经收敛的分析、方案、任务或验收结果。
• reflect-learn：分析重复偏差并形成后续改进建议。
• quick-questions：管理个人全局快捷问题。

项目记忆

SA 将不同生命周期的信息分开管理：

• 项目约束：当前仓库长期有效的规则和边界；
• 快捷问题：个人跨项目重复使用的问题；
• todo/：当前版本计划、任务拆解和验收安排；
• temp/：尚未收敛的临时材料；
• docs/：已经确认的稳定结论和项目文档。

这些信息不互相替代，也不会因为一次临时任务自动扩散到其他项目。

安装

普通用户安装（推荐）

npm i super-audit

如果希望长期使用 CLI，可以全局安装：

npm i -g super-audit

安装时会自动探测宿主适配器目录中可用的宿主，先安装普通 Skill；如果检测到 Codex，再通过官方 Marketplace 额外安装 Codex 原生插件。其他宿主继续使用普通 Skill。用户不需要再执行额外的 setup 命令。

未检测到支持的宿主时安装失败；请先安装宿主，或使用 CLI 的 install --host 明确指定普通 Skill 宿主。

仅安装到指定宿主

super-audit install --host codex

这是有明确需要时的高级选项，不是普通用户的安装前提。

卸载

super-audit uninstall

安装器会把完整 Skill 集合写入宿主官方目录。npm 包是单个跨平台包，安装后由本地 shim 选择当前平台对应的二进制。

CLI

CLI 只提供确定性的本地能力，以及不影响主流程的只读版本提示；它不替代 Agent 的需求理解和语义判断：

super-audit install                 # 安装 Skill
super-audit install --host codex    # 安装到 Codex
super-audit setup                   # 自动初始化宿主与 Codex 插件
super-audit check                   # 只读检查 Skill 与 Codex 插件状态
super-audit uninstall               # 卸载 Skill
super-audit install --check         # 只读检查已安装副本是否漂移
super-audit context --format json   # 读取当前项目约束
super-audit audit --format json     # 采集只读 Git 工作区事实
super-audit --version               # 查看版本

JSON 命令统一使用以下成功结构：

{
  "ok": true,
  "data": {}
}

context 在成功读取项目约束后，还会按本地缓存周期执行只读版本检查；发现新版本时，在同一响应的顶层附加 _notice.update。版本检查失败不会影响项目约束结果，也不会自动升级。

命令失败时，结构化错误写入 stderr：

{
  "ok": false,
  "error": {
    "type": "state",
    "message": "项目约束状态无效",
    "hint": "请检查 PROJECT.md"
  }
}

没有 Git 仓库时，audit 无法提供 Git 快照；其他 Skill 能力仍然可以使用。

install --check 不会创建、覆盖或删除文件。它比较当前 CLI 构建内嵌的 super-audit 内容与已安装副本，并报告 in_sync、missing、drift 或 foreign 状态；发现 drift 后，再由用户明确执行 install 完成同步。

公开项目

• npm：super-audit
• GitHub：rayho-huang/super-audit

开发者验证

go test ./...
go vet ./...
python3 skills/super-audit/references/methods/workflow-orchestrator/scripts/validate_workflow.py
git diff --check

普通用户安装在检测到 Codex 时会创建 SA 管理的 npm 来源 Marketplace，并调用 Codex 官方插件命令；未检测到 Codex 时不会创建这些内容。npm 安装链路会验证这两种情况：

bash tests/codex/test-install.sh
bash tests/npm/test-package.sh
bash tests/npm/test-install.sh

License

MIT