whaojie797-design/change-proof

change-proof

让 Agent 在提交代码前，自动回答“改了什么、为什么安全、怎么验证、哪里仍有风险”。

Make any AI coding agent answer four questions before it commits: what changed, why it is safe, how to verify, and what risks remain.

一个跨平台、框架无关的 Agent Skill。把任意功能改动变成一份可审计的变更证据包（CHANGE_PROOF.md），解决“代码看起来能跑，但无法证明可上线”的问题。

A cross-platform, framework-agnostic Agent Skill that turns any code change into an auditable change-proof package, solving the problem of “the code looks like it runs, but you can’t prove it’s ready to ship.”

适用宿主 / Works with: Codex · Claude Code · Cursor · Gemini CLI.

演示 / Demo

change-proof demo

上图是动画占位 SVG，发布前请替换为真实的 30 秒 GIF。

The image above is an animated placeholder SVG. Replace it with a real 30-second GIF before publishing.

为什么需要 / Why

普通 AI 交付只给代码，带证据交付给的是“代码 + 证据 + 风险 + 回滚”。

普通 AI 交付 vs 带证据交付 / Plain delivery vs Evidence delivery

| 维度 | 普通 AI 交付 / Plain delivery | 带证据交付（change-proof）/ Evidence delivery |
|---|---|---|
| 改了什么 | 一段代码 + “已修改 xxx” | 文件/接口/数据/配置/依赖 全量清单 |
| 为什么安全 | “应该没问题” | 五维风险评级（兼容/安全/性能/迁移/回滚）|
| 怎么验证 | “测试通过了” | 验证矩阵：每项标注 通过/失败/未执行 + 命令证据 |
| 风险在哪 | 不提或藏起来 | 显式列出未验证项 + 人工复核清单 |
| 出事怎么办 | 没有 | 回滚命令 + 数据回滚步骤 |
| 可审计 | ❌ | ✅ 一份 CHANGE_PROOF.md 留痕 |

红线 / Red line：没有真正运行过的测试，状态必须写 未执行，禁止伪造通过。
Tests that were never actually run must be marked 未执行 (not executed). Forging a pass is strictly forbidden.

安装 / Install

每个宿主单独安装（不是 bundle），把本目录放进对应 skills 目录即可。

Install separately into each host’s skills directory — this is not a bundled plugin.

Claude Code

git clone https://github.com/whaojie797-design/change-proof ~/.claude/skills/change-proof

Cursor

git clone https://github.com/whaojie797-design/change-proof ~/.cursor/skills/change-proof

Codex

git clone https://github.com/whaojie797-design/change-proof ~/.codex/skills/change-proof

手动 / Manual

下载或复制本目录到任意宿主的 skills/ 下即可
Download or copy this directory into any host's skills/ folder

安装后无需额外配置、无需 API Key。Agent 会在触发场景下自动加载 SKILL.md。

No extra config or API key needed. The agent auto-loads SKILL.md on trigger.

触发场景 / Trigger scenes

- 新增功能 / New feature
- 修复 bug / Bug fix
- 准备提交 / Pre-commit
- 准备发版 / Pre-release
- PR 自查 / PR self-review
- 上线前检查 / Pre-deploy check

强制阶段 / Mandatory phases

1. 变更范围识别 — 文件、接口、数据模型、配置、依赖
2. 风险分类 — 兼容性、安全、性能、迁移、回滚
3. 验证计划 — 已有测试、需补测试、手工验证步骤
4. 证据收集 — 命令、输出摘要、失败项、未验证项
5. 输出 CHANGE_PROOF.md — 变更摘要 / 影响面 / 验证矩阵 / 风险等级 / 回滚方案 / 人工复核项

详见 SKILL.md，补充规则见 references/。

目录结构 / Structure

change-proof/
├── SKILL.md                 # 入口：触发场景 + 五阶段 + 红线
├── README.md                # 本文件
├── LICENSE                  # MIT
├── EVALUATION.md            # 20 个评测场景
├── docs/demo.svg            # 演示占位图
├── references/
│   ├── default-rules.md          # 框架无关默认规则（始终加载）
│   ├── react-nextjs-rules.md     # React / Next.js 补充规则
│   ├── python-fastapi-rules.md   # Python / FastAPI 补充规则
│   └── nodejs-rules.md          # Node.js 补充规则
└── scripts/
├── diff-checklist.py     # 扫描 git diff，打印初始验证清单
└── diff-checklist.sh     # 纯 shell 版本

设计原则：轻量。单个项目只新增一个 CHANGE_PROOF.md 和必要测试，不引入 CI 平台依赖。
设计原则：轻量。单个项目只新增一个 CHANGE_PROOF.md 和必要测试，不引入 CI 平台依赖。

可选脚本 / 可选脚本

扫描 git diff 并打印一份初始验证清单，不替代人工复核与测试。

python3 scripts/diff-checklist.py
或 / 或
bash scripts/diff-checklist.sh

隐私 / 隐私

- 完全本地运行，不上传任何代码或数据。
- 不需要任何 API Key、Token。
- 不调用任何第三方服务。
- 唯一产物是项目根目录下的 CHANGE_PROOF.md。

完全本地运行。不上传，不需要密钥，不调用第三方服务。唯一的产物是项目根目录下的 CHANGE_PROOF.md。

许可证 / 许可证

MIT — Copyright (c) 2026 whaojie797-design。见 LICENSE。