修改文档
官方指令文件管理插件自带一个 revise 命令,它会将会话期间的学习成果追加到根指令文件中。本技能的存在正是为了取代这一行为。一个只增不减的根指令文件最终不会被读完,而随意附加的学习内容往往不是未来会话在那一刻恰好需要的那个事实。本技能保留了该插件中有用的那一半——在写入前审计声明是否与代码库一致——并移除了追加那一半,转而采用路由。工具本身的本地机器内存笔记已经捕获了会话学习的内容,跳过了指令文件中已有的部分,因此本技能负责路由可共享、可检入的那一半:将规则路由到其路径覆盖了相关领域的规则文件中,将实践记录路由到仓库存档中。
默认流程
- 命名本次会话产生的值得保留的内容:一个修正、一个约定的惯例、一个 bug 及其修复、一个测量结果、一个两种方案之间的决策。
- 将其归类为规则或实践记录。
- 规则:每当匹配的情况再次出现时都适用。只需声明一次,并且在下次重构后仍然成立。
- 实践记录:事件仅发生一次,带有一个日期,并附有名称或测量数字。它是规则存在的证据,而不是规则本身。
- 将规则路由到匹配的规则文件。
- 按范围和标题搜索现有规则文件,而不仅仅是按文件名搜索。打开其
paths:已经覆盖了学习成果所涉及领域的规则文件。 - 如果已有文件覆盖该领域,则添加一个新标题或将点内容折叠到现有标题中。遵循规则结构:一个祈使句标题(本身就充当规则)、一条原因条款、一个命名强制执行者的
Anchor:行、一个指向存档条目的Receipts:行,并且文件以## 不要结尾。 - 验证后再写入。检查
Anchor:行中的每个标记、每个路径、每个脚本名称,确保它们在当前仓库中确实存在。这是从上述插件继承来的审计习惯:永远不要写入未经检查的声明。 - 如果没有文件覆盖,则说明情况,并建议新建一个规则文件或扩展现有文件的范围。不要仅仅因为接近就把点内容丢进最近的文件。
- 按范围和标题搜索现有规则文件,而不仅仅是按文件名搜索。打开其
- 将实践记录路由到仓库的存档层。
- 存档层是仓库用来存储带日期证据文档的任何东西:手册章节、设计历史文件、事后分析日志。在其中写入日期、名称、测量数字,并以为单行教训作为标题,使条目读起来像一条声明而不是文件名。
- 用条目的引用标题指向存档中的条目。不要在规则正文中重复实践记录的具体信息;规则中的日期或数字是穿着规则外衣的历史。
- 如果仓库还没有存档,则说明情况并建议开始建立。不要因为没有合适的存放位置就将实践记录折叠到规则文件或根文件中。
- 永远不要修改根指令文件。如果规则文件和存档都不合适,则表明该知识点不够持久,不值得保留,而不是默认将其放入根文件。直截了当地说明并停止操作。
- 在保存前展示编辑内容。打印你建议的标题和段落,或显示与现有文件的 diff,并等待确认,除非明确告知你直接进行修改。
当匹配的是受管理的团队规则时
如果已经覆盖该主题的文件是一个受管理的团队规则(带有受管理文件头,位于 .claude/rules/house/** 下),则不要在此仓库中编辑它。对受管理文件的本地修改会在下一次 /house-rules:sync 运行时被静默覆盖,而这种静默丢失正是 house 机制要防止的。
相反,建议向上游提出修改。草拟相同的标题和段落,然后说明此修改应作为更改在 house 仓库中提出,而不是在当前仓库中。如果该知识点确实特定于此仓库而不是一个全团队规则,则记录为 house.json 中的偏差,而不是 fork 受管理文件。这两种方式都能保持受管理文件的同步;原地编辑则不能。
逃生通道
- 学习成果与现有规则矛盾。 直截了当地说明,引用现有标题,并在写入任何内容前询问哪条规则优先。不要静默地用一条规则覆盖另一条。
- 学习成果是仓库特定的一次性记录,不具有规则形式,例如供应商 bug 的变通方案、仅需一次的注释。将其作为实践记录路由到存档,而不是用未来会话无需遵守的内容污染规则文件。
- 你不确定是规则还是实践记录。 偏向存档。归档错误的规则是日后可以提升的标题;而归类错误的规则会变成没有标志的无用文字。
- 仓库既没有规则文件也没有存档。 直截了当地说明并停止操作,而不是从本技能内部创建它们。那是
/house-rules:bootstrap的任务,不是本技能的任务。
不要
- 不要追加到根指令文件。这正是官方指令文件插件的 revise 命令的行为,也是本技能存在的原因。
- 不要编写其锚点未经代码库检查的规则句子。
- 不要在规则正文中重复实践记录的日期、名称或数字;应指向存档。
- 不要原地编辑受管理的团队规则文件。向上游提出修改或记录偏差。
- 不要保存对方未看到的编辑内容,除非明确告知你直接进行修改。
- 不要在仓库没有规则文件或存档时创建它们。