maintenance-routine

运行维护例程

概述

例程是一次机械化的维护操作，按计划运行，要么创建一个规模小、易于审查的 PR，要么报告没有发现问题。本技能包含七种类型，每种都有自己的资格判定测试；但它们都遵循同一套约定。

之所以需要例程，是因为那些无人有空处理的维护工作——死代码、不会失败的测试、分层偏移、逐渐产生差异的重复代码——正是适合机械化处理的工作，前提是资格门槛足够高，让“未发现问题”成为正常且可接受的结果。

本技能提供方法，仓库提供参数。 扫描范围、禁止访问的路径、验证命令，以及会使静态搜索失效的框架陷阱，都因仓库而异，并记录在目标仓库的 .claude/routines.md 中。这种划分是有意为之：例程自身的调整循环是“PR 被拒绝 → 调整例程”，而可调整的部分必须位于例程能够针对其创建 PR 的仓库中。

范围：每次调用运行一种类型。运行多个类型是调度器的工作——应错开时间，避免它们争用同一个运行器。

调用

/cadence:maintenance-routine <archetype>

<archetype> 是以下七种类型之一。通过调度器调用时，整条提示词可以只有这一行。

类型	功能	客观性
dead-code-removal	通过静态搜索，删除可确定无法到达的代码	最高
useless-test-pruner	找出不会失败的测试；修复这些测试，仅在万不得已时才删除	高
abstraction-police	修复违反仓库已记录的分层规则的问题	高
dup-unifier	统一可确定会同步变化的重复实现	中
logic-bugfixer	根据规范分析一个模块，并先写测试再修复实际错误	中
logic-simplifier	理清单个函数内部的逻辑	低
abstraction-improver	展平不承载实际含义的间接层	最低

客观性可以预测首轮合并率。在新仓库中启用例程时，先启用此表顶部的类型，只有在它们的 PR 开始合并后，才添加下面的类型。

调度器注意事项：无论由什么触发运行，具体操作细节都应记录在目标仓库自己的运维文档中，但有三点适用于所有情况：

• 如果调度器允许指定模型，请明确指定模型。留空时会继承默认值，而默认值通常价格较高——对于这种机械化工作来说并不划算。
• 不要在运行之间保留状态。 每次运行都应从冷启动开始并读取仓库。调度器侧的会话记忆会按自身计划回收，因此依赖记住上次运行内容的例程会悄无声息地从头开始。
• 错开计划运行时间，以符合运行器施加的并发限制。同一分钟触发的任务会排队等待，并在等待期间占用各自的工作区。

预检——开始任何扫描前，四项检查都必须通过

**1. 加载仓库配置。**读取目标仓库中的 .claude/routines.md。

如果文件不存在，立即停止。不要根据代码库推断范围、禁止访问的路径或验证命令——猜测这些内容正是例行任务最终修改迁移文件的原因。打印 仓库配置架构 中的模板，说明需要先填写并提交，然后结束本次运行。

**2. 加载类型文件。**读取此文件旁边的 routines/<archetype>.md。该文件定义资格测试、工作流、PR 正文各部分以及每次运行的 PR 上限。其规则是对本文件规则的补充，绝不会放宽本文件的规则——两者不一致时，以更严格的规则为准。

**3. 检测代码托管平台。**GitHub 使用 gh，GitLab 使用 glab。检查已安装并通过身份验证的工具：

gh auth status 2>/dev/null || glab auth status 2>/dev/null

两者都没有 → 停止并报告。本技能中的示例使用 gh；glab 对应命令见 代码托管平台命令。下文中的“PR”在 GitLab 上指 MR。

**4. 确认基线通过。**在 HEAD 上运行配置中的验证命令，然后再进行任何更改。

如果基线未通过，立即停止并报告失败的命令。不要尝试修复——一项旨在删除无用代码的例行任务，最后却修复了无关的失败测试，这超出了范围；更糟的是，基线未通过会让之后任何“我的更改是安全的”这一说法都无法证伪。HEAD 损坏是人类的问题。

记录基线输出，稍后与之进行差异比较。

常规约定

每种类型都必须遵守以下所有规定。类型文件会重申最容易出错的部分；这种重复是有意的。

打开 PR，绝不合并。 不要使用 --auto，不要因为 CI 通过就合并，也不要因为改动很小就合并。合并是由人做出的决定。这是让整个机制能够安全地无人值守运行的唯一不变原则。

没有发现 → 不开 PR。 空洞或凑数的 PR 比保持沉默更糟：它会占用审核精力，还会污染合并率信号，让你无法判断是否值得运行这项例行任务。以“扫描了 X，评估了 Y 和 Z，但两者都未满足条件 3，因此未创建任何内容”收尾，是一次成功的运行。请直白说明，不要勉强找出边缘案例。

遵守每次运行的 PR 上限。 每个类型文件都会规定各自的上限（1–3）。上限针对的是审核吞吐量，而不是你发现了多少问题。超出的候选项放入 ## Observations。

按规范命名分支，便于统计。

claude/<archetype>/<YYYY-MM-DD>-<n>

<n> 在每次运行中从 1 开始。这使得无需埋点也能计算合并率——参见合并率统计。不要擅自采用其他命名方案。

避开禁止修改的路径。 配置中的列表，以及以下在每个仓库中都适用的路径：

• 规范和决策记录——架构文档、ADR、领域术语表、功能规范、归档的变更记录。对于若干类型而言，这些文件就是评判工作的准绳。修改自己的准绳不算维护。如果你认为某条规则有误，应将其写入 ## Observations，交由人类将其转化为决策。
• CI 工作流定义——例行任务不得削弱用于把关其自身 PR 的检查。

