self-reflection-review

name	self-reflection-review
description	Claude が書いた AgentVillage のコードを自己レビューし、MVP 段階で妥協した やっつけ箇所を正直に洗い出して GitHub Issue 化まで行うスキル。 「コードレビューして」「やっつけコード探して」「技術的負債を棚卸し」 「self-reflection」「MVP で流したコードを見直したい」などのフレーズで積極的に起動する。 src/ 全体、特定モジュール、特定観点など絞り込み指定にも対応する。

Self-Reflection Review

Claude 自身が書いたコードを自己レビューし、MVP 段階で妥協した箇所を正直に洗い出して GitHub Issue 化まで一気に行うスキル。

モード選択

ユーザーの発言からモードを判断する:

モード	トリガー例	スコープ
フルスキャン	「self-reflection-review して」「技術的負債を棚卸し」	src/ 全体（または絞り込み指定）
コミットレビュー	「直近のコミットをレビュー」「このPRの変更を見て」「今日書いたコードをレビュー」	指定コミット / 直近 N コミットの差分

モードが判断できない場合は「フルスキャンとコミットレビューどちらにしますか？」と確認する。

---

フロー（共通）

[1] スキャン          — コードを読んで問題リストを生成（モードにより方法が異なる）
[2] リスト提示        — 番号付き表でユーザーに提示
[3] ユーザーレビュー  — 修正・削除・追記を受け付ける（確定まで繰り返し）
[3.5] 重複チェック   — doc/Ideas.md と照合し、重複・部分重複・新規を仕分ける
[4] Issue 登録        — gh issue create で一括登録
[5] Ideas.md 更新     — コミット & PR 作成を提案

---

Phase 1A — フルスキャン

スコープ

• デフォルト: src/ 以下の全ファイル
• ユーザーが「src/engine/ だけ」「エラーハンドリングだけ」など絞り込みを指定した場合はそれに従う

読み方

全ファイルを読んだ上で、以下の 7つの観点 でそれぞれ問題を探す。 自分が書いたコードである前提で、「なぜその実装を選んだか」まで正直に思い出して記述する。

---

Phase 1B — コミットレビュー

対象コミットの確定

まず直近のコミット一覧を表示し、対象を確定する:

git log --oneline -10

ユーザーがコミットを指定していない場合は一覧を見せて確認する:

直近のコミット:
  abc1234 feat: add pre-night judgment phase
  def5678 refactor: extract vote tallying
  ...

どのコミットをレビューしますか？（例: "直近1件" / "abc1234" / "直近3件"）

差分の取得

対象が決まったら diff を取得する:

# 直近1件
git show HEAD --stat
git diff HEAD~1 HEAD -- src/

# 特定コミット
git show <hash> --stat
git diff <hash>^..<hash> -- src/

# 複数コミット
git diff HEAD~N HEAD -- src/

読み方

1. diff を読む — 追加行（+）を中心に変更の意図を把握する
2. 変更されたファイルの前後を読む — diff だけでは見えないコンテキストを補う（変更ファイルの全体を Read する）
3. 観点 G を最優先に — 今回の変更が既存コードのスメルを強化していないか集中的に確認する
4. 他の観点も適用 — 新たに導入されたハードコード・重複・エラーハンドリング漏れがないか確認する

コミットレビュー特有の出力

リスト提示時に「この変更で新たに導入された問題か、元からある問題か」を明示する:

#	ファイル	箇所	観点	問題の概要	深刻度	新規導入 or 既存
1	src/engine/game.py	_run_night()	G: 変更増幅	今回の変更でisinstance分岐が1つ増え、将来の役職追加コストがさらに高まった	🟡 medium	今回の変更で悪化
2	src/llm/client.py	call_new_action()	E: 重複ロジック	新関数が既存のcall()パターンをコピーしている	🔴 high	今回の変更で新規導入

---

Phase 1（共通） — 観点一覧

