既存コードの改修・テスト整備・大規模リファクタリングをAIエージェントに任せる【2026】レガシーと戦う実践手順

order-system/
├── CLAUDE.md                     # AIと人間の共通ルール（テストコマンド・禁止事項・用語）
├── docs/
│   ├── ARCHITECTURE.md           # 構成説明・主要な処理の流れ（AIが調査して下書き→人が修正）
│   ├── DEPENDENCIES.md           # モジュール依存関係図（Mermaid）と外部依存の一覧
│   └── RISKS.md                  # 危険箇所リスト（暗黙の仕様・副作用・テスト困難箇所）
├── tests/
│   ├── characterization/         # 特性テスト：今の振る舞いを固定（リファクタ中は変更禁止）
│   └── unit/                     # リファクタ後に書く「あるべき仕様」のテスト
└── .claude/
    ├── settings.json             # permissions と hooks（テスト自動実行・特性テスト保護）
    ├── hooks/                    # hooks から呼ぶシェルスクリプト
    └── agents/                   # 調査係・テスト係・レビュー係のサブエージェント定義

# Claude Code をインストール（手順・対応環境は執筆時点。公式ドキュメントで最新を確認）
npm install -g @anthropic-ai/claude-code

# 対象リポジトリで作業ブランチを切る。main で直接作業させない
cd order-system
git switch -c refactor/pricing-module
git status   # 作業前にクリーンであることを確認（AIの変更と自分の変更を混ぜない）

claude

このリポジトリの改修を始める前に、現状を理解したい。コードは一切変更しないで。

1. 全体構成を調べて docs/ARCHITECTURE.md の下書きを作る計画を出して。
   - エントリポイント、主要モジュールの責務、リクエストから DB 更新までの処理の流れ
2. モジュール間の依存関係を Mermaid の graph で docs/DEPENDENCIES.md に。
   - 静的に追えない依存（動的 import、文字列で組み立てる SQL、テンプレートから呼ばれる関数、
     グローバル変数）は「要確認」として別リストにする
3. 危険箇所を docs/RISKS.md に。特に pricing/ 配下について:
   - 暗黙の仕様に見える処理（端数処理、NULL と空文字の区別、日付の境界、税率）
   - 副作用（DB 書き込み、メール送信、外部 API、ファイル出力）
   - テストが書きにくい理由（現在時刻依存、乱数、グローバル状態）
推測で書いた部分には必ず「推測」と明記して。根拠にしたファイルと行も添えて。

## pricing/calc.py
- [暗黙の仕様] calc_price() は席数 11 以上で 1 席あたり単価を切り替えるが、
  境界が「>= 11」か「> 10」かで浮動小数の丸め順が異なる（calc.py L88-L104）
- [暗黙の仕様・推測] クーポン "EXPIRED" 系は例外ではなく 0 円割引として扱われる。
  請求書の再発行処理がこの挙動に依存している可能性（billing/reissue.py L41 から呼び出し）
- [副作用] apply_campaign() がグローバルな CAMPAIGN_CACHE を書き換える
- [テスト困難] datetime.now() を直接呼んでいる（calc.py L17, L130）→ 時刻の注入が必要
## 静的に追えない依存（要確認）
- templates/order.html から {{ pricing.display_price(...) }} で呼ばれている

# order-system 作業ルール

## コマンド
- テスト（速い）: pytest -q tests/characterization -x
- テスト（全体）: pytest -q
- リンタ: ruff check .
- 起動: make dev（DB は docker compose up -d db）

## リファクタリング中の絶対ルール
- tests/characterization/ は「現在の振る舞いの記録」。変更・削除・skip 禁止。
  振る舞いを変える必要があると判断したら、作業を止めて理由を報告すること
- 1 回の変更は 1 つの意図だけ。依頼されていないファイルの整形・改名・コメント修正をしない
- 新しい抽象（基底クラス・ファクトリ・汎用ユーティリティ）を導入する前に、必ず提案して承認を得る
- 公開関数のシグネチャを変えない（templates/ から文字列で呼ばれている箇所がある。docs/DEPENDENCIES.md 参照）

