AIが自分自身を掃除する

AIエージェントが機能をリリースするたびにリポジトリは乱雑になっていきます。デッドコードが積み重なります。ブランチが壊れたまま放置されます。命名パターンがドリフトします。どれも劇的ではありません。ただ機能ごとに積み重なり、コードベースの変更が遅くなり、触るのが怖くなっていきます。

この記事では、それをスケジュールに従って、あなたが眠っている間に掃除してくれる清掃員チームについて説明します。3つのワークフロー。1つのスケジューラー。それぞれが異なる種類の乱雑さを受け持ち、静かに処理します。朝目覚めると、1通のメールを読み、何が掃除されたか、何が修正されたか、何にまだ人の目が必要かがわかります。

大きな問題になる3つの小さな問題

ほとんどのコードベースの問題は最初から大きくありません。しばらくの間は小さいままです。そして数機能後、小さかったものが他の3か所にコピーされ、クリーンアップが1時間ではなく1週間になります。

これらはAIが多用されるリポジトリで最もよく現れる3つです。

1. 誰も削除しないデッドコード

エージェントが機能をリリースします。1週間後にその機能の別バージョンをリリースします。古いコードはそのままです。何かがまだ使っているかどうか誰もわからないため、誰も削除しません。さらに3つの機能後、リポジトリには放棄されたヘルパーが3つ、未使用のルートが2つ、どのリンクも指していないページが1つあります。

平均的なプロジェクトでは、数ヶ月以内にデッドコードがリポジトリの約18%に成長します。それは毎回のビルドで型チェック、リント、バンドル、ロードされているコードです。コールドビルドを遅くし、新しい貢献者を混乱させ、必要以上にリファクタリングを怖くします。

問題はデッドコードを見つけることではありません。リンターでそれはできます。問題は安全に削除することです。ファイルを削除しても実際に何も壊れないことを知る必要があります。ほとんどの場合、誰も行ごとに検証する忍耐を持っていないため、デッドコードはそのままです。

2. リリースをブロックする壊れたブランチ

エージェントの実行が終わります。機能が完成したと言います。朝にブランチをプルすると、ビルドが赤です。型エラー、失敗するテスト、欠けているインポート。小さなこと。10分で修正できます。

ただしそれを週に何度も朝にやります。ここで10分、そこで20分。本当の作業を始める前の壊れた受け渡しを修正するだけで、月に2日間が消えます。そしてmainに問題が入ると、他のすべての機能がそれを待ちます。

理論上は修正は簡単です。エージェントが自分の壊れたものを修正すべきです。実際には、それはテストを実行し、エラーを読み、正しいファイルを編集し、推測で悪化させないことを意味します。それは余分な構造なしにほとんどのエージェントが単独では閉じられないループです。

3. 静かにドリフトするパターン

認証、請求、通知、検索という4つの機能があります。すべてが1つのパターンに従います。同じフォルダ構造。同じファイル名。主要な関数の同じ命名。

そして1つの機能がドリフトします。エージェントが少し異なる名前をつけます。あるいは他が1つにまとめているファイルを分割します。あるいは他がすべて共有するパターンをスキップします。単独ではそれで構いません。3つの機能後、新しいエージェントがドリフトしたものを見て、元のものではなくその形をコピーします。誰も同意しなかったフォークが自分のコードベースに生まれます。

ドリフトは3つの中で最も費用がかかる乱雑さです。デッドファイルは1回の削除で済みます。壊れたブランチは1つの朝で済みます。3つ以上の機能に伝播したドリフトは、フォルダ全体にわたる本物のリファクタリングです。

清掃員チーム

このシステムは1つの夜間スケジュールで実行される3つのClaude Codeワークフローです。それぞれが狭い仕事を持つ1つのチームと考えることができます。

1つのスケジューラーが夜に清掃員チームを起動します。各ワークフローを順に発火します。それぞれが共有ログに短いメモを書きます。最後のステップはログをメールにまとめてあなたに送ります。

何もmainに独自にリリースされません。Slop-cleanerの編集はテストの後ろにあります。/healはmainではなくサイドブランチで動作します。/driftはフラグを立てるだけで、書き直しません。朝のレポートを受け入れるか拒否するかを決める人はあなたのままです。

清掃員1: slop-cleaner

slop-cleanerの仕事は何も壊さずにデッドコードを削除することです。

コツは順序です。ほとんどのデッドコードツールはスキャンし、リストし、人間が削除するのを待ちます。誰も間違ったファイルを削除して本番を壊したくないため、それは遅いです。ワークフローは順序を逆にします。まず安全ネットを書き、次に削除し、次に安全ネットを再実行します。

ステップ1、リグレッションテストを書く。エージェントは触れようとしているファイルを確認し、まだ呼び出し元があるものそれぞれに小さなテストを書きます。目標は完全なカバレッジではありません。目標は「重要な部分はまだ機能している」というグリーンシグナルです。これらのテストはサイドブランチにコミットされるため、人間が読めます。