観点ID	観点名	具体的に見るポイント
A	クラス/モジュール分割不足	1関数・1クラスに複数責務が混在、行数が多すぎる
B	ハードコード	マジックナンバー、設定値の埋め込み、定数化すべき文字列
C	スケール耐性	役職追加・フェーズ追加・人数増加時に壊れそうな設計
D	エラーハンドリング省略	システム境界（LLM レスポンス・ファイル I/O 等）での検証・例外処理の欠落
E	重複ロジック	コピペ臭のある類似コード、DRY 違反
F	アーキテクチャ逸脱	CLAUDE.md の設計原則（ドメイン分離・絶対インポート等）から外れている箇所
G	変更増幅スメル	直近の変更（機能追加・リファクタ）によって既存のコードスメルが強くなった箇所。フラグ・特殊ケース分岐・コメントアウトが増えたら要注意
H	変数の意味多重化	1つの変数が複数の意味を兼ねている（フラグでない変数をフラグとして使う／None に「未設定」と「リセット済み」を兼用／is_alive=False に「死亡」と「投票対象外」を兼用 等）。名前が意味する単一概念以上のことを判定に使っていないか

---

Phase 2 — リスト提示

以下のフォーマットで番号付きリストを提示する。

## Self-Reflection Review 結果（{N}件）

| # | ファイル | 箇所 | 観点 | 問題の概要 | 深刻度 | なぜそうした |
|---|---|---|---|---|---|---|
| 1 | src/ui/renderer.py | render_event() | A: クラス/モジュール分割不足 | イベント種別ごとの分岐が1関数に集中。将来的に種別が増えると肥大化する | 🟡 medium | MVP段階で分割のコストを避けた |
| 2 | ... | | | | | |

**深刻度の基準**
- 🔴 high: 今すぐ直さないと新機能追加やデバッグが困難になる
- 🟡 medium: しばらくは動くが、拡張時に必ず問題になる
- 🟢 low: 気になるが今すぐ直さなくてもよい

---
**操作方法:**
- `削除: 3, 5` — 指定番号を除外
- `3を修正: {新しい内容}` — 問題・深刻度・理由を変更
- `追加: {内容}` — 見落としを追記
- `ok` または `登録` — このまま Issue 化へ進む

---

Phase 3 — ユーザーレビュー

ユーザーの指示（削除・修正・追加）を受け付け、リストを更新して再提示する。 「ok」「登録」「全部登録」などの確定ワードが来るまでこのループを繰り返す。

確定ワードを受け取ったら Phase 3.5 へ進む。

---

Phase 3.5 — Ideas.md 重複チェック

Issue 登録前に doc/Ideas.md を読み、既存 Issue との重複を確認する。

各アイテムについて以下を判定する:

• 重複: 同じ問題がすでに Ideas.md に記載されている → 除外候補としてマーク
• 部分重複: 関連する Issue はあるが観点が異なる → 補足情報として明示
• 新規: Ideas.md に存在しない → そのまま登録候補

重複チェック結果を提示する:

## Ideas.md 重複チェック結果

✅ 新規（{N}件）— Issue 化します:
  1. 🔴 src/llm/client.py — call関数の重複ロジック（E）
  2. ...

⚠️ 部分重複（{M}件）— 関連Issueあり、登録しますか？:
  3. 🔴 src/engine/game.py — _run_night() の肥大化（A）
     → 関連: #58「Split GameEngine phases」（同じファイルだが観点が異なる）

❌ 重複のため除外（{K}件）:
  4. src/domain/agent.py — Dead code（#71「Eliminate redundant role」と同一）

⚠️ の件は個別に「登録 / スキップ」を指定してください。
（例: "3を登録" / "3をスキップ" / "全部登録"）

確認が取れたら最終リストを確定して Phase 4 へ。

以下の {N} 件を GitHub Issue として登録します:

1. 🔴 src/llm/client.py — call関数の重複ロジック（E: 重複ロジック）
2. ...

よいですか？ [y/N]

---

Phase 4 — Issue 登録

y の確認後、1件ずつ登録する。

Issue 本文の構成:

## Background
{なぜそうしたか — 自己解説をそのまま使う}

## Problem
{問題の詳細。観点ID（A〜F）と深刻度も記載}

## Acceptance Criteria
- [ ] {修正完了の最低条件}
- [ ] ruff check . と pytest がパスすること

gh issue create \
  --title "{問題の簡潔な英語タイトル（50文字以内）}" \
  --body "..." \
  --label "tech-debt" \
  --repo yukkie/AgentVillage

全件登録後にサマリーを表示する：

{N} 件の Issue を登録しました:
- #XX: {タイトル}
- ...

---

Phase 5 — Ideas.md 更新

全件登録後、doc/Ideas.md の tech-debt セクションへの追記を提案する。 承認されたら docs/self-reflection-review-{YYYYMMDD} ブランチを作成してコミット & PR を出す。