maintenance-routine

メンテナンスルーチンの実行

概要

ルーチンとは、スケジュールに従って実行される機械的なメンテナンス作業の1回分です。小規模でレビューしやすいPRを作成するか、該当事項がなかったと報告します。このスキルには7つのアーキタイプが含まれています。それぞれに独自の適格性テストがありますが、共通の契約に従います。

メンテナンスルーチンがあるのは、誰も時間を割けない作業、たとえばデッドコード、失敗しないテスト、レイヤー構成の逸脱、乖離していく重複コードこそ、機械的に実行するのに適した作業だからです。ただし、「該当事項なし」という結果が通常のことであり、許容されるほど、適格性の基準が十分に高いことが条件です。

このスキルが手法を提供します。パラメーターはリポジトリが提供します。 スキャン範囲、対象外のパス、検証コマンド、静的検索を妨げるフレームワーク固有の落とし穴はすべてリポジトリごとに異なり、対象リポジトリの .claude/routines.md に記載されています。この分割は意図的なものです。ルーチン自体の調整サイクルは「PRが却下される → ルーチンを調整する」であり、調整可能な部分は、ルーチンがPRを作成できるリポジトリ内に置く必要があります。

対象範囲：1回の実行につき1つのアーキタイプです。複数のアーキタイプを実行するのはスケジューラーの役割です。同じランナーを取り合わないよう、実行時刻をずらしてください。

実行方法

/cadence:maintenance-routine <archetype>

<archetype> には、以下の7つのいずれかを指定します。スケジューラーから実行する場合、プロンプト全体をこの1行にできます。

アーキタイプ	処理内容	客観性
dead-code-removal	静的検索で到達不能と証明できるコードを削除します	最高
useless-test-pruner	失敗しないテストを見つけて修正します。削除は最後の手段とします	高
abstraction-police	リポジトリに明記されたレイヤー構成のルールへの違反を修正します	高
dup-unifier	変更内容が確実に連動する重複実装を統一します	中
logic-bugfixer	仕様に照らして1つのモジュールをモデル化し、テストを先に書いて実際のバグを修正します	中
logic-simplifier	1つの関数内のロジックを整理します	低
abstraction-improver	意味のない間接化レイヤーを平坦化します	最低

客観性は、初回のマージ率を予測する指標です。新しいリポジトリでルーチンを導入する場合は、この表の上位から有効にし、先に有効にしたものが採用されてから、下位を追加してください。

スケジューラーの運用上の注意事項は、どのような方法で実行する場合にも当てはまります。詳細は対象リポジトリ独自の運用ドキュメントに記載しますが、どこでも共通する点が3つあります。

• スケジューラーでモデルを指定できる場合は、モデルを明示的に固定してください。空欄のままにするとデフォルトが引き継がれますが、デフォルトは通常、コストの高いモデルです。このような機械的な作業では割に合いません。
• 実行間で状態を引き継がないでください。 各実行は初期状態から開始し、リポジトリを読み込みます。スケジューラー側のセッションメモリは独自のスケジュールで回収されるため、前回の実行を記憶していることに依存するルーチンは、気づかないうちに最初からやり直すことになります。
• ランナーの並列実行数の上限に合わせて、スケジュールをずらしてください。同じ分に実行が重なると、順番待ちの間もワークスペースを占有し続けます。

事前確認 — スキャンを始める前に、4つのゲートすべてを通過する必要があります

1. リポジトリ設定を読み込みます。 対象リポジトリの .claude/routines.md を読みます。

存在しない場合は、停止します。コードベースから対象範囲、禁止パス、検証コマンドを推測してはいけません。推測が原因で、ルーチンがマイグレーションを編集することになります。Repo Config Schema のテンプレートを表示し、まず必要事項を記入してコミットする必要があると伝えて、実行を終了します。

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 に相当するコマンドは Forge Commands にあります。以下で「PR」とある箇所は、GitLab では MR を意味します。

4. グリーンなベースラインを確立します。 何かを変更する前に、設定に記載された検証コマンドを HEAD で実行します。

ベースラインが失敗した場合は、停止して、失敗したコマンドを報告します。修正を試みてはいけません。不要なコードを削除するために実行したルーチンが、無関係なテストまで修正して終わるのは対象範囲外です。さらに、HEAD が失敗していると、その後の「自分の変更は安全だ」という主張を検証できません。壊れた HEAD は人間が対処する問題です。

ベースラインの出力を記録します。後でこれと差分を比較します。

Routine の契約

すべてのアーキタイプは、以下のすべてを遵守します。アーキタイプファイルでは、特によく間違える項目を繰り返し記載しています。この繰り返しは意図的です。

PR は作成しても、マージはしないでください。 --auto を使う場合も、CI がグリーンの場合も、変更が些細な場合も同様です。マージは人間が判断します。これは、仕組み全体を無人で安全に実行するための唯一の不変条件です。

検出事項がなければ、PR も作成しません。 空の PR や水増しした PR は、何も報告しないより悪いものです。レビューの注意を浪費し、Routine を実行する価値があるかどうかを示すマージ率の指標も損ないます。「X 件をスキャンし、Y と Z を検討したが、どちらも条件 3 を満たさなかったため、何も作成しなかった」と報告して終了するのは、成功した実行です。ぎりぎりの候補に手を出さず、そのまま明確に伝えてください。

実行ごとの PR 上限を守ってください。 各アーキタイプファイルに、それぞれの上限（1～3）が記載されています。上限はレビュー担当者の処理量に関するもので、見つけた件数に関するものではありません。上限を超える候補は ## Observations に記載してください。

集計しやすいブランチ名を付けてください。

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

<n> は実行ごとに 1 から始まります。この命名によって、何も計測機能を追加せずにマージ率を算出できます。マージ率の集計を参照してください。別の命名規則を独自に考案しないでください。

禁止対象のパスには手を出さないでください。 設定ファイルに記載されているリストに加え、すべてのリポジトリに当てはまる次の項目も対象です。

• 仕様書と意思決定記録 — アーキテクチャ文書、ADR、ドメイン用語集、機能仕様、アーカイブ済みの変更記録。複数のアーキタイプでは、これらのファイルが作業の評価基準となる根拠です。自分の根拠を編集するのはメンテナンスではありません。ルールに誤りがあると考える場合は、## Observations に記載し、人間が判断に反映できるようにしてください。
• CI ワークフロー定義 — Routine が、自身の PR を制御するチェックを弱められる状態にしてはいけません。

プラットフォームレベルでは、これを強制する仕組みはありません。ブランチ保護と人間によるレビューが実際の防御策です。このリストは、そうした事態が起きる可能性を下げます。

ついでに気づいた問題を修正しないでください。 アーキタイプから外れた Routine が作成する差分は、明示された意図に照らしてレビューできません。テストの整理中に見つけた実際のバグ、ロジックのバグを追う途中で見つけたスキーマの問題、「ついでに」行うクリーンアップなど、すべて ## Observations に記載してください。

すべての PR 本文に ## Verification と ## Observations を含めてください。 アーキタイプファイルで、独自の必須セクションが追加される場合があります。## Verification には、成功したという主張ではなく、実際のコマンド出力を貼り付けてください。## Observations は省略できません。記載事項がない場合は none と記入してください。

PR は単一のトピックに絞り、小さく保ってください。 アーキタイプファイルで行数の上限が定められています。上限を超える場合は分割してください。「今回だけ」は認められません。

ワークフロー

1. 事前確認を行います（4 つすべてのゲート）。
2. 今回の実行対象（サブディレクトリ、モジュール、またはアーキタイプがローテーションする単位）を選びます。最近変更されていない領域を優先してください。git log --since='60 days ago' --name-only で、ツリー内のどの部分が最近変更されていないか確認できます。選択した対象とその理由を PR 本文に記載してください。
3. 候補を列挙します。
4. 各候補にアーキタイプの適格性テストを適用します。候補の大半がここで除外されます。それが意図した設計どおりの動作です。
5. 条件を満たした候補について、PR 上限まで変更を行います。
6. 検証スイート全体を実行します。ベースラインと比較してください。
7. PR を作成するか、条件を満たす候補がなかったことを報告します。

検証

設定ファイルに記載されたコマンドをそのまま実行してください。変更後にグリーンにならない候補は、デバッグして無理に提出せず、断念してください。内容を ## Observations に記載して、次に進みます。

実際の出力を ## Verification に貼り付けてください。アーキタイプで赤からグリーンへの実証（logic-bugfixer の失敗するテストや、abstraction-police の新しいリントルールなど）が必要な場合は、どちらの出力も必須です。

ツリーをクリーンな状態に保ってください。 テストのために一時的にソースを変更するアーキタイプ（useless-test-pruner、logic-simplifier）は、変更を元に戻し、続行する前に git status で確認する必要があります。変更が PR に残ると、その後に続くすべての Routine の 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>

PR の本文は --body-file -／標準入力で渡します。シェル引数で複数行の本文を渡すと、内容が崩れます。

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 の入力となります。ルーチンはライフサイクルの最初の段階であり、開始時点で人間が関与しない唯一の段階です。