no-negative-echo vs ruff AGENTS.md:AI 交付文案规范终极对照,你的项目该抄哪份?
no-negative-echo vs ruff AGENTS.md:AI 交付文案规范终极对照,你的项目该抄哪份?
本文对照 no-negative-echo Skill 与 ruff 风格的 AGENTS.md 交付规范两种做法:前者是完整可安装的 AI 交付文案规范 Skill,后者是把核心规则写进项目 AGENTS.md 的轻量约束。文章帮你判断自己的项目该抄哪一份。
🍳 先看问题:AI 交付文案是怎么"被污染"的
用 Codex、Claude 这类 Agent 干活时,很多人遇到过同一个尴尬:代码已经改对了,但 commit 写着"移除冗余方案 B",PR 标题写着"番茄炒蛋(无东坡肉)",注释还在解释为什么不用东坡肉。
这就是 no-negative-echo 项目要解决的**负向回声(negative echo)**问题:
- 会话里被否决的方案,复述进了 commit、PR 和注释
- 用户的纠正("不要提 X")本身,被写成了"无 X"
- 长对话、多轮修改后,交付说明还在回放整个沟通过程
BACKGROUND.md 里记录了这个问题在中文和英文社区的广泛反馈,连 ruff 这样的头部开源项目都把"读者没看过本次会话"写进了验收标准。
一张图看懂这个痛点:左边是散乱的会话草稿,右边才是干净的最终交付物。
⚖️ 核心差异:一页规则 vs 完整 Skill
| 维度 | AGENTS.md 规则式(ruff 风格) | no-negative-echo Skill |
|---|---|---|
| 形态 | 项目根目录一个 Markdown 文件 | 可安装的 Agent Skills 包 |
| 生效方式 | 每次会话开始自动读取,持续生效 | 重要交付前显式调用,按需生效 |
| 覆盖范围 | 核心行为约束 | 判断流程 + 检查脚本 + 高保障模式 |
| 依赖 | 宿主 Agent 对 AGENTS.md 的支持 |
Python 3.10+ 与安装脚本 |
| 适合场景 | 日常持续约束 | 发布、PR、敏感交付前的完整收口 |
一句话总结:AGENTS.md 管"平时",Skill 管"关键时刻"。项目 README 也明确建议两者可以同时使用,详见 README.md。
✍️ 抄 AGENTS.md 这份:三步落地交付规范
如果你的项目只需要"少留会话残留"这一条核心约束,直接抄精简规则即可。
第一步:在项目根目录新建或追加 AGENTS.md(已存在则追加,不要覆盖)。
第二步:把 README.md 中的精简指令贴进去,核心就这几条:
生成标题、注释、commit、PR 等最终产物时,只描述最终采用的状态,
假设读者没看过本次会话。
- 会话里的否决、中间尝试只当控制信息,不成为产物的叙述中心
- 「不要提 X」不是让你写「无 X」,从正向目标重新生成标题
- 保留真实的基线变化与必要的技术名称、诊断、测试
第三步:修改后开启新会话再运行,确保规则被加载。
ruff 的这条规则值得单独抄走:"写完通读一遍,假设自己是一个没有 Codex 会话权限的人"——把验收标准从"我删干净了"变成"陌生读者看不出删过什么"。
📦 装 no-negative-echo Skill:重要交付的完整流程
当交付涉及公开发布、多人协作收口,或需要逐面检查时,安装 Skill 更稳妥。
一键安装(本地示例):
git clone https://gitcode.com/gh_mirrors/no/no-negative-echo
cd no-negative-echo
python3 -I -m unittest discover -s tests -p 'test_*.py'
python3 -I scripts/install_skill.py \
--expected-provenance-sha256 d42280b21f519ea00e417c68f31c68ca3d7faae607faf6dcb6e04beeff9c5ed6 \
--discovery-root "$HOME/.agents/skills" \
--agent codex
完整安全约束与多宿主适配见 INSTALL.md。
安装后,重要交付前显式调用:
使用 no-negative-echo Skill。
根据最终 diff 写 commit subject、PR 标题、PR 正文和交付说明。
Skill 相比裸规则多出三样东西:
- 判断流程:先识别正向目标与最终状态,再生成文案,见 SKILL.md
- 文本扫描器:scripts/check_surface.py 可精确检查指定词是否残留在文案和文件名中
- 高保障模式:涉敏感信息、公开发布时,按 references/high-assurance-finalization.md 走冻结—回读—复检流程
❓ 三个判断问题:哪些内容该留、该删
两种做法共享同一套判断逻辑——对每个交付面(标题、文件名、注释、commit、PR)问三个问题:
| 问题 | 答案指向 |
|---|---|
| 没看过本轮对话的读者需要这条信息吗? | 不需要 → 省略 |
| 省略会造成事实错误、安全风险或兼容问题吗? | 会 → 保留 |
| 它是基线中的真实变化,且当前交付面需要解释吗? | 是 → 保留 |
据此形成一张快速对照表:
| 内容 | 处理 |
|---|---|
| 只在会话里讨论、从未合入的方案 | 省略 |
| 助手草稿、中间尝试、措辞纠正 | 省略 |
| 已发布的 API 删除、迁移与外部操作 | 如实说明 |
| 安全、法律、兼容性、审计所需事实 | 保留 |
| 任务开始前已有的用户改动 | 保留归属,不算本次成果 |
注意:仅仅"出现过"或"被否过"不是保留理由。
🧭 选型速查:你的项目该抄哪份?
| 你的场景 | 建议 |
|---|---|
| 个人项目、轻量协作,日常生成 commit / PR | 只抄 AGENTS.md 精简规则 |
| 多轮修改、多人协作后的最终收口 | 两者都用:规则管日常,Skill 管收口 |
| 对外发布、审计要求高的交付 | 必装 Skill,并启用高保障模式 |
| 宿主不支持 Skill 机制 | 退回 AGENTS.md 方式 |
⚠️ 边界说明:提示词规范 ≠ 确定性过滤器
无论抄哪份,都要清楚它的边界:
- Skill 被"发现"不等于"激活",重要交付请显式调用
- 扫描器
PASS只代表精确文本检查通过,语义改写仍需人工通读 - 它不能清除模型已读上下文,也不控制工具日志与宿主界面
- 不要为了"通过检查"而改动 API、迁移、测试快照或用户已有改动
📚 延伸阅读
- 安装合约:INSTALL.md
- 设计背景与社区证据:BACKGROUND.md
- 默认工作流:SKILL.md
- 评测协议与公开用例:evals/evaluation-protocol.md
