Assurance

---

编码 Agent 结束时会说 “全部完成了——测试通过。” Assurance 会读取实际发生的情况，用通俗的语句告诉你完成了什么、跳过了什么，以及哪些内容无法验证。

快速开始

在使用过 Claude Code 或 Codex 的任意项目中运行：

uvx assurance audit                        # with uv: runs it without installing anything
pip install assurance && assurance audit   # without uv

它会读取任一 Agent 为此文件夹留下的最新会话，无需配置，也无需指定你用的是哪个 Agent。还没用过这两者？运行 uvx assurance audit --demo，即可查看内置示例会话的报告。

没有 uvx？它随 uv 一起提供。运行一条命令即可安装：

位置	命令
macOS（Homebrew）	brew install uv
macOS / Linux	curl -LsSf https://astral.sh/uv/install.sh | sh
Windows	powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Windows（WinGet）	winget install --id=astral-sh.uv -e
任何已安装 Python 的环境	pipx install uv 或 pip install uv

之后打开一个新的终端，让 uvx 加入 PATH。也可以完全跳过 uv，使用 pip install assurance，这会提供相同的 assurance 命令。

以下是本仓库中示例会话的真实输出。Agent 被要求修复 invoice.py 中的舍入错误，“并确保 pytest -q tests/test_invoice.py 通过”，最后却说 “全部完成了——现在总额正确了。”

$ assurance audit examples/audit/sample-session.jsonl
Claude Code session demo-8f2 — 13 min in /home/you/my-app
10 tool calls, 3 failed — Bash 6, Edit 2, Grep 1, Read 1

  Looped: 3 rounds of Bash `pytest -q tests/test_invoice.py` failing the same way, with nothing new read
  After the last edit (14:09): no test or check it recognises; 2 unclassified commands ran after it (make lint-fix, python script)
  Against the last prompt (14:00, "The invoice totals are off by a cent for EUR. Fix it in inv…"):
    invoice.py: changed at 14:04 (src/billing/invoice.py).
    pytest -q tests/test_invoice.py: did not run after the last edit to src/billing/rates.py (14:09); it last failed at 14:08, before that.
    Only what the last prompt names is checked here; whether the work does what it asks is not.
  Not classified: 2 shell commands (make lint-fix, python script), so whether they read, wrote or tested anything is unknown.
  Also in the transcript: 1 assistant turn, 1 user turn, 1 bookkeeping record.
  Not read: 0 lines.

“全部完成”遗漏了这些内容：

• ❌ 测试连续失败了 三次，每次情况都一样。
• ❔ 最后一次编辑之后，没有运行它能识别的测试。虽然运行了两条命令，但它无法确认这两条命令的结果，因此会明确列出。没有报告不代表通过。
• ❔ 提示词要求的测试最后一次运行是在最后一次编辑之前，而且失败了。它指定的文件已被修改。它并不声称知道修复是否正确，并且会明确说明这一点。

在每次会话结束后运行

启用 Stop 钩子后，每当 Claude Code 完成一轮对话，都会运行审计。只有在有内容需要提醒时，它才会发声，并且会先指出以下三个级别之一：

级别	触发条件	会询问谁
提示	本轮代码发生了更改，但尚未测试	只询问你一次，并提供要运行的命令。不询问 Claude
建议审查	最后一次编辑后测试失败、受保护路径发生更改，或 Claude 声称测试通过但没有依据	询问你和 Claude：修复问题或说明原因
停止并检查	未经测试的代码被推送、合并、发布、部署、迁移，或提交到了 main	询问你和 Claude：在其他内容基于它构建之前先验证

assurance · note: no test or check has passed since the last edit to src/billing/invoice.py (14:04). Run pytest -q tests/test_invoice.py before you commit or push.
assurance · suggested review: the last test run after the last edit to src/billing/invoice.py (14:04) failed: pytest -q tests/test_invoice.py (tests/test_invoice.py::test_eur_rounding; 1 failed, 11 passed in 0.33s).
assurance · stop and check: pushed at 14:06 with no passing test or check after the last edit to src/billing/invoice.py (14:04).

uvx assurance@latest hook install   # shows the change to ~/.claude/settings.json, asks, then writes it
uvx assurance hook remove           # takes it out again; nothing else changes

它知道 Maven、Gradle、Bazel、Django、Rails、jest、vitest、go、cargo 等工具的测试命令，会读取你的 package.json、Makefile 和 justfile 脚本来了解项目的测试命令，并且绝不会将未运行任何测试视为通过。它能识别的内容。

也可以将其作为 Claude Code 插件使用：claude plugin marketplace add i-ops-hq/assurance，然后运行 claude plugin install assurance@i-ops-hq。它绝不会阻止会话，也不会导致会话失败。关于固定版本、与团队共享、Windows 以及插件的运行内容：钩子指南。

使用场景

