no-negative-echo vs ruff AGENTS.md:AI 交付文案规范终极对照,你的项目该抄哪份?

原创2026-10-23 14:00:131,698 阅读

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 这样的头部开源项目都把"读者没看过本次会话"写进了验收标准。

一张图看懂这个痛点:左边是散乱的会话草稿,右边才是干净的最终交付物。

no-negative-echo AI交付文案规范:会话残留与干净最终交付物的对照

⚖️ 核心差异:一页规则 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 相比裸规则多出三样东西:

❓ 三个判断问题:哪些内容该留、该删

两种做法共享同一套判断逻辑——对每个交付面(标题、文件名、注释、commit、PR)问三个问题:

问题 答案指向
没看过本轮对话的读者需要这条信息吗? 不需要 → 省略
省略会造成事实错误、安全风险或兼容问题吗? 会 → 保留
它是基线中的真实变化,且当前交付面需要解释吗? 是 → 保留

据此形成一张快速对照表:

内容 处理
只在会话里讨论、从未合入的方案 省略
助手草稿、中间尝试、措辞纠正 省略
已发布的 API 删除、迁移与外部操作 如实说明
安全、法律、兼容性、审计所需事实 保留
任务开始前已有的用户改动 保留归属,不算本次成果

注意:仅仅"出现过"或"被否过"不是保留理由。

🧭 选型速查:你的项目该抄哪份?

你的场景 建议
个人项目、轻量协作,日常生成 commit / PR 只抄 AGENTS.md 精简规则
多轮修改、多人协作后的最终收口 两者都用:规则管日常,Skill 管收口
对外发布、审计要求高的交付 必装 Skill,并启用高保障模式
宿主不支持 Skill 机制 退回 AGENTS.md 方式

⚠️ 边界说明:提示词规范 ≠ 确定性过滤器

无论抄哪份,都要清楚它的边界:

  • Skill 被"发现"不等于"激活",重要交付请显式调用
  • 扫描器 PASS 只代表精确文本检查通过,语义改写仍需人工通读
  • 它不能清除模型已读上下文,也不控制工具日志与宿主界面
  • 不要为了"通过检查"而改动 API、迁移、测试快照或用户已有改动

📚 延伸阅读

登录后查看全文
no-negative-echo