用途
这份文档是编写「AI 阅读并遵循的文档」时的通用准则，适用于 Agent Skill、CLAUDE.md、AGENTS.md 等类型。它被 kuden:agent-skill 技能与 kuden:persistent-instructions 技能共同引用：Agent Skill 特有的标准放在 kuden:agent-skill 中，规则文档特有的标准放在 kuden:persistent-instructions 中，本文档只承载两者共通的心得。
主要能力（四项心得）
心得 1：读者是聪明的模型
阅读并执行文档的是能够理解上下文、自行判断的模型。因此只写模型无法通过推理到达的内容，例如项目或作者特有的方针、隐藏的约束、从外部看不到的前提、不实际尝试就无法发现的 gotcha。
具体要求：
- 不防御性地明文写出「想一想就能明白」的判断，不添加 edge case 的排除规定，也不添加防止误读的但书。
- 不为理解力低的模型做设计；无法读取上下文的模型，也无法执行文档要求的其他工作。
- 如果用手顺或示例就能达成目的，就不写背景说明，例如事故经过、想避免的结果说明；像 git 的一般性质那样「想一想就明白」的理由也不写。
- 不写比喻。读者会推理比喻的其他侧面，导致句子含义变得模糊。
心得 2：只写面向执行模型的内容
选择某种方法的经过、尝试后被否决的方案，应写在 commit message 或 PR 概要栏中，而不是写进文档。
心得 3：编辑时以整体最优为目标
修改既有文档时，不要试图把变更差异保持得很小。不要把手头要加的内容直接接在既有章节末尾，而要考虑「如果这段内容从一开始就存在，会怎么写」。可以大幅改变结构。
心得 4：评审意见的采纳与否
外部 Agent 或 subagent 的指摘，即使作为事实是正确的，也不一定值得写进文档。在验证指摘是否正确之外，还要用以下四个问题决定是否采纳：
- 问 1：聪明的模型是否能在当场自行判断？
- 问 2：是否属于目标文档类型所固有的心得中「规定不要写」的内容？
- 问 3：是否是面向未来的编辑者，而不是面向执行模型？
- 问 4：如果没有它，模型是否会卡在执行上？
命中问 1 至问 3 的指摘不采纳；命中问 4 的指摘采纳。未采纳的指摘，需附上理由向用户报告。
使用方式
本文档本身是一份准则说明，未提供安装命令、代码或调用方式。它作为被引用项，供 kuden:agent-skill 与 kuden:persistent-instructions 两个技能在编写相应文档时参照。具体如何安装或集成，资料中暂未提供。
适用场景
- 编写或维护 Agent Skill 文档。
- 编写或维护 CLAUDE.md、AGENTS.md 等持久性指令文档。
- 对上述文档进行编辑与重构。
- 处理外部 Agent 或 subagent 对上述文档提出的评审意见。
限制
- 本文档只覆盖共通心得，不包含 Agent Skill 固有标准与规则文档固有标准，这两部分分别在 kuden:agent-skill 与 kuden:persistent-instructions 中。
- 资料未提供具体的安装、配置或运行步骤。
- 资料未提供收费、价格、平台支持范围等信息。