keep-codebase-maintainable

保持代码库易于维护

维护性任务不是在功能上额外打磨。交付成果应是一个更精简、更准确的代码树：删除未使用的内容，合并重复项，确保名称名副其实、文档与代码一致，差异中只包含要求的内容。

内容取自 Cooper 的 OMP Hindsight 提示库（他实际如何提示编码 Agent）。源示例：references/instances.md（副本也位于 /var/lib/hermes/workspace/omp-maintainability-asks.md）。

核心原则： 严守要求的范围。遵循 codebase-design，了解通用的可读性规则和 示例。移除只转发调用的抽象；保留能够隐藏复杂性、强制执行不变量或转换外部接口的抽象。

适用场景

当用户（或任务）表达的内容类似以下任意一种时，加载此技能：

• 清理 / 整理 / 精简 / 卫生检查 / 遗留内容 / 死代码 / 未使用内容
• 简化 / 缩小差异 / 精准修改 / 不要跑题
• 审计、修复和重组
• 重命名 / 合并 / 理清职责 / 单一包 / 简短名称
• “不要添加”、“不要新建服务”、“停止编写代码”、“不在范围内”
• 解释原因的注释 / 文档已过时 / 修复 AGENTS.md
• 保持易于维护 / 减少维护工作 / 提高内聚性

不适用场景： 实现用户要求的功能、修复故障行为，或对自己刚写完的差异进行功能完成后的检查——此时请遵循代码库的审查指南。

如果用户将“添加 X”和“清理 Y”放在一起，拆分提交。此技能负责 Y。

常规规则

以下规则优先于“乐于助人的 Agent”的默认直觉。

1. 删除测试。 如果一个符号 / 文件 / 包 / 依赖 / 标志 / 范围没有任何实际导入者，并且不是公共契约（导出的 API、框架对等依赖，或仍由运行中应用声明的 Helm 值），就应删除。搜索名称，再搜索旧名称。knip / ts-prune / depcheck 只能提供线索，不能作为证据——它们会误报框架对等依赖和动态导入。
2. 不要让死物复活。 删除过时的 Git 声明才是修复。为了“清除 Missing”而同步 / 应用 / 复活资源，则是错误。同样，对预留给未来使用的开关，也应彻底移除，而不是留下墓碑注释。
3. 一项职责，一个名称。 重复项会逐渐产生差异（两个调度器、menu 与 x、统一后遗留的 ManualCommitStep）。合并后，搜索废弃名称并删除重复项。
4. 优先使用原生能力，而非自定义实现。 如果库已提供所需能力，就使用该库。当本地适配器负责解码、错误处理、资源生命周期，或提供更简单而完整的操作时，应予保留；删除只对调用改名的包装层。
5. 名称简短且名副其实。 使用能体现所属能力的名称，例如 @repo/billing；避免把内容都堆进共享的 utils。在所属模块内，使用常见的职责目录。公共文档使用规范名称（x），不要使用旧别名。
6. 包 = 内聚单元。 通过明确的公共入口暴露完整操作；将实现放在 src/ 下，按所属模块和职责分组。让相关 SQL 和辅助代码与其适配器放在一起。测试应通过接口验证可观察行为，并遵循代码库的文件放置惯例。
7. 精准修改差异。 暂存指定路径。绝不运行 git add -A。每次提交只处理一个关注点。未经授权的额外改动应直接还原，不要争辩。“清理已获批准”不等于“可以合入主分支”。
8. 当前用户指令优先于参考性 AGENTS.md。 关于提交 / 推送的约束仍适用于远程变更，但不能作为启动额外 Agent 或扩大范围的授权。
9. 注释解释原因。 写明设计意图、不变量和边缘情况的理由。不要写 // increment counter。过时文档属于契约错误——应更新或删除。
10. 停止就是停止。 “停止所有编码。”“不要修改生产环境中的 auto/flash。”立即遵守范围限制。

流程

1. 明确任务

用一句话说明：要精简或纠正什么，以及哪些内容不在范围内。

完成标准：这句话中不包含任何功能。如果包含，就说明此技能不适用。

2. 动手前先盘点

列出候选项。暂时不要删除。

path:symbol  → why it looks dead  → consumers found (grep)  → contract?  → action

按以下顺序搜索：

