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

上图是动画占位 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

红线 / 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 平台依赖。 Design principle: lightweight. Only one CHANGE_PROOF.md and necessary tests per project — no CI platform lock-in.

可选脚本 / Optional script

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

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

隐私 / Privacy

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

Fully local. No upload, no keys, no third-party services. The only artifact is a CHANGE_PROOF.md in your project root.

许可证 / License

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