## 用語
- 席（seat）= 契約ユーザー数。 プラン = free / basic / pro
- 「請求書の再発行」は billing/reissue.py。料金計算の挙動変更は請求額に直結する

## 参照
- 構成: docs/ARCHITECTURE.md / 危険箇所: docs/RISKS.md

pricing/calc.py の calc_price() について、特性テスト（characterization test）を作って。
目的は「正しい仕様の確認」ではなく「今の挙動を記録して、リファクタで変わったら検知する」こと。

- 入力の組み合わせ: plan（free/basic/pro）× seats（0, 1, 10, 11, 100）× coupon（None, "WELCOME10", "EXPIRED", 不正な文字列）
- 例外が出る入力は、例外の型を期待値として記録する
- まず scripts/record_calc_price.py で現在の出力を JSON に記録し、
  tests/characterization/test_calc_price.py はその JSON と比較するだけにして
- datetime.now() 依存がある場合は、テスト内で固定する方法を提案して（本体は変更しないで）
- 「バグっぽい挙動」を見つけても直さず、docs/RISKS.md に追記するだけにして

calc_price() を読みやすくしたい。挙動は一切変えない前提で、リファクタリング計画を出して。
- 1 ステップ = 1 コミットになる粒度で、順番に並べて
- 各ステップで「何を変えるか」「どのテストで安全を確かめるか」「リスク」を書いて
- 新しいクラスやモジュールを作る案は、作らない案と比較して理由を書いて

計画のステップ 1 だけ実行して。終わったら pytest -q tests/characterization を実行し、
結果と git diff --stat を見せて。コミットはまだしないで。

"""現在の calc_price() の出力を記録する。リファクタ開始前に 1 回だけ実行する。"""
import itertools
import json
import pathlib
from datetime import datetime

from pricing.calc import calc_price

FIXED_NOW = datetime(2026, 9, 1, 10, 0, 0)  # 現在時刻依存を固定

PLANS = ["free", "basic", "pro"]
SEATS = [0, 1, 10, 11, 100]           # 境界値（10 と 11）を必ず含める
COUPONS = [None, "WELCOME10", "EXPIRED", "!!invalid"]

cases = []
for plan, seats, coupon in itertools.product(PLANS, SEATS, COUPONS):
    args = {"plan": plan, "seats": seats, "coupon": coupon}
    try:
        expected = {"value": repr(calc_price(**args, now=FIXED_NOW))}
    except Exception as e:  # 例外も「今の振る舞い」として記録する
        expected = {"error": type(e).__name__}
    cases.append({"id": f"{plan}-{seats}-{coupon}", "args": args, "expected": expected})

out = pathlib.Path("tests/characterization/calc_price_cases.json")
out.write_text(json.dumps(cases, ensure_ascii=False, indent=2), encoding="utf-8")
print(f"recorded {len(cases)} cases -> {out}")

import json
import pathlib
from datetime import datetime

import pytest

from pricing.calc import calc_price

FIXED_NOW = datetime(2026, 9, 1, 10, 0, 0)
CASES = json.loads(
    (pathlib.Path(__file__).parent / "calc_price_cases.json").read_text(encoding="utf-8")
)


@pytest.mark.parametrize("case", CASES, ids=[c["id"] for c in CASES])
def test_calc_price_behavior_is_unchanged(case):
    try:
        actual = {"value": repr(calc_price(**case["args"], now=FIXED_NOW))}
    except Exception as e:
        actual = {"error": type(e).__name__}
    assert actual == case["expected"]

{
  "permissions": {
    "allow": [
      "Bash(pytest:*)",
      "Bash(ruff check:*)",
      "Bash(git diff:*)",
      "Bash(git status)",
      "Bash(git log:*)"
    ],
    "ask": ["Bash(git commit:*)"],
    "deny": [
      "Read(./.env)",
      "Read(./config/production.*)",
      "Bash(git push:*)",
      "Bash(python scripts/record_*:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": ".claude/hooks/protect-characterization.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": ".claude/hooks/fast-checks.sh" }]
      }
    ]
  }
}

