CLAUDE.md Refinement Loop Engine

コーディングエージェントが「楽な方に流れる」性質（セキュリティ黙殺、prop drilling、一時しのぎ等）を、自動化された補正ループで矯正するツール。

バニラ状態の CLAUDE.md を Generate → Review → Evolve の3回サイクルで鍛え上げ、洗練されたコーディングガイドラインを自動生成。

仕組み

User Input (初期grudges / 不満点)
    ↓
[Iteration 1]
    ├─ Generate: Claude CLI でフルスタックアプリを生成
    ├─ Review:   ESLint静的解析 + LLMレビュー + ルール準拠チェック
    ├─ Grudge:   不満点（アンチパターン）を蓄積・分類
    └─ Evolve:   CLAUDE.md に BAD/GOOD 例付きルールを追加
[Iteration 2] ... 更新された CLAUDE.md で再生成・再レビュー
[Iteration 3] ... 最終研磨
    ↓
Output: 鍛え上げられた CLAUDE.md + 改善レポート

生成される Web サービスは使い捨て。最終成果物はCLAUDE.md

セットアップ

npm install --legacy-peer-deps

前提条件:

• Node.js 20+
• Claude Code CLI がインストール済みで認証済み

使い方

# 基本実行（3イテレーション）
npx tsx src/index.ts

# 不満を初期シードとして投入
npx tsx src/index.ts -g "prop drillingするな" "anyを使うな" "セキュリティを無視するな"

# フルカスタマイズ
npx tsx src/index.ts \
  -i 3 \
  -m sonnet \
  --generation-model opus \
  --budget 5 \
  --app-description "ブログアプリ with 認証" \
  --backend fastify \
  --database postgres \
  --preserve-projects \
  --verbose

オプション

フラグ	説明	デフォルト
-i, --iterations	リファインメント回数	3
-m, --model	全フェーズのモデル	sonnet
--generation-model	生成フェーズ専用モデル	-m の値
--review-model	レビューフェーズ専用モデル	-m の値
--evolution-model	進化フェーズ専用モデル	-m の値
-g, --grudge	初期不満点（複数可）	なし
-o, --output	出力ディレクトリ	./output
--budget	イテレーションあたり上限 (USD)	5
--app-description	生成するアプリの説明	タスク管理アプリ
--backend	express / fastify	express
--database	sqlite / postgres	sqlite
--styling	tailwind / css-modules	tailwind
--preserve-projects	生成プロジェクトを保持	false
--skip-permissions	--dangerously-skip-permissions を使用	false
--verbose	詳細ログ	false

出力

./output/ に以下が生成されます:

ファイル	内容
CLAUDE.md	最終版ガイドライン
CLAUDE-v0.md ~ v3.md	各イテレーション時点のバージョン
iteration-{n}.json	各イテレーションの詳細（スコア、findings、grudge）
report.json	構造化レポート（スコア推移、不満点統計、コスト）
report.txt	テキスト形式のサマリー

アーキテクチャ

src/
  index.ts              # CLI エントリポイント
  orchestrator.ts       # メインループ制御
  generator.ts          # Claude CLI でコード生成
  reviewer.ts           # 3段階レビューパイプライン
  grudge-buffer.ts      # 不満点メモリ（蓄積・重複排除・優先順位）
  md-evolver.ts         # CLAUDE.md 進化ロジック
  claude-cli.ts         # Claude Code CLI サブプロセスラッパー
  scoring.ts            # スコアリング・改善追跡
  config.ts             # 設定管理
  types.ts              # 全型定義
  prompts/              # プロンプトテンプレート
  utils/                # ログ、ファイル操作、ESLint実行、エラー定義

レビュー3段階

1. Static Review — ESLint (@typescript-eslint, eslint-plugin-security) で型安全性、セキュリティホールを検出
2. Logic Review — LLM が本番運用の観点でコードレビュー（認証、エラーハンドリング、API設計等）
3. Compliance Review — 現在の CLAUDE.md のルールを守っているかチェック

スコアリング

各段階 0-100 で採点し、加重平均を算出:

• Static: 25% — max(0, 100 - errors*5 - warnings*1)
• Logic: 40% — LLM が直接評価
• Compliance: 35% — 準拠ルール数 / 全ルール数 * 100

コスト目安

3イテレーション x (生成1回 + レビュー2回 + 進化1回) = 約12-15回の Claude CLI 呼び出し。

Sonnet 使用時: $1-$8 程度（生成するアプリの規模による）