• 未使用的文件 / 导出 / 依赖 / 标志 / Slack 权限范围 / Helm 遗留项
• 未完成统一后留下的旧副本（仍保留旧名称）
• 与锁文件矛盾的过时注释、README、AGENTS.md 固定版本
• 仍在宣传已弃用功能的命令 / 别名
• “留待以后使用”的配置项和未使用的错误变体
• 临时产物（/tmp/*、worktree、过时标签、已合并分支）

完成标准：每个候选项都有 grep 结果（包括“零匹配”）和契约判定。对于任何可能导致生产环境中断的内容（绑定、PVC、Hyperdrive、DNS、密钥），必须检查是否有活跃使用者。

3. 按风险顺序处理

层级	示例	操作
SAFE	未使用的导入、遗留的 /tmp、注释掉的代码块、失败编辑留下的重复配置段	立即删除。
CAREFUL	没有导入者的未使用文件、应用中没有导入的依赖、重命名为短名称、合并重复的辅助函数	删除 / 重命名，然后运行该包的定向测试 / lint。
RISKY	任何包含活跃绑定、公开导出、Helm/Argo 资源、密钥、对等依赖、“knip 命中数为零”的内容	核实是否有活跃使用者。如有，停止并说明。绝不按名称分组删除。

不要添加推测性的标志、服务或抽象。清理时，只有在明确改善授权范围内的理解时，才可引入本地辅助函数或结构清晰的模块。提取代码必须隐藏复杂性或支持有用的复用。保留已配置的行数限制；针对特定情况的例外应予以说明，不要为了满足数字而拆分成转发文件。

完成标准：所有 SAFE / CAREFUL 项目都已处理，或明确说明跳过原因；未经活跃使用者检查，不得处理任何 RISKY 项目。

4. 确保契约仍然成立

仅当以下内容因本次变更而不再正确时，才在同一变更集中更新：

• AGENTS.md / README 中的说明（版本、由谁发布评审、凭据存放位置）
• 描述刚删除路径的注释
• 指向已删除脚本的公开命令目录 / x 菜单项
• 仍使用旧标记的快照 / 固定数据

除非用户要求，否则不要编写新的设计文档。不要启动规划循环——机械式重构无需头脑风暴。

完成标准：陌生人 grep 旧名称时，要么没有结果，要么只找到一行指向新名称的说明。

5. 谨慎提交

• 差异中只包含你接受的盘点项目。
• 与任何无关的 WIP 分开提交。必要时使用脏工作树处理流程：备份差异 → 还原无关代码块 → 验证 git diff → 提交 → 重新应用 WIP。
• 除非用户要求按该方式落地，否则不要推送 / 同步 / 部署。
• 如果发生偏离（额外文件、额外 Agent、超出范围）：先还原，再报告。

完成标准：相较于起始状态的 git diff，每一行都能根据盘点内容说明缘由；且所修改包的项目定向检查通过（或者基线本身已出现相同失败）。

此处“干净”的标准

以下是实际需求中反复出现的模式——按这些模式处理，不要另创做法：

• 目录审查 — 删除失效命令，为其余命令添加前缀，并统一分组方式。
• 精简差异 — 删除不必要的间接层，同时保留行为覆盖。 净行数可以说明规模，但不是质量目标。
• 用库钩子替换自定义技术栈（bash-preexec、Polar SDK、供应商客户端）。
• 归并为单一负责人（一个 SessionHost、一个调度器、一个 SDK 仓库、最终保留两个仓库）。
• 删除预留配置项，不要为了“以后支持受限 API”而保留。
• 统一优先于装饰，当额外样式会增加代码量或引入错误时。
• 启发式优先于标志，当标志可能导致恢复错误时。
• 将供应商引用作为普通文件保存，让下一个 Agent 无需额外设置即可遵循 AGENTS.md。

常见陷阱

1. 按名称分组删除。 按生产名称删除 Hyperdrive 配置会导致线上 Workers 停机。务必先解析线上 ID / 绑定。
2. 通过同步清除 Missing。 这会重新创建未使用的声明。编辑 git；如果只需要查看状态，请硬刷新。
3. 相信未使用导出工具。 使用 grep。检查框架的同级依赖。检查字符串动态导入。
4. 把“清理可以了”理解成“推送到 main”。 合并代码是另一项独立请求。
5. 留下双份实现。 增量合并会统一 ManualCommitStep。之后 grep 旧名称。
6. 保留已预留但无用的 API。 它会变成误导性的分类器。切换过去。
7. AGENTS.md 做样子。 不要因为存在阻塞事项的提示，就发起用户未要求的工作。但未经授权，仍须拒绝远程变更。
8. 只规划清理。 发现 → 完成清点 → 应用。不要重新设计已批准的方案。
9. 为删除的代码留注释。 如果代码已删除，注释也应一并删除——除非它记录了不可或缺的为何不做 X。
10. 在同一个提交中混合功能和清理。 分开提交。

验证清单

• 用一句话描述的工作不包含任何功能开发
• 存在清点表；每项删除都有 grep 结果和契约结论
• 已检查 RISKY 项的线上绑定
• 对旧名称的 grep 结果为空（或指向新名称）
• 每个保留或新增的抽象都能隐藏复杂性或支持有用的复用
• 保留已配置的行数限制，并记录任何有针对性的例外
• 测试验证行为以及必需的完成 / 错误 / 清理契约
• 差异可根据清点结果解释；没有未经授权的文件
• 已运行修改包的针对性测试 / lint；仅剩预先存在的失败
• 已更新或删除被此次变更证伪的过时文档 / AGENTS.md / 菜单项
• 未按要求前未执行推送 / Sync / 部署