architectural-refactor

アーキテクチャのリファクタリング

アーキテクチャに関する推奨事項を、何も壊さずに実現します。

コーディングエージェントは局所的な変更は得意ですが、長時間のセッションやコンテキストの圧縮、複数セッションにまたがる作業で、アーキテクチャの一貫性を維持するのは苦手です。このスキルでは、計画をディスクに外部化し、マニフェストで進捗を追跡し、各チャンクの間に検証ゲートを設けることで、この問題を解決します。エージェントがコンテキストを完全に失っても、中断した箇所から正確に作業を再開できます。

中核となる仕組み

このアプローチは、コンテキスト内ではなくディスク上に保存される次の3つのファイルを基盤としています。

1. refactor-plan.md — 評価結果に基づいて作成する、具体的で順序付けられた計画です。各チャンクには、明確な開始条件、手順、完了条件を定めます。
2. refactor-manifest.json — 機械可読な進捗トラッカーです。完了した作業、次の作業、失敗した作業、検証結果を記録します。
3. refactor-log.md — 何が起きたのか、その理由は何かを追記していく、人が読めるログです。どのエージェント（または人間）も履歴を把握できます。

これらのファイルが信頼できる唯一の情報源です。記憶でも、会話でもありません。ファイルです。

フェーズ1：評価内容を取り込む

ユーザーが提供した評価ドキュメントを読みます。Markdown ファイル、seam-ripper の出力、simplicity audit の結果、または推奨事項を含む構造化された分析などが該当します。

評価内容から、次の項目を抽出します。

• 変更が必要な点 — 特定された具体的な問題
• 目標とするアーキテクチャ — 実現すべき最終状態
• 順序に関する制約 — 変更間の依存関係（例：「Y を Z から切り離すには、先にモジュール X を抽出する」）

評価内容が曖昧、または重要な詳細が不足している場合は、作業を止めて確認してください。曖昧な推奨事項に基づいて作成したリファクタリング計画は、意図から逸れてしまいます。それこそ、まさに防ごうとしていることです。

フェーズ2：計画を作成する

評価内容を、具体的で順序付けられたチャンクの列に変換します。各チャンクは、コードベースをある有効な状態から別の有効な状態へ移行させる、自己完結したリファクタリング単位です。

チャンクの境界の決め方

チャンクは次の条件を満たす必要があります。

• 単独で検証できる — 完了後にテスト、型チェック、リンターを実行し、問題がないことを確認できます
• 単独でコミットできる — 明確なコミットメッセージを付けて、1つのコミットとして成立します
• 全体を把握できる程度に小さい — 15個のファイルを同時に理解する必要がある場合は、さらに分割します
• 意味のある作業になる程度に大きい — インポートを1つ移動するだけではチャンクになりません。モジュールの抽出などが該当します

適切なチャンクの例：

• 関連する関数や型のまとまりを、新しいモジュールに抽出する
• モジュール A の責務をモジュール B に移し、すべての参照を更新する
• 抽象化を、よりシンプルな代替手段に置き換える
• 依存関係の方向を逆転させる
• 複数のファイルや抽象化を1つにまとめる
• 評価で特定された不要なコードを削除する

不適切なチャンクの例：

• 「認証システムをリファクタリングする」（曖昧すぎます。具体的に何をするのかが不明です）
• 「42行目の変数名を変更する」（細かすぎます。関連する変更をまとめてください）
• 「すべてを再構成する」（単独で検証できません）

依存関係の分析

チャンクを並べ替える前に、各チャンクがどのチャンクに依存するのかを整理します。

• チャンク B が、チャンク A で作成するモジュールにコードを移しますか？ → A を B より先に実行します
• チャンク C が、チャンク D の変更で不要になることを前提としている抽象化を削除しますか？ → C を D より先に実行します
• チャンク E と F は独立していますか？ → 順序は問いません（ただし、一貫性のためにどちらかを先にします）

チャンク間に循環依存が見つかった場合は、チャンクの境界が適切ではありません。依存グラフが DAG（有向非巡回グラフ。つまり循環依存がないグラフ）になるまで、チャンクを分割し直してください。

計画を記述する

プロジェクトのルート（またはユーザーが希望する場所）に refactor-plan.md を作成します。

# Refactoring Plan

**Source:** [link/path to assessment document]
**Created:** [date]
**Target:** [one-sentence description of desired end state]

## Pre-flight Checks
- [ ] All tests pass before starting
- [ ] No uncommitted changes
- [ ] Working branch created