了解 Assurance 如何融入你现有的工作流程。每个页面都很简短：说明可能出现的问题、它所处的位置，以及用于配置它的代码行。

你的工作	它会为你检查什么
支付与金融科技	确保依赖这些测试的支付代码在最后一次编辑后、发布之前完成测试并通过
银行业务与受监管变更	每个会话都有一份记录，说明更改了什么、测试了什么，以及发起者是否获得了变更涉及的每位所有者的授权
医疗保健与生命科学	Agent 未经询问便更改的受保护路径；安装操作运行前将执行的内容
法律、保险与文档	研究 Agent 是否读取了问题所需的每份文档；报告文件夹中是否缺少某些时间段
平台、DevOps 与 SRE	对未经测试的代码进行推送、部署和迁移；变更会影响什么；会话无法提高的限制
构建自有 Agent 的团队	根据运行记录或 OTel 跟踪数据，核对你的 Agent 的“完成”与其门禁的“允许”，以及之后实际发生的情况

prompt ─▶ agent edits ─▶ note ─▶ tests ─▶ suggested review ─▶ push / deploy ─▶ stop and check ─▶ CI gate

命令

安装一次，使用一个 assurance 命令。

命令	回答的问题
assurance audit	此文件夹中的 Claude Code 或 Codex 会话，或你自己的 Agent 运行或跟踪记录，做了什么，又跳过了什么？
assurance hook	在每轮 Claude Code 对话后运行该审计，或停止运行：install、remove、status。
assurance notices	每次 hook 提示之后，下一轮是否运行了测试、修复了故障或还原了文件？从这台机器的对话记录中读取；不会发送任何内容。
assurance serve	一个本地端点，任何 Agent 都可以向它发送跟踪记录或运行记录，任何工作流也可以向它请求某次运行的审计结果。
assurance coupling	根据 git 历史，哪些内容通常会和你刚改动的内容一起变化？其中哪些你还没碰？无需图谱或配置。
assurance reach	通过 Graphify 等代码图谱，修改此文件会影响哪些范围？该图谱落后于代码多少？
assurance clearance	提出修改的人是否已获准触及修改影响范围内每位所有者的内容？
assurance diff	工作是否涵盖了所有应涵盖的内容？例如，已检索的文档与必需文档是否一致。
assurance pin	MCP 服务是否在你批准后悄悄修改了工具的描述？
assurance deps	pip install 或 npm install 会在你的机器上运行什么？只读取，不运行。
assurance budget	Agent 运行的预算花在了哪里？又在哪里陷入循环？
assurance authority	对于提出请求的人，这项任务是否可以继续，而无需借用他人的访问权限？
assurance check	一组带日期的报告是否完整？缺少哪些时间段？

每个命令都可以直接用作 CI 门禁：

退出代码	含义
0	已检查，未发现问题
1	有需要查看的内容，包括无法检查的内容
2	无法运行

指南

• 每次会话后运行：完整级别、固定、团队设置、插件、Windows
• 项目规则：声明自己的测试、必须通过的检查、禁止触及的内容，以及 Agent 无法自行提高的限制
• 你自己的 Agent：运行记录、OpenTelemetry 跟踪记录和本地端点
• 更多检查：检索覆盖率、MCP 固定、安装、修改影响范围、MCP 工具

它不会做什么

• 猜测。 如果无法确定某个数字，它会如实说明，而不是凭空编造。
• 调用模型或访问网络。 每个结果都是你可以自行核验的算术运算。
• 声称超出它所看到的范围。 audit 会读取 Claude Code 对话记录、Codex 运行记录，以及你自己的 Agent 写入的运行记录。它不认识的记录格式会计为未读取，而绝不会猜测成工具调用——报告会显示该数量。接下来将支持其他 Agent 自己的日志： 告诉我们你使用的是哪个。

告诉我们哪里不对

项目还处于早期阶段，你能做的最有帮助的事，就是在实际工作中运行它。

• 🎯 它给出了错误或误导性的答案。这是最有价值的反馈。
• 🐛 有问题无法运行
• 💡 支持其他 Agent、锁文件或框架
• 🤝 **贡献：**选择一个 适合新手的 issue，并阅读 CONTRIBUTING.md。

如果它对你有用，点个 ⭐ 能帮助其他人发现它。

软件包

pip install assurance 会安装所有命令。每个部分也可以单独安装。

软件包	说明
assurance-cli	assurance 命令：diff、check、pin、drift、init
assurance-budget	用于编码 Agent 会话的 audit，以及用于运行日志的 budget
assurance-deps	读取安装将要运行的内容，而不实际运行
assurance-authority	确定请求者是否有权批准任务继续进行
assurance-reach	通过代码图谱分析更改的影响范围，以及该图谱落后代码多少
assurance-mcp	以只读 MCP 工具形式提供检查，范围仅限 --root
assurance-core	底层的纯决策库。不涉及 I/O、模型或依赖

---