平台层面没有任何机制强制执行这些规定。分支保护和人工审核才是真正的防线；这些列表可以降低需要依赖防线的概率。

不要顺手修复偶然发现的问题。 偏离自身类型的例行任务会产生一份无法依据明确意图审核的差异。清理测试时发现的真实缺陷、追查逻辑错误时发现的架构问题、“既然都做到这儿了”就顺手做的清理——全部写入 ## Observations。

每个 PR 正文都必须包含 ## Verification 和 ## Observations。 类型文件还会添加各自要求的章节。## Verification 中粘贴实际命令输出，而不是声称验证已通过。## Observations 不得省略——没有内容时写 none。

每个 PR 只涉及一个主题，且规模要小。 类型文件会设定行数上限。超过上限就拆分，不要说“这次例外”。

工作流

1. 预检（全部四项关卡）。
2. 选定本次运行的目标——子目录、模块或类型轮换覆盖的其他单元。优先选择近期未触及的区域；git log --since='60 days ago' --name-only 可以显示代码树中哪些部分近期较少改动。在 PR 正文中说明选择及原因。
3. 列出候选项。
4. 对每项应用该类型的资格测试。这一步会淘汰大多数候选项，而且这正是设计的预期效果。
5. 对通过筛选的候选项进行修改，但数量不得超过 PR 上限。
6. 运行完整验证套件，并与基线进行比较。
7. 打开 PR，或报告没有符合条件的项。

验证

逐字运行配置中的命令。若某项候选改动未能通过验证，就放弃该项，不要调试到它通过为止——将其记录在 ## Observations 中，然后继续。

在 ## Verification 中粘贴真实输出。若某种类型要求先失败再通过的演示（logic-bugfixer 的失败测试、abstraction-police 的新 lint 规则），则必须提供前后两部分。

保持代码树干净。 会临时修改源代码来测试的类型（useless-test-pruner、logic-simplifier）必须还原修改，并在继续之前通过 git status 确认。若有修改泄漏到 PR 中，之后每个例行任务的 PR 都会因此失去可信度。

合并率统计

分支命名约定就是全部的检测机制。运行几周后：

# GitHub
gh pr list --search "head:claude/<archetype>" --state all \
  --json number,state,mergedAt,title

# GitLab
glab mr list --source-branch "claude/<archetype>" --all

某项例行任务的落地率远低于其他任务，说明其资格测试过于宽松，或者仓库配置缺少一道防线。收紧该类型任务的条件，或补充到 .claude/routines.md 中，然后让下一轮运行应用这些更改。

没有符合条件的任务时

在运行输出中报告，而不是创建 PR：

• 扫描了哪个目标，以及选择它的原因
• 考虑了哪些候选项
• 每个候选项未通过的条件

对于客观性较低的任务类型，这是最常见的结果，并不代表失败。为了凑数而创建 PR 才是失败。

Forge 命令

用途	GitHub	GitLab
创建 PR	gh pr create --head <branch> --title T --body-file -	glab mr create --source-branch <branch> --title T --description "$(cat -)"
身份验证检查	gh auth status	glab auth status
按分支列出	gh pr list --search "head:<prefix>"	glab mr list --source-branch <prefix>

通过 --body-file - / stdin 传入 PR 正文。通过 shell 参数传递多行正文会导致内容错乱。

在 GitLab 上，绝不能传入 --merge-when-pipeline-succeeds（或 --auto-merge）。这违反了绝不合并的不变量。

仓库配置架构

目标仓库中的 .claude/routines.md。这里的所有内容都按定义属于仓库专属配置——此技能对此没有任何默认值。

# Maintenance routine config

## Verification

Commands every routine runs, in order, before opening a PR. Include whatever
build step the tests depend on — a missing one produces failures that look
like the routine's fault.

```bash
<install command>
<build command, if the test run needs built artifacts>
<lint command>
<test command>
```

## Forbidden paths

| Path | Why |
|---|---|
| `<glob>` | `<reason a human can check>` |

## Spec sources

Where the written rules live. `abstraction-police` and `logic-bugfixer` use
these as their oracle; every archetype treats them as read-only.

| What | Where |
|---|---|
| Architecture constraints | `<path>` |
| Decision records | `<path>` |
| Domain glossary / state-machine invariants | `<path>` |

## Commit conventions

Anything a commit lint will reject: title format, body line length, allowed
scopes.

## Dynamic-reference traps

Constructs that look unreferenced to static search but are live: framework
convention files, glob-loaded test files, string-keyed dispatch tables,
cross-package boundaries, config that names symbols as strings, and any
deliberately-retained transitional code. Each entry: what it is, how to
recognise it, and that the routine must skip it.

## Per-routine

### <archetype>

Scan scope, rotation order, or archetype-specific exclusions. Omit an
archetype to accept the defaults in its file.

各个章节可以留空，但不应缺失——动态引用陷阱为空，意味着该仓库没有此类陷阱，这应当是经过审慎考虑的声明。

设计说明

• 资格测试就是产品。 每种任务类型的价值，在于它拒绝做什么。每次运行都创建 PR 的例行任务，说明测试有问题，而不是效率高。
• 方法在这里，参数在仓库中。 可泛化的规则放在此技能中；任何涉及路径、包管理器或内部符号的内容都属于 .claude/routines.md。可泛化的规则如果漂移到了仓库配置中，就是此技能的缺陷——应将其移回。
• 例行任务为周期流程的其余部分提供输入。 例行任务的输出是 PR，它是 pr-review 的输入，而后者又是 pr-babysit 的输入。例行任务是生命周期中最靠前的阶段，也是唯一一个开始时没有人工参与的阶段。