レガシーコード保守向けCLAUDE.mdテンプレート

レガシーコード保守でCLAUDE.mdが特に重要な理由

レガシーコードベースでClaude Codeを使うとき、最も危険なのは「Claudeが善意で大きく書き換えてしまうこと」です。

「このコード、全部書き直したほうがきれいになりますよ」——その提案は正しいかもしれません。でも、10年動いてきたコードには、コードには書かれていない「暗黙の知識」が詰まっています。あの if 文には理由があり、あの回避策には歴史があります。

レガシーコード向けのCLAUDE.mdは、Claudeに「慎重に、小さく、確認しながら」動いてもらうための設定です。

※CLAUDE.md: プロジェクトのルートに置くClaude Code専用の設定ファイル。プロジェクト固有のルールやコンテキストを記述する。

テンプレート本体

# [プロジェクト名] — レガシーコード保守ガイド

## このプロジェクトについて

- **稼働期間**: 約XX年
- **言語・フレームワーク**: [例: PHP 7.4 + CakePHP 3.x]
- **現状**: 本番稼働中（一日あたりXXXユーザーが使用）
- **最終目標**: [例: Rails 7にリプレイス / モジュール化 / テスト追加]

## 最重要原則

**このコードベースで作業するときは以下を守ること。**

1. **動いているものを壊さない**: 小さな変更を積み重ねる
2. **確認してから進む**: 大きな変更の前に必ず方針を説明する
3. **既存のスタイルに合わせる**: 新しいコードで突然モダンな書き方をしない
4. **テストがなければ書いてから変える**: テストなしの変更は提案しない

## 現在のコードベースの状況

### 既知の問題点（触れない）

以下のコードには既知の問題があるが、**現時点では修正しない**。
副作用が大きすぎるため、計画的に対処する。

- `app/Controllers/OrdersController.php` の `processPayment()` メソッド
  - 決済処理と在庫更新が同一トランザクションに混在
  - 現状は動いているので触らない

- `lib/legacy/user_auth.php`
  - 古い暗号化方式を使用（MD5）
  - マイグレーション計画あり（2025年Q2予定）

### 地雷ポイント（必ず確認してから変更）

- **`config/database.php`**: 本番・ステージング・開発の設定が混在している
- **`app/Models/User.php`**: 複数の認証システムが依存している（変更前に要確認）
- **`public/js/main.js`**: jQueryコードが散在。`$` は jQuery を指す

## 変更の原則

### やっていいこと

✅ バグ修正（既存の動作を壊さない範囲） ✅ 新機能の追加（既存コードへの影響が小さい場合） ✅ テストの追加（既存コードを変更せずに） ✅ コメントの追加・改善 ✅ ログ出力の追加 ✅ 設定値の定数化（マジックナンバーを排除）

### 要相談・慎重に進めること

⚠️ 既存関数の引数変更 ⚠️ データベーススキーマの変更 ⚠️ 認証・権限関連のコード ⚠️ 外部APIとの連携部分 ⚠️ バッチ処理・スケジューラー

### 原則としてやらないこと

❌ 動いている機能の「きれいにするための」書き直し ❌ 依存ライブラリの突然のアップグレード ❌ グローバル変数・関数の削除（利用箇所を完全に確認する前に） ❌ データベースのカラム削除・リネーム

## 段階的改善計画

### フェーズ1（現在）: テストを書く

既存コードを変更せず、テストを追加する。

```bash
# テストの追加方法
vendor/bin/phpunit tests/Unit/OrdersTest.php

# カバレッジ確認
vendor/bin/phpunit --coverage-html coverage/

フェーズ2: 新機能はモダンなスタイルで

既存コードには手を加えず、新機能は現代的な設計で追加する。

新機能は src/NewFeatures/ 以下に配置
PSR-4 オートローディングを使用
PHPUnit でテスト必須

フェーズ3: 既存コードの段階的リファクタリング

テストがある部分から少しずつ改善する。

※リファクタリング: 外部から見た動作を変えずに、コードの内部構造を整理・改善すること。※マイグレーション: データベースのスキーマ（テーブル構造）を安全に変更するための手順書。※スキーマ: データベースのテーブル構造や型定義のこと。※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

コードの読み方・注意点

頻出するパターン

// このプロジェクト固有のエラーハンドリング
// （例外を使わず、戻り値でエラーを示す古いパターン）
$result = doSomething();
if ($result === false) {
    // エラー処理
    $this->log('エラー: ' . $this->getLastError());
    return false;
}

// グローバル設定の読み込み方（このプロジェクト固有）
global $config;
$db_host = $config['database']['host'];

ドキュメントに書かれていない仕様

ユーザーIDが 0 の場合はゲストユーザーを意味する（コードに明示されていない）
注文ステータス 9 はキャンセル扱いだが、DBの cancelled カラムとは別物
user_type = 3 は内部管理アカウント（ドキュメントなし）

テスト戦略

テストのない既存コードを変更するときは：

ステップ1: 変更前のスナップショットテストを書く

public function testCurrentBehavior(): void
{
    // 現在の動作をそのままテストとして記録する
    $result = $this->orderProcessor->calculate([
        'product_id' => 1,
        'quantity' => 2,
    ]);

    // 現在の（正しいかどうかに関わらず）動作を記録
    $this->assertEquals(2000, $result['total']);
    $this->assertEquals(200, $result['tax']);
}

ステップ2: テストが通ることを確認してから変更

# 変更前: テストがグリーンであることを確認
vendor/bin/phpunit tests/Unit/OrderProcessorTest.php

# コードを変更

# 変更後: テストがまだグリーンであることを確認
vendor/bin/phpunit tests/Unit/OrderProcessorTest.php

よく使うコマンド

# 開発サーバー起動
php -S localhost:8000 -t public/

# テスト実行
vendor/bin/phpunit

# 特定のテストのみ
vendor/bin/phpunit --filter testOrderCalculation

# SQLダンプ（確認用）
mysqldump -u root -p legacy_db > backup_YYYYMMDD.sql

# ログ確認
tail -f logs/app.log

変更履歴

変更を加えるたびに、このセクションを更新する。

2026-XX-XX: [変更内容] by [担当者]
  - 変更した理由
  - 影響範囲
  - テスト追加: ✅ / ❌

Claudeへのお願い

大きな変更の前に必ず確認する: 「この変更をしようと思いますが、影響範囲はXXです。進めますか？」と聞いてから作業すること
既存のコードスタイルを真似する: このプロジェクトはPSR-12には従っていない。既存コードのスタイルに合わせること
「きれいにしたい」衝動を抑える: 動いているコードは触らない
わからないことは聞く: 「このコードの意図がわからないのですが…」と聞いてOK

## 各セクションの説明

**既知の問題点（触れない）**: これが最も重要なセクションです。Claudeが「改善しようとして壊してしまう」コードを事前に指定します。

**地雷ポイント**: 変更する前に人間に確認が必要な箇所を明示します。Claudeは「確認してから進む」ことができますが、何を確認すべきかを知らなければなりません。

**ドキュメントに書かれていない仕様**: これはコードには書かれていない暗黙知です。特に「`0` はゲストユーザー」のような数値の意味は、書いておかないとバグの原因になります。

## カスタマイズのポイント

1. **現在のフェーズを明確にする**: 「テストを書く段階」「リファクタリング段階」「リプレイス段階」によって、Claudeへの指示が変わります。

2. **地雷ポイントは随時更新する**: 作業していて新たに「ここは危険」とわかった箇所を追加し続けてください。

3. **変更履歴セクション**: Claudeにこのセクションを更新してもらう習慣をつけると、後から「なぜこの変更をしたか」が追えます。

:::tip
レガシーコードをClaude Codeで扱うときの最強パターンは「まずテストを書いてもらう → テストがグリーンな状態で変更を依頼する → テストで変更前後の動作が変わっていないことを確認」です。このサイクルをCLAUDE.mdに明記しておきましょう。
:::