## Chunk 1: [Descriptive Name]
**Why:** [Which assessment finding this addresses]
**Entry criteria:** All tests pass, no prior chunks pending
**Steps:**
1. [Concrete action — e.g., "Create `src/auth/tokens.ts` with the TokenService class"]
2. [Next action — e.g., "Move `generateToken()` and `validateToken()` from `src/core/utils.ts`"]
3. [Continue — e.g., "Update imports in `src/api/middleware.ts` and `src/api/routes/login.ts`"]
4. [e.g., "Remove the now-empty token section from `src/core/utils.ts`"]
**Exit criteria:** All tests pass, types check, lint clean
**Commit message:** `refactor: extract token management into dedicated auth module`

## Chunk 2: [Descriptive Name]
**Depends on:** Chunk 1
**Why:** [...]
**Entry criteria:** Chunk 1 complete and verified
**Steps:**
1. [...]
**Exit criteria:** All tests pass, types check, lint clean
**Commit message:** `refactor: ...`

[...continue for all chunks...]

## Post-flight Checks
- [ ] Full test suite passes
- [ ] No TODO/FIXME markers left from refactoring
- [ ] Assessment findings are resolved

各チャンクの手順は、事前知識がまったくないエージェントでも、機械的に実行できるほど具体的に記述します。「必要に応じて再構成する」ではなく、ファイルパス、関数名、具体的な移動先などを記載してください。

マニフェストを初期化する

refactor-manifest.json を作成します。

{
  "plan_file": "refactor-plan.md",
  "assessment_source": "[path to assessment]",
  "created": "[ISO date]",
  "total_chunks": 5,
  "current_chunk": 0,
  "status": "ready",
  "preflight_passed": false,
  "chunks": [
    {
      "id": 1,
      "name": "Extract token management",
      "status": "pending",
      "depends_on": [],
      "verification": null,
      "commit_sha": null,
      "started_at": null,
      "completed_at": null
    },
    {
      "id": 2,
      "name": "Decouple auth from core",
      "status": "pending",
      "depends_on": [1],
      "verification": null,
      "commit_sha": null,
      "started_at": null,
      "completed_at": null
    }
  ]
}

ユーザーの承認を得る

何かを実行する前に、計画をユーザーに提示します。次の点を確認してもらいます。

• チャンクが適切で、評価の推奨事項を網羅している
• 順序が正しい
• 重要な項目が抜けていない
• チャンクの粒度が適切である

ユーザーが変更を希望する場合は、作業を進める前に計画とマニフェストを更新します。

フェーズ 3：実行

ここがメインのループです。厳密に定めているのは、厳密さによって逸脱を防げるからです。

セッションの開始時（またはコンテキスト圧縮後の再開時）

作業を始めるたびに――初回でも、コンテキスト圧縮後や新しいセッションで再開するときでも――次の手順を実行します。

1. refactor-manifest.json を読む — 現在の進捗を確認します
2. refactor-plan.md を読む — 現在のチャンクを把握します
3. refactor-log.md を読む — 直近の作業内容を把握します
4. 現在の状態を検証する — 検証スイートを実行して、コードベースが正常な状態であることを確認します

所要時間は 30 秒です。これにより、エージェントの逸脱の最大の原因である、古い情報や思い込みに基づいて作業を始めることを防げます。

チャンク実行ループ

FOR each chunk (in order):

  1. READ the chunk from refactor-plan.md
  2. CHECK entry criteria
     - Dependencies met? (check manifest)
     - Tests passing? (run them)
     - If not: STOP. Fix or escalate to user.

  3. UPDATE manifest: chunk status → "in_progress"
  4. LOG: "Starting chunk N: [name]"

  5. EXECUTE each step in the chunk sequentially
     - Follow the plan literally
     - If a step can't be done as written: STOP
       → Log what went wrong
       → Update manifest with the blocker
       → Ask the user how to proceed
       → Do NOT improvise a workaround

  6. VERIFY (the gate)
     - Run the full test suite
     - Run type checking
     - Run linter
     - If ANY verification fails:
       → Fix the issue (if it's clearly caused by this chunk's changes)
       → Re-verify
       → If you can't fix it in 2 attempts: STOP
         → Revert the chunk (git checkout/restore)
         → Log the failure
         → Update manifest: chunk status → "failed"
         → Ask the user

  7. COMMIT
     - Stage only the files changed in this chunk
     - Use the commit message from the plan
     - Record the commit SHA in the manifest

  8. UPDATE manifest: chunk status → "completed"
  9. LOG: "Completed chunk N. Verification: [pass/fail details]"

  10. Proceed to next chunk

「STOP」の意味

スキルに STOP と書かれている場合、次のチャンクに進んだり、独自の回避策を試したり、「修正して先に進む」ことはしないでください。このスキルの目的は、計画から逸脱すると、そもそもリファクタリングが必要になった原因である混乱にコードベースが陥ることを防ぐことです。

作業を停止したら、次の手順を実行します。

1. 現在の状態でマニフェストを更新します
2. 起きたことを明確に説明するログエントリーを記録します
3. 何が問題だったのか、どのような判断が必要なのかをユーザーに正確に伝えます

ユーザーから「このチャンクはスキップして」「計画を変更して」「このように対処して」と言われるかもしれません。いずれも問題ありません。判断するのはエージェントではなく、ユーザーです。

逸脱の兆候への対処

計画から逸脱している兆候に注意してください。

• 現在のチャンクの手順に記載されていないファイルを編集している
• 計画にない、気づいた問題も「ついでに修正」している
• 「こちらのほうが理にかなっているから」と手順の順序を入れ替えている
• 「もう必要ないから」と手順を省略している

いずれかに該当する場合は、STOP して計画を読み直します。計画に本当に誤りがある場合は、ユーザーの承認を得てから計画とマニフェストを更新します。黙って逸脱しないでください。

フェーズ 4：作業後の確認

すべてのチャンクが完了したら、次の手順を実行します。

1. 最後に検証スイート全体を実行します
2. リファクタリングログを確認し、異常がないか調べます
3. 最終状態を評価の目標アーキテクチャと比較します
4. マニフェストを更新します：status → "completed"
5. 次の内容をユーザーに報告します。
   • 正常に完了したチャンク
   • スキップまたは変更したチャンク
   • 評価で指摘された項目のうち、未対応のもの
   • 検証結果

検証スイート

検証コマンドはプロジェクトによって異なります。初回実行時に検出し、セッション間で一定になるようマニフェストに記録します。

{
  "verification": {
    "test": "npm test",
    "typecheck": "npx tsc --noEmit",
    "lint": "npm run lint",
    "detected_at": "[ISO date]"
  }
}

検出順序：

1. package.json のスクリプト、Makefile、Cargo.toml、pyproject.toml などを確認します
2. 一般的なコマンド（npm test、pytest、cargo test、go test ./...）を確認します
3. 何も見つからない場合は、コードベースの検証に使うコマンドをユーザーに尋ねます

すべてのゲートで、3 種類のチェック（テスト、型チェック、リンティング）をすべて通過する必要があります。プロジェクトにそのうちのいずれかがない場合（例：プレーンな JavaScript で型チェッカーがない場合）は、マニフェストに記録してそのチェックをスキップします。ただし、テストは絶対にスキップしないでください。

失敗からの復旧

チャンクが失敗し、再試行が必要な場合：

1. git stash または git checkout . を実行して、失敗したチャンクの未コミットの変更を取り消します
2. マニフェストを更新します：チャンクのステータスを「failed」から「pending」に戻します
3. 再試行したことをログに記録します
4. 計画からチャンクの内容を読み直します
5. チャンクの手順 1 から再度実行します

同じチャンクが 2 回失敗した場合は、もう再試行しないでください。マニフェストを更新し、詳細をログに記録して、ユーザーにエスカレーションします。同じチャンクが 2 回失敗したということは、さらなる試行ではなく、計画の見直しが必要だということです。

セッションの引き継ぎ

すべてのチャンクが完了する前にセッションを終了する場合、または別のエージェント／セッションへの引き継ぎを作成する場合：

1. マニフェストが完全に最新の状態であることを確認します
2. ログエントリーを追加します：「Session ended. Current state: chunk N of M complete. Next: chunk N+1.」
3. マニフェストとログファイルをコミットします

次のセッションでは、まずマニフェストを読み込みます。続行に必要なコンテキストはすべてディスク上にあります。

このスキルが行わないこと

• 何をリファクタリングするかを決めること。 それは評価の役割です（/seam-ripper、/simplicity-audit を使うか、独自の分析を行ってください）。
• アーキテクチャ上の判断を下すこと。 計画が曖昧な場合は、推測せずに停止して確認します。
• 計画にないものを「改善」すること。 場当たり的な整理が、ずれの始まりです。修正する価値のある点に気づいた場合は、今すぐ対応するのではなく、今後のチャンク用に計画へ追加してください。
• 検証を省略すること。 いかなる場合も省略しません。「テストに時間がかかる」は理由になりません。「明らかに問題ない」も理由になりません。