keep-codebase-maintainable

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Keep a Codebase Maintainable

保持代码库可维护性

A maintainability job is not a feature with extra polish. The deliverable is a smaller, truer tree: unused gone, twins collapsed, names honest, docs matching code, diff containing only the ask.

Mined from Cooper's OMP Hindsight bank (how he actually prompts coding agents). Source instances:

references/instances.md

(copy also at

/var/lib/hermes/workspace/omp-maintainability-asks.md

Core principle: Keep the requested scope. Follow codebase-design for shared readability rules and examples. Remove abstractions that only forward calls; retain ones that hide complexity, enforce invariants, or translate an external interface.

可维护性工作不是经过额外打磨的功能。交付物是一棵更精简、更真实的代码树：无用代码已清除，重复项已合并，命名准确，文档与代码一致，diff 仅包含请求的内容。

提炼自 Cooper 的 OMP Hindsight 库（他实际给编码 Agent 下发提示的方式）。源实例见：

references/instances.md

（副本也位于

/var/lib/hermes/workspace/omp-maintainability-asks.md

）。

核心原则： 限定在请求的范围内。通用的可读性规则和示例请遵循 codebase-design。移除仅用于转发调用的抽象；保留能够隐藏复杂度、强制约束不变量或转换外部接口的抽象。

When to Use

何时使用

Load this when the user (or the task) sounds like any of:

clean up / tidy / prune / hygiene / leftover / dead / unused
simplify / trim the diff / surgical / no tangents
audit, repair, and reorganize
rename / consolidate / disentangle / one package / short names
"don't add", "no new services", "stop coding", "out of scope"
comment the why / docs are stale / fix AGENTS.md
keep it maintainable / reduce maintenance / cohesion

Don't use for: implementing a requested feature, fixing a failing behavior, or a post-feature pass over your own just-written diff — use the repository's review guidance for that pass.

If the user mixes "add X and also clean Y", split the commits. This skill owns Y.

当用户（或任务）听起来像以下任何一种情况时加载本技能：

清理 / 整理 / 删减 / 代码卫生 / 遗留项 / 死代码 / 未使用
简化 / 精简 diff / 精准修改 / 不跑题
审计、修复和重组
重命名 / 合并 / 解耦 / 单一包 / 短名称
「不要添加」、「不要新服务」、「停止编码」、「超出范围」
注释原因 / 文档过时 / 修复 AGENTS.md
保持可维护性 / 减少维护成本 / 提升内聚性

不适用场景： 实现请求的功能、修复故障行为，或是对你自己刚提交的 diff 做功能完成后的检查——这类检查请使用仓库的评审指南。

如果用户的需求混合了「添加 X 功能」和「清理 Y 代码」，请拆分提交。本技能负责 Y 部分。

Standing Rules

常设规则

These override default "helpful agent" instincts.

Deletion test. A symbol/file/package/dep/flag/scope dies if it has zero real importers and is not a public contract (exported API, framework peer, Helm value a live app still declares). Grep the name. Then grep the old name.
```
knip
```
/
```
ts-prune
```
/
```
depcheck
```
are hints, not proof — they flag framework peers and dynamic imports.
Don't recreate the dead. Removing a stale git declaration is the fix. Syncing / applying / resurrecting the resource to "clear Missing" is the bug. Same for reserved-for-later knobs: clean cutover, not a tombstone comment.
One owner, one name. Twins drift (two schedulers,
```
menu
```
vs
```
x
```
,
```
ManualCommitStep
```
leftover after a unify). After a collapse, grep the retired name and delete the twin.
Native over custom. Use the library when it supplies the needed capability. Keep a local adapter when it owns decoding, errors, resource lifetime, or a simpler complete operation; delete wrappers that only rename a call.
Short honest names. Name the owning capability, such as
```
@repo/billing
```
; avoid a shared
```
utils
```
dumping ground. Within an owner, use familiar role directories. Public docs use the canonical surface (
```
x
```
), never the legacy alias.
Package = unit of cohesion. Expose complete operations through explicit public entries; keep implementation under
```
src/
```
, grouped by owner then role. Keep related SQL and helpers with their adapter. Tests exercise observable behavior through the interface and follow repository placement conventions.
Surgical diff. Stage specific paths. Never
```
git add -A
```
. One concern per commit. Revert unauthorized extras without arguing. "Cleanup approved" is not "land on main."
Live user instruction beats advisory AGENTS.md. Binders about commits/pushes still apply to remote mutations. They do not authorize you to spawn extra agents or expand scope.
Comment the why. Design intent, invariants, edge-case rationale. No
```
// increment counter
```
. Stale docs are a contract bug — update or delete.
Stop means stop. "Stop all coding." "Don't modify production auto/flash." Honor scope locks immediately.

这些规则凌驾于默认的「有帮助的 Agent」直觉之上。

删除测试。 如果一个符号/文件/包/依赖/标志位/作用域没有任何真实导入者且不是公共契约（导出的 API、框架对等依赖、线上应用仍在声明的 Helm 值），则可以删除。先 grep 名称，再 grep 旧名称。
```
knip
```
/
```
ts-prune
```
/
```
depcheck
```
的结果只是提示，不是证据——它们会误报框架对等依赖和动态导入。
不要复活死代码。 移除过时的 git 声明才是正确的修复方式。为了「消除 Missing 报错」而同步/应用/复活资源是错误的做法。那些「留待后用」的开关也是如此：直接干净地切换，不要留下墓碑注释。
一个归属，一个名称。 重复项会产生偏差（比如两个调度器、
```
menu
```
和
```
x
```
并存、合并后遗留的
```
ManualCommitStep
```
）。合并完成后，grep 已废弃的名称并删除重复项。
原生优先于自定义。 如果库已经提供了所需的能力，直接使用库。当本地适配器负责解码、错误处理、资源生命周期管理或提供更简单的完整操作时，保留本地适配器；删除仅用于重命名调用的包装器。
简短准确的命名。 以归属的能力命名，比如
```
@repo/billing
```
；避免使用共享的
```
utils
```
垃圾场。在同一归属下，使用常见的角色目录。公共文档使用规范对外接口（
```
x
```
），绝不使用遗留别名。
包 = 内聚单元。 通过显式的公共入口暴露完整操作；将实现代码放在
```
src/
```
目录下，按归属再按角色分组。将相关的 SQL 和辅助函数与其适配器放在一起。测试通过接口验证可观测行为，并遵循仓库的放置约定。
精准 diff。 暂存指定路径的文件。绝对不要使用
```
git add -A
```
。每个提交只处理一个关注点。无需争论，直接回滚未授权的额外修改。「清理已批准」不等于「可以合并到 main 分支」。
用户实时指令优先于 AGENTS.md 的建议。 关于提交/推送的约束规则仍然适用于远程变更。它们不会授权你生成额外的 Agent 或扩大范围。
注释要说明原因。 注释设计意图、不变量、边界情况的处理逻辑。不要写
```
// increment counter
```
这种没用的注释。过时的文档是契约缺陷——要么更新，要么删除。
停止就是停止。 「停止所有编码工作。」「不要修改生产环境的 auto/flash。」立即遵守范围锁定要求。

Process

流程

1. Name the job

1. 定义任务

Write one sentence: what gets smaller or truer, and what is out of scope.

Done when: the sentence has no feature in it. If it does, this is the wrong skill.

用一句话描述：哪些内容会被精简或修正，以及哪些内容不在范围内。

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

2. Inventory before you touch

2. 动手前先盘点

Build a list of candidates. Do not delete yet.

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

Search, in this order:

unused files / exports / deps / flags / Slack scopes / Helm leftovers
leftover twins from an incomplete unify (old name still present)
stale comments, READMEs, AGENTS.md pins that contradict lockfiles
commands / aliases still advertising a retired surface
"reserved for later" knobs and unused error variants
temp artifacts (
```
/tmp/*
```
, worktrees, stale tags, merged branches)

Done when: every candidate has a grep result (including "zero hits") and a contract verdict. Live-consumer check is mandatory for anything that can take production down (bindings, PVCs, Hyperdrive, DNS, secrets).

列出候选清理项。先不要删除。

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

按以下顺序搜索：

未使用的文件 / 导出项 / 依赖 / 标志位 / Slack 权限范围 / Helm 遗留项
未完成的合并遗留的重复项（旧名称仍然存在）
过时的注释、README、与锁文件矛盾的 AGENTS.md 固定说明
仍在宣传已废弃接口的命令 / 别名
「留待后用」的开关和未使用的错误变体
临时产物（
```
/tmp/*
```
、工作树、过时的标签、已合并的分支）

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

3. Apply in risk order

3. 按风险等级执行

Tier	Examples	Action
SAFE	unused import, leftover `/tmp` , commented-out block, duplicate config section from a failed edit	Delete now.
CAREFUL	unused file with no importers, dep with no app import, rename to the short name, collapse a twin helper	Delete/rename, then run the targeted test/lint for that package.
RISKY	anything with a live binding, public export, Helm/Argo resource, secret, peer dependency, "zero knip hits"	Verify live consumers. If any exist, stop and say so. Never delete by name-group.

Do not add speculative flags, services, or abstractions. A cleanup may introduce a local helper or coherent module when it demonstrably improves understanding within the authorized scope. Extraction must hide complexity or enable useful reuse. Retain configured line limits; document targeted exceptions instead of splitting into forwarding files to satisfy a number.

Done when: every SAFE/CAREFUL item is applied or explicitly skipped with a reason, and no RISKY item was applied without a live-consumer check.

等级	示例	操作
安全	未使用的导入、遗留的 `/tmp` 文件、被注释掉的代码块、编辑失败导致的重复配置段	立即删除。
谨慎	无导入者的未使用文件、无应用导入的依赖、重命名为简短名称、合并重复的辅助函数	删除/重命名，然后运行该包的针对性测试/ lint 检查。
高风险	任何有活跃绑定的内容、公共导出、Helm/Argo 资源、密钥、对等依赖、「knip 零匹配」的内容	验证是否有活跃的消费者。如果有，停止操作并告知用户。绝不要按名称组批量删除。

不要添加推测性的标志位、服务或抽象。如果清理过程中引入本地辅助函数或内聚模块能明显提升授权范围内的代码可读性，则可以添加。提取的模块必须能隐藏复杂度或实现有用的复用。保留配置的行数限制；对需要例外的地方做专门说明，而不是为了凑行数拆分成多个转发文件。

完成标准：所有「安全」/「谨慎」等级的项都已执行，或已明确跳过并说明原因；所有「高风险」等级的项都经过了活跃消费者检查，否则不得执行。

4. Keep the contract true

4. 保持契约一致性

In the same change-set, only if they are now false:

AGENTS.md / README claims (versions, who posts reviews, where creds live)
comments that describe a path you just deleted
public command catalogue /
```
x
```
menu entries that point at removed scripts
snapshot / fixture leftovers that still use the old marker

Do not write new design docs unless the user asked. Do not start a planning loop — mechanical refactors skip brainstorming.

Done when: a stranger grepping the old name finds either nothing, or a one-line pointer to the new name.

在同一个变更集中，仅当以下内容现在已不成立时才修改：

AGENTS.md / README 中的声明（版本、评审负责人、凭证存放位置）
描述你刚删除的路径的注释
指向已删除脚本的公共命令目录 /
```
x
```
菜单项
仍在使用旧标记的快照 / fixture 遗留项

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

完成标准：一个不熟悉代码库的人 grep 旧名称时，要么找不到任何结果，要么能看到一行指向新名称的说明。

5. Land narrowly

5. 精简落地

Diff contains only the inventory items you accepted.
Separate commit from any unrelated WIP. Use the dirty-worktree recipe if needed: backup diff → revert unrelated hunks → verify
```
git diff
```
→ commit → re-apply WIP.
Do not push / Sync / deploy unless the user asked for that land path.
If you drifted (extra files, extra agents, extra scope): revert first, then report.

Done when:

git diff

against the starting point is explainable line-by-line from the inventory, and the project's targeted check for touched packages is green (or the baseline already failed the same way).

Diff 仅包含你确认的盘点项。
与任何不相关的 WIP 分开提交。如有需要，使用脏工作树处理方案：备份 diff → 回滚不相关的代码块 → 验证
```
git diff
```
→ 提交 → 重新应用 WIP。
除非用户要求该落地路径，否则不要执行 push / Sync / deploy 操作。
如果你超出了范围（额外的文件、额外的 Agent、额外的范围）：先回滚，再报告。

完成标准：相对于起始点的

git diff

每一行都能通过盘点项解释清楚，且项目对被修改包的针对性检查是通过的（或者基线本来就有同样的失败）。

What "clean" looks like here

这里的「干净」是什么样的

Recurring shapes from real asks — match these, don't invent new ones:

Catalogue audit — remove broken commands, prefix the rest, one grouping scheme.
Diff diet — unnecessary indirection removed; behavior coverage preserved. Net line count is evidence about size, not a quality target.
Replace a custom stack with the library hook (bash-preexec, Polar SDK, vendor client).
Collapse to one owner (one SessionHost, one scheduler, one SDK repo, two-repo end state).
Delete the reserved knob rather than keep it "for the bounded API later."
Uniform over decorative when the extra style costs code or bugs.
Heuristic over flag when the flag would become a recovery bug.
Vendor references as plain files so the next agent can follow AGENTS.md without extra setup.

真实需求中反复出现的模式——遵循这些模式，不要发明新的：

目录审计 —— 移除失效命令，为其余命令添加前缀，使用统一的分组方案。
Diff 瘦身 —— 移除不必要的间接层；保留行为覆盖率。净行数是规模的参考，不是质量目标。
用库的钩子替换自定义栈（bash-preexec、Polar SDK、厂商客户端）。
合并到单一归属（一个 SessionHost、一个调度器、一个 SDK 仓库，最终两仓库状态）。
删除预留开关，而不是为了「以后做受限 API」而保留。
统一优先于装饰 —— 当额外的风格会增加代码量或引入 bug 时。
启发式优先于标志位 —— 当标志位可能成为恢复故障的隐患时。
将厂商引用作为普通文件存放 —— 这样下一个 Agent 无需额外设置就能遵循 AGENTS.md。

Common Pitfalls

常见陷阱

Deleting by name group. Hyperdrive configs deleted by production name took down live Workers. Always resolve the live ID / binding first.
Syncing to clear Missing. Recreates the unused claim. Edit git; hard-refresh if you only need status.
Trusting unused-export tools. Grep. Check framework peers. Check string-dynamic imports.
Hearing "cleanup OK" as "push to main." Land path is a separate ask.
Leaving the twin. Incremental unifies leave
```
ManualCommitStep
```
. Grep the old name after.
Keeping reserved dead API. It becomes a lying classifier. Cut over.
AGENTS.md theater. Don't spawn work the user didn't ask for because a blocker advisory exists. Do still refuse remote mutations without authority.
Planning the cleanup. Discovery → do the inventory → apply. No redesign of an approved shape.
Commenting the deletion. If the code is gone, the comment goes too — unless it records a load-bearing why we don't do X.
Mixing feature and cleanup in one commit. Split.

按名称组批量删除。 按生产名称删除 Hyperdrive 配置曾导致线上 Workers 宕机。务必先确认活跃的 ID / 绑定。
为消除 Missing 报错而同步。 这会重新创建未使用的声明。直接修改 git 配置；如果你只需要状态，执行硬刷新即可。
轻信未使用导出检测工具。 一定要 grep。检查框架对等依赖。检查字符串形式的动态导入。
把「清理没问题」当成「可以推送到 main 分支」。 落地路径是单独的需求。
遗留重复项。 增量合并会留下
```
ManualCommitStep
```
这类重复项。合并后一定要 grep 旧名称。
保留预留的死 API。 它会变成一个误导性的分类器。直接切换掉。
AGENTS.md 形式主义。 不要因为存在阻塞性建议就去做用户没要求的工作。但在没有授权的情况下，仍要拒绝远程变更。
过度规划清理工作。 发现问题 → 盘点 → 执行。不要重新设计已经批准的模式。
给删除的代码写注释。 如果代码已经删掉了，对应的注释也要删掉——除非它记录了一个关键的我们为什么不做 X的原因。
把功能和清理混在一个提交里。 一定要拆分。