技術的負債をClaudeと計画的に返済する方法

このワークフローが有効な場面

技術的負債が積み重なりすぎて、どこから手をつけるかわからないとき
チームに技術的負債の解消を提案したいが、コストの見積もりが難しいとき
少しずつ改善したいが、日々の機能開発に追われているとき
技術的負債の「棚卸し」をしたいとき

技術的負債の棚卸しから始める

ステップ1: Claudeに技術的負債を洗い出してもらう

「このプロジェクトの技術的負債を洗い出してください。

調査対象:
- src/ ディレクトリ全体

洗い出してほしい観点:
1. TODO/FIXMEコメント（全て列挙）
2. 重複しているコード（DRY違反）
3. 長すぎるファイル・関数（300行以上）
4. 型安全でない箇所（any型の使用）
5. テストがない重要なロジック
6. 古いライブラリのバージョン（package.jsonを確認）
7. console.log が残っているコード

ファイルを実際に読んで調査してください。
結果はマークダウンのテーブル形式でまとめてください。」

ステップ2: 優先順位をつける

Claudeが洗い出した技術的負債を、インパクトとコストで分類します。

「洗い出した技術的負債に優先順位をつけてください。

優先度の基準:
- 高: ビジネスへの影響が大きい（バグのリスク、パフォーマンス問題）
- 中: 開発効率に影響する（テスト追加のしにくさ、理解しにくいコード）
- 低: きれいにしたいだけ（命名、コメント）

各項目に対して:
- 優先度（高/中/低）
- 修正にかかる概算時間
- 対応する場合のアプローチ

を教えてください。」

ステップ3: 返済計画を立てる

「優先度の高い技術的負債から、3ヶ月の返済計画を作ってください。

制約:
- 毎週金曜日に2時間程度（合計約24時間）
- 通常の機能開発を止めない
- 各回の作業は独立したPRとして出せるようにする

計画のフォーマット:
- 第1〜4週: [作業内容]（推定X時間）
- 第5〜8週: [作業内容]（推定X時間）
- ...」

※型安全: 変数や関数の型をコンパイル時にチェックし、型の不一致によるバグを防ぐ設計方針。

具体的な返済作業のワークフロー

パターン1: TODO/FIXMEコメントの解消

「src/ 以下の TODO コメントを全て調査して、
以下のように分類してください:

1. すぐに対応可能（30分以内）
2. 要設計が必要（半日以上）
3. 外部要因で対応できない（仕様待ち等）

すぐに対応可能なものから片付けましょう。
第1弾として5件を選んで、修正してください。」

パターン2: 重複コードの共通化

「以下の重複コードを発見しました:
- src/api/users.ts:45 の validateEmail
- src/api/auth.ts:23 の checkEmailFormat
- src/utils/form.ts:67 の isValidEmail

これらを統一してください。
場所: src/utils/validation.ts に isValidEmail として集約
既存の3箇所は新しい関数を使うように変更」

パターン3: 長すぎるファイルの分割

「src/components/Dashboard.tsx が600行あります。
段階的に分割してください。

第1ステップ: コンポーネントの境界を特定する（コードは変更しない）
- どこで分割するのが適切か提案してください

第2ステップ: 最も独立性の高い1コンポーネントだけ切り出す
- 残りはまた次回」

毎週の返済作業のルーティン

技術的負債の返済を継続するためのルーティン例：

## 毎週金曜のルーティン

### 作業開始時
「先週の技術的負債リスト（.claude/tech-debt.md）を確認して、
今週取り組む項目を1〜2個選んでください。
見積もり時間が2時間以内のものを優先して。」

### 作業中
「[選んだ項目] に取り組みます。
変更が完了したら、tech-debt.md の該当項目を「完了」に更新してください。」

### 作業終了時
「今日の作業をまとめて .claude/tech-debt-log.md に追加してください。
- 完了した項目
- 発見した新しい負債（あれば）
- 次回のおすすめ作業」

技術的負債ファイルの管理

プロジェクトに技術的負債を記録するファイルを作成して、Claudeと一緒に管理します。

# tech-debt.md（例）

最終更新: 2026-05-01

## 優先度: 高

### [未対応] User モデルのany型
- ファイル: src/types/user.ts
- 問題: User型に any が使われていてバグの温床
- 対応方針: Prismaの生成型を使うように変更
- 見積もり: 2時間
- 担当:

### [対応中] 認証ロジックの重複
- ファイル: src/api/auth.ts, src/middleware/auth.ts
- 問題: 同じJWT検証ロジックが2箇所
- 対応方針: src/lib/auth.ts に共通化
- 見積もり: 1時間
- 担当: Claude担当, 2026-05-03開始予定

## 優先度: 中

### [完了] console.log の削除
- 完了日: 2026-04-28
- 変更PR: #156

※JWT: JSON Web Token の略。ユーザー認証情報をJSON形式でエンコードしたトークン。ヘッダーに付けてAPIを呼び出す際に使う。

チームへの説明・共有

技術的負債の返済をチームに提案するときに使えるフォーマット：

「技術的負債の棚卸し結果を、チームへの提案資料にまとめてください。

含めてほしい内容:
1. 現状のサマリー（件数・リスクレベル）
2. 放置した場合の影響（速度低下・バグリスク）
3. 3ヶ月の返済計画（コスト試算付き）
4. チームへのお願い（毎週2時間）

読む人: エンジニアチーム + PM
トーン: 数字で説得する、感情的な訴えはしない」

注意点・よくある失敗

失敗1: 全部一気に直そうとする

「全ての技術的負債を今週で解消する」はほぼ必ず失敗します。週2時間の継続のほうが、1週間の集中作業より効果的です。

失敗2: 技術的負債の解消中に機能を追加する

リファクタリングと同様、技術的負債の返済PRには機能追加を混ぜません。

失敗3: 記録なしに進める

何を直したか記録がないと、「この前直したはずのバグがまた出た」という事態が起きます。tech-debt.md のような記録ファイルを必ず維持しましょう。

※リファクタリング: 外部から見た動作を変えずに、コードの内部構造を整理・改善すること。