📄 门禁类操作补充就地检查清单与流程合规证据要求 (针对 Claude 的行为偏差） - #1761
cyfung1031 wants to merge 1 commit into
Conversation
AGENTS.md 的路由表本身会随会话变长而在显著性上衰减:表中一行读过之后,真正 触发该行所指向动作(命令、发布调用、破坏性操作)可能是几十次工具调用之后 的事,单靠"表里写了"不足以保证该动作发生时仍会被正确执行前置条件。 - AGENTS.md「Route the task before acting」:补充一段面向执行时的行为 准则——路由表的一行只是指向所有者文档,真正的门禁是该文档里紧邻动作 机制描述之处的检查清单(以 docs/develop.md#revision-scope-and-publication-binding 为范例),而非表项本身;当环境提供在动作触发那一刻生效的机制(前置钩子、 强制确认、lint/CI 门禁)时,优先接入该机制而非依赖这张表的显著性。 - docs/DOC-MAINTENANCE.md「Checklist 1 — Organization」:补充一条面向文档 维护者的检查项——新增一条门禁类路由表行时,须在其所有者文档里同步补充 就地检查清单,而非只留一个指回表格的指针;这条"如何撰写"指令按照该文件 自身的所有权边界放在这里,而非 AGENTS.md,避免每个任务都承担一条只有 文档维护时才用得到的规则。 - AGENTS.md「Completion checksum → Owners/facts」:将"每个任务部分遵循其 路由所有者"收紧为可证伪的要求——需要点名具体文档并复述实际套用的约束 或绑定的路径,而不是让"我照着路由表做了"成为一句无法验证的断言,统一到 本文件已经对代码类声明设下的同一证据标准。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
@CodFrm 对Claude来说是必须。详见上述背景 |
cyfung1031
changed the title
我感觉不如加hook去限制和约束，加提示词依旧概率性发生，而且又浪费上下文， 不如整理一下规则，看看哪些可以由hook/lint去处理，然后删掉相关的提示词，让lint去约束 这文档越加越大了，已经快来到300行 用
|
我认为那些 Engineering Principles 都可以或已经放到 references 里 我不想乱改你的文件 可以加一个 contract.md 之类的做处理 |
这个 PR 就是去约束Agent的思考行为。不是针对单一行为。 |
2 participants
Checklist / 检查清单
背景
在一次修复 npm 依赖漏洞的会话中,创建/更新 PR 前本应先读
docs/pull-request.md与docs/develop.md#revision-scope-and-publication-binding(AGENTS.md 路由表已列出这一行),但实际上下文里虽然装着这张表,却在真正调用
gh pr create那一刻没有回头核对——表在会话早期读过一次,到动作真正发生时已经过了很多轮工具调用,显著性衰减了。事后复盘发现 AGENTS.md 自己已经在用近似
的措辞提醒过这种失效模式("Routing is continuous, not a classification you make once"),但纯说明性、
只读一次的提醒本身就有上限——这不是措辞不够好的问题,而是结构性的:没有在动作真正触发的那一刻
重新提示。
本次改动
的一行只是指向所有者文档,真正的门禁是该文档里紧邻动作机制描述之处的检查清单(以
docs/develop.md#revision-scope-and-publication-binding为范例),而非表项本身;当环境提供在动作触发那一刻生效的机制(前置钩子、强制确认、lint/CI 门禁)时,优先接入该机制而非依赖这张表的显
著性。
一条门禁类路由表行时,须在其所有者文档里同步补充就地检查清单,而非只留一个指回表格的指针。
伪的要求——需要点名具体文档并复述实际套用的约束或绑定的路径,不能让"我照着路由表做了"成为一句
无法验证的断言,统一到本文件已经对代码类声明设下的同一证据标准(
Match claim strength to evidence)。实现考虑
docs/DOC-MAINTENANCE.md明确说明CLAUDE.md只是指向AGENTS.md的兼容性符号链接,AGENTS.md才是实际所有者,因此改动只落在
AGENTS.md,未触碰CLAUDE.md。docs/DOC-MAINTENANCE.md「Instruction budget」的要求(优先收紧已有规则而非新增,一条规则只在其所有者文档里说一次),"新增门禁行时如何撰写就地检查清单"这条指令放进
docs/DOC-MAINTENANCE.md,不放进AGENTS.md——因为它只在文档维护时才用得到,不应成为每个任务都要加载的标准成本;
AGENTS.md里只保留与"执行任务时如何跟随门禁行"直接相关的行为准则。Owners/facts一条选择"收紧既有 bullet"而不是新增一条 bullet,同样是为了避免同一原则在文件里被复述两次。
("当环境提供……时"),不指定具体钩子文件,因为
AGENTS.md是要能被任意智能体工具链读取的通用契约,不应假定某一种特定的 hook 机制存在。
已知限制
本地化、验证等)——那些行是否需要各自所有者文档补一份就地检查清单,留给各自文档在下次改动时
按新加的 Checklist 1 检查项处理。
建议审查重点
AGENTS.md新增段落是否真的只停留在"执行任务时的行为"这一层,没有滑向"如何撰写新路由行"的文档维护指令(这正是第一轮自我审查抓到的问题)。
Owners/facts新措辞对协作者(人类或智能体)是否可操作——"点名文档 + 复述约束或绑定路径"是否足够具体。
docs/develop.md#revision-scope-and-publication-binding之间是否有事实重复(而不只是呼应)。
验证
docs/DOC-MAINTENANCE.md「One-shot verification」给出的链接检查脚本,分别对改动前的
origin/main(0 处 broken)和改动后的最终树(0 处 broken)执行,diff结果为空。docs/DOC-MAINTENANCE.md「Policy-consistency check」给出的绝对化措辞 grep,新增文字里唯一命中的 "must not" 已确认是有意为之的强规则,未被放宽。
docs/DOC-MAINTENANCE.md合规性与文风一致性,一个核对是否忠实覆盖会话里提出的三条原则)分三轮审阅最终 diff。第一轮发现真实问题(一条应属于
docs/DOC-MAINTENANCE.md的文档维护指令被误放进AGENTS.md,以及两处文风瑕疵),已在第二轮修正;第二轮又指出一处冗余指针句,已在第三轮(即本次提交)删除。两个子代理在最终版本上均给出
PASS。
docs/README.md索引核对:未新增/改名/删除任何文档文件,其对AGENTS.md、docs/DOC-MAINTENANCE.md的条目均为整篇摘要,不因本次改动失真,无需更新。🤖 Generated with Claude Code