ステップ2、デッドコードを削除する。エージェントは静的チェックを使って候補をリストします。インバウンドインポートがゼロのファイル、呼び出されない関数、リンクのないルート、参照されない型。それらを小さなバッチで削除します。

ステップ3、テストを再実行する。すべてのテストがまだグリーンであれば、削除は有効です。テストが赤になれば、それを引き起こした特定の削除が取り消されます。エージェントはテストを「修正」しようとしません。削除が間違っていると想定してロールバックします。微妙なことはしません。

結果として、通常の恐れなくリポジトリが軽くなります。1回の夜間実行で、清掃員チームは中規模SaaSから412行のデッドコードを削除しました。テストは壊れませんでした。ページはレンダリングを止めませんでした。翌朝レビュアーはdiffをざっと確認し、承認をクリックして先に進みました。

slop-cleanerはテスト安全ネットが誠実な場合にのみ機能します。エージェントが常に合格する偽のテストを書くと、パターン全体が崩れます。ワークフローは1つのルールを強制します。すべてのテストは実際の関数を呼び出し、実際の出力をアサートしなければなりません。テスト対象のファイルをインポートしないテストは拒否されます。

清掃員2: /heal

/healの仕事は、壊れたコードをmainに置かずに壊れたブランチを修正することです。

/healが起動すると、最近の機能ブランチのリストを読みます。それぞれについて、ビルド、型チェック、テストスイートを実行します。ブランチが赤であれば、/healは作業を開始します。

重要な詳細: /healはオリジナルではなくサイドブランチで作業します。壊れたブランチをheal/feature-nameのようなものにコピーし、そこで編集し、オリジナルはそのままにします。mainは常にきれいなままです。元の作者は依然として修正の決定を所有します。

修正ループはタイトです。/healは最初の失敗チェックを読み、1つの質問をします。この特定のチェックに合格させるための変更は何か? 最小の表面を編集し、チェックを再実行し、次の失敗に移ります。リファクタリングしません。改善しません。赤いシグナルを閉じるだけです。

ループの後、/healはすべてを再実行します。すべてのチェックに合格すれば、ゼロから百のスケールで自分の信頼度をスコアリングします。スコアは単純なシグナルに基づいています。修正がテストファイルに触れたかソースファイルに触れたか、何行変更されたか、エラーが明確で狭かったかあいまいで広かったか、同じテストが合格する前に2回続けて失敗したか。

次に/healは短い判定を書いてメールします。判定にはブランチ名、信頼スコア、変更された正確なファイル、1行の理由が含まれます。92%信頼度、2ファイル触れた、ハンドラーに欠けているインポート。そのような内容です。

人間は依然としてマージするかどうかを決定します。タイトなdiffを伴う高信頼度は通常イエスを得ます。低信頼度または広いdiffはより詳しく確認されます。ポイントは人間のレビューを排除することではありません。ポイントは人間が生の赤いブランチではなくきれいで狭い修正をレビューしていることを確認することです。

清掃員3: /drift

/driftの仕事は、広がる前に最近の機能全体のパターン分岐を捉えることです。

/driftが起動すると、コードベースのパターンマップを構築します。小さな機能のセット（通常は最後の5〜10）を選択し、それぞれの形を記録します。フォルダレイアウト、ファイル名、関数名、インポートスタイル、テストの場所。これは単純なスナップショットで、深い分析ではありません。

次に比較します。4つの機能が同じ形を持ち、1つの機能が少し異なる場合、その1つが外れ値です。/driftは外れ値を書き直しません。フラグを立てます。

フラグはこのようなものです。「notifyはsendNotificationを使用していますが、auth、billing、searchはsendEmailを使用しています。命名のドリフト。さらに3つの機能がそれをコピーした後は4倍のコストで修正が必要です。」それは行動できるほど具体的で、最終的な判断を人間に残すほど漠然としています。

修正ではなくフラグを立てる理由は何か。なぜならドリフトは常に間違いではないからです。外れ値が正しい呼び出しで他の4つがレガシーであることもあります。人間はどちらがどちかを判断できます。エージェントはできません。なぜならルールは意図に基づいて変わるからです。だから/driftはエージェントが得意なこと（パターンを発見する）をして、判断をあなたに任せます。

重要な窓は早いです。/driftが3つの機能がパターンをコピーする前にnotifyのドリフトを捉えれば、修正は1ファイルです。後に捉えれば、修正は4ファイルとチーム全体の調整です。「4倍のコスト」という数字はそこから来ています。

1つの夜、1つのスケジュール

スケジューラーはシンプルです。1つのトリガー、1つのcron形式のエントリが毎晩設定された時間に発火します。

発火すると、新しいClaude Codeセッションが開始します。オーケストレーターはリポジトリの現在の状態を読み取り、3つのワークフローを順に実行します。slop-cleaner、次に/heal、次に/drift。それぞれが./overnight.logの共有ログに短いメモを書きます。

順序は重要です。slop-cleanerが最初に実行されるのはレビュー中のコードを縮小するからです。/healが2番目に実行されるのは現在壊れているものを修正するからです。/driftが最後に実行されるのは、他の2つが作業を終えた後の最もきれいなバージョンのリポジトリを読むからです。

各清掃員には時間予算があります。長くかかりすぎると、そのステップでワークフローは終了して次に移ります。ポイントは完璧な夜間実行ではなく、予測可能な朝のメールです。未完了の作業はフラグが立てられ翌夜に引き継がれます。

このセットアップはクラウドプラットフォームを必要としません。マシンの本物のcrontabエントリで機能します。Claude Code Desktopのスケジュールタスクで機能します。選択は操作上のものであり、アーキテクチャ上のものではありません。重要なのはトリガーが発火し、新しいセッションが起動し、オーケストレーターがどこから始めるかを知ることです。

朝のレポート

夜間実行の最後のステップはログをメールにまとめて送ります。形式は短く、スキャン可能で、「何も必要ない」から「レビューが必要」の順で並んでいます。

実際の朝のログはこのようなものです。

overnight.log - janitor crew
01:00  Slop-cleaner swept the repo
       412 dead lines removed. Tests green.

02:30  /heal rescued a broken branch
       Fixed on side branch. 92% confidence.

04:00  /drift caught a naming gap
       1 file out of pattern. Flagged.

07:00  Verdict emailed to you
       3 cleanups ready for review.

コーヒーを飲みながら読みます。最大4分。各行には時間、短い結果、清掃員がどれだけ自信があるかを示す1つの数字があります。高信頼度のクリーンアップは通常その場で承認されます。フラグが立てられたドリフトはざっと確認され、修正されるか「それは意図的なもの、そのままで」になります。

メールの形が重要です。短い。具体的。順序立てられている。散文の要約なし。「エージェントは今夜一生懸命働いた」という埋め草なし。何が変わったか、清掃員がどれくらい確信しているか、何をすべきかを知りたいのです。それ以外は何も。

自分のバージョンを構築する方法

利点を得るために完全なスタックは不要です。パターンはシンプルです。この形から始めて拡張します。

3つの小さなワークフローを書きます。狭く保ちます。slop-cleanerはテストが合格した場合にのみデッドコードを削除します。/healはサイドブランチでのみ壊れたブランチを修正します。/driftは最近の機能のパターン分岐にのみフラグを立てます。それぞれに単一の仕事と単一の出力形式があります。

1つのスケジューラーの後ろに置きます。Cronで十分。スケジュールされたClaude Codeセッションで十分。ジョブキューやメッセージバスは不要です。設定された時間にチームを起動する1つのpingが必要です。

削除の前に毎回リグレッションテストを書きます。これがslop-cleanerを安全にするルールです。エージェントが削除したいファイルの誠実なテストを書けなければ、削除は起きません。この単一のルールがワークフロー全体の価値があります。

/healをサイドブランチに置き続けます。mainは常にきれいでなければなりません。/healの修正が間違いであれば、サイドブランチは捨てられ、オリジナルの壊れたブランチは依然として人間を待っています。mainで驚くことは決してありません。

/driftにフラグを立てさせ、修正させません。これが保つのが最も難しいルールです。エージェントはコードを見たとき「改善」したがります。ドリフトではそれは間違った動きです。問題があるように見えるパターンは意図的かもしれません。エージェントの仕事はそれを表面化して止めることです。人間の仕事はパターンが今後どうあるべきかを決定することです。

すべての実行を短い構造化されたメールで終わらせます。時間、結果、数字、1行の理由。それ以外は何も。5分以内にメール全体をスキャンできなければ、清掃員は1晩に多すぎる作業をしています。分割します。

このパターンが他にどこで適用できるか

コードで清掃員チームが動いたら、同じ形が他の種類の緩やかに燃える乱雑さにも機能します。

コンテンツ清掃員。古いブログ投稿を掃除し、古いセクションをフラグ立てし、著者にメモを書くワークフロー。書き直しません。フラグを立てます。

アナリティクス清掃員。製品全体のイベント命名のドリフトを確認し、外れ値をフラグ立てし、標準リストを提案するワークフロー。/driftと同じパターンマップ、異なる入力。

依存関係清掃員。未使用パッケージをスキャンし、アクティブなもの各々をインポートするテストを書き、テストがまだ合格すれば残りを削除するワークフロー。slop-cleanerと同じ安全ネット、package.jsonに適用。

核心的なアイデアは「AIがコードをきれいにする」ではありません。「小さな乱雑さはスケジュールに従って、安全ネットの後ろで、5分で読める形式で処理される」です。それはコード、コンテンツ、アナリティクス、そして大きなリリースの間に静かに積み重なるものすべてに機能します。

1つのチーム。1つのスケジュール。3つの狭い仕事。朝にはきれいなリポジトリと、あなたの時間を尊重するメール。それがシステム全体です。