#!/usr/bin/env bash
# PreToolUse: 特性テストの編集をブロックする（exit 2 でブロックし、stderr が Claude に返る）
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  */tests/characterization/*)
    echo "tests/characterization/ はリファクタ中は変更禁止です。挙動を変える必要があるなら、作業を止めて理由を人間に報告してください。" >&2
    exit 2
    ;;
esac
exit 0

#!/usr/bin/env bash
# PostToolUse: Python ファイルを編集したら、リンタと特性テストを自動実行
# 失敗したら exit 2 で結果を Claude に返し、自分で直させる
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.py)
    ruff check "$file" 1>&2 && pytest -q -x tests/characterization 1>&2 || exit 2
    ;;
esac
exit 0

---
name: diff-reviewer
description: リファクタリングの差分をレビューする。コミット前やPR作成前に使う。コードは修正しない。
tools: Read, Grep, Glob, Bash
---
あなたはレガシーコード改修のレビュアーです。`git diff main...HEAD` を読み、次の観点で指摘してください。
修正はせず、指摘を「重大 / 要確認 / 軽微」に分けて、ファイル名と行を添えて報告します。

1. テストの弱体化: assert の削除・緩和、skip/xfail の追加、期待値の書き換え、例外の握りつぶし
2. スコープ外の変更: 依頼の意図と関係ないファイル・整形・改名・コメント変更
3. 過剰な抽象化: 呼び出し元が1つしかない基底クラス・ファクトリ・設定項目の追加
4. 挙動変更の混入: 丸め・日付境界・NULL の扱い・例外の型・ログ/副作用の順序の変化
5. 公開インターフェースの変更: 関数シグネチャ、テンプレートから呼ばれる関数名
最後に「このままコミットしてよいか」を Yes/No と理由1行で答えてください。

# 独立したモジュールごとに作業場所を分ける
git worktree add ../order-wt-pricing -b refactor/pricing
git worktree add ../order-wt-report  -b refactor/report-export

# それぞれのディレクトリで別の Claude Code セッションを起動
cd ../order-wt-pricing && claude
# (別ターミナル) cd ../order-wt-report && claude

# 終わったら片付け
git worktree remove ../order-wt-pricing

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "allowJs": true,
    "checkJs": false,
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

src/ 配下の JavaScript を TypeScript に段階移行したい。コードはまだ変えないで、計画だけ出して。
- import の依存グラフを調べ、他から依存されていないファイル（葉）から順に並べた移行順リストを作る
- 1 PR あたりの目安は 5 ファイル以内。PR ごとの移行対象を分けて
- 外部 API のレスポンスや localStorage など「実行時にしか形が分からないデータ」は一覧にして、
  型をどう決めるか（zod 等で実行時検証するか、型だけ付けるか）の選択肢を比較して
- 各 PR の完了条件: npx tsc --noEmit と npm test が通る / any と @ts-expect-error の件数を報告

#!/usr/bin/env bash
# リファクタ差分の「怪しい変更」を機械的に拾う（完全ではない。人のレビューの補助）
base=${1:-main}

echo "== 変更規模 =="
git diff --stat "$base"...HEAD | tail -1

echo "== テストから消えた assert / expect =="
git diff "$base"...HEAD -- 'tests/**' '*.test.*' '*_test.py' \
  | grep -E '^-[^-].*(assert|expect\()' || echo "(なし)"

echo "== 追加された skip / only / 型・lint の黙らせ =="
git diff "$base"...HEAD \
  | grep -E '^\+[^+].*(\.skip\(|\.only\(|xit\(|pytest\.mark\.(skip|xfail)|@ts-ignore|@ts-expect-error|eslint-disable|# noqa|: any\b)' \
  || echo "(なし)"

echo "== 新規ファイル（過剰な抽象化の候補） =="
git diff --name-status "$base"...HEAD | grep '^A' || echo "(なし)"