reflection

name

reflection

description

Claudeセッションのログ（ディレクトリ指定があればそのリポジトリの過去全 worktree、指定がなければ現在実行中のセッション）を分析し、設計・実装中にユーザーから受けた指摘・軌道修正・ダメ出しや、Claude自身のつまずきを「教訓」として蒸留し、行き先を見極めてコーディングルールへ反映するスキル。一般化できる改善点・設計思想・実装技法はグローバルルール（~/.claude の CLAUDE.md / rules）へ、そのプロジェクト固有の事情で寄り道・難航した知見はそのリポジトリの .claude（CLAUDE.md / rules）へと、肥大させずに振り分ける。「この指摘を二度とさせたくない」「さっきの反省をルールに落としたい」「セッションを振り返ってルールにして」「最近の指摘から学習して」「同じミスを繰り返さないようにルール化して」「reflection」「振り返って」と言われたとき、また長いセッションでユーザーが何度も似た修正を入れていたと気づいたときにも積極的に使うこと。コードベースからルールを起こす refine-rules とは入力が違い、こちらは「人間がClaudeに与えたフィードバック」を入力にする。

Reflection

過去のClaudeセッション（会話ログ）を分析し、設計・実装の過程で Claudeがやらかしたこと と それに対して人間が入れた指摘・軌道修正・ダメ出し をペアで読み解き、背後の教訓を蒸留して、行き先を見極めて コーディングルールに反映するスキル。教訓には二種類あり、行き先が違う:

• 一般化できる原則 — 指摘された改善点・設計思想・実装技法のうち、どのプロジェクトでも成り立つもの → グローバルルール（claude/CLAUDE.md と claude/rules/、実体は ~/.claude 配下）。
• そのプロジェクト固有の知見 — Claudeがそのリポジトリ固有の事情で寄り道した・詰まった・誤った前提で進んだ箇所から得られる、知っていれば遠回りを避けられた事実 → そのリポジトリの .claude/（CLAUDE.md / rules）。

目的はただ一つ、同じ種類のミスを二度と繰り返さないこと。

refine-rules がコードベースを観察してルールを起こすのに対し、こちらは「セッションでのClaudeの振る舞いと、それへの人間のフィードバック」を入力にする。両者は補完関係にある。

重要 — 人間の発話だけ見ても反省にならない。 「これはダメって言ったでしょ」という一言は、その直前にClaudeが何を提案・実装したかを見て初めて意味を持つ。反省すべきは Claudeの振る舞い であり、人間の指摘はそれが間違っていた「目印」にすぎない。だから抽出の単位は人間の発話単体ではなく、(Claudeの提案/行動) → (人間の指摘) というペア（= correction episode）にする。

このスキルの信条（ここが本体）

ルールを足すことは簡単で、足し続ければルールは壊れる。だから判断の質がすべて。次の3つを常に意識する。

1. 枝葉ではなく原理原則を抽出する

ユーザーの指摘はたいてい具体的な事象として現れる（「このエンドポイントのトークンに tenant_id を入れるな」）。しかしルールにすべきは、その背後にある 設計思想（「資格情報には必要最小限の識別子だけを載せ、残りはサーバ側で導出する」）。

• 具体名（プロジェクト名・エンドポイント・変数名・特定ライブラリ）が混じったら、それは枝葉のサイン。抽象化できているか自問する。
• 同じ指摘が別の文脈でも通用する形まで一般化できて初めてルールになる。一度きりの好み（命名の語感など）はルールにしない。

2. ルールを肥大させない（追記は最後の手段）

ルールには「積載量」がある。1項目ごとに居場所を勝ち取らせる。新しい原則を反映するときの優先順位は次のとおり:

• Skip — 既存ルールで既にカバーされている → 何もしない（冪等性。「もう効いている」と記録するだけ）。
• Sharpen — 既存ルールが弱く/暗黙にしか触れていない → 既存の一文を強める、短い但し書きを足す。新しい箇条書きは増やさない。
• Absorb（一般化して吸収） — 新しい原則と既存の複数ルールが、より上位の一文の特殊例だと気づいたら → それらを1つの一般則に書き直し、冗長になった個別記述を削る。ここで行数はしばしば減る。
• Add — どこにもカバーされていない真に新しい領域のときだけ、簡潔に追加する。新しいドメインを成すなら CLAUDE.md を膨らませず rules/<domain>.md を新設する。

健全な実行は、Absorb/Sharpen が Add を相殺して、純増がほぼゼロに収まることが多い。1回の実行で行数が増えるばかりなら、統合が足りていない。

3. 行き先で「見る観点」を変える — グローバルか、プロジェクトか

教訓は安易に捨てず、二つの行き先のどちらかに振り分ける。両者は観点がまるで違うので混同しない。

• グローバル（~/.claude の CLAUDE.md / rules）— 一般化して原則を抽出する。 指摘された改善点・設計思想・実装技法のうち、どのプロジェクトでも成り立つもの（セキュリティ・エラーハンドリング・API設計思想・検証/テストの姿勢など）。ここでは具体（プロジェクト名・パス・特定API・特定ライブラリ）を 剥がして 転用可能な一文に昇華するのが仕事（信条1のとおり）。観点は「これは別のリポジトリでも通用するか？」。
• プロジェクト（そのリポジトリの .claude/CLAUDE.md / .claude/rules/）— 寄り道の原因になった固有知識を記録する。 Claudeが そのプロジェクト固有の事情 で寄り道した・詰まった・誤った前提で進んだ箇所。ここでは逆に具体を 剥がさない —「このリポジトリではビルド/テストは X で回す」「この層の状態は Y に置く約束」「この生成物は触らず Z から再生成する」といった、知っていれば遠回りせずに済んだ事実そのもの が価値。観点は「次回このリポジトリで同じ所で転ばないために、Claudeは何を知っているべきだったか？」。

捨てるのは どちらの観点にも乗らないものだけ（一度きりの語感の好み、再発しない偶発事など）。「一般化できないから捨てる」は誤り — 一般化できないものは、まずプロジェクト側に固有知識として置けないかを問う。

手順

作業中は必ずworktree内にファイルを作成すること。またファイルを削除することを禁止する。

Step 1: 対象セッションを解決する

入力の有無で二通りに分岐する。

• ディレクトリ（パス）が渡された場合 — そのパスからリポジトリを特定し、その 全 worktree のセッションを横断対象にする。パスのエンコード規則とglob方法は references/mining.md 参照。過去ログを掘るモードなので Step 2 のサブエージェント委譲を使う。
• 何も渡されなかった場合 — 今まさに実行中のこのセッション を対象にする。会話履歴は既にこの文脈の中にあるので、新たにログを掘る必要はない。Step 2 のJSONL抽出やサブエージェント委譲は スキップ し、この場で対話を遡って correction episode を読み取る。文脈が要約で圧縮されていて欠けがありそうな場合に限り、references/mining.md の「現在のセッションのJSONLを特定する」手順で自分のセッションファイルを開いて補完してよい。

迷ったら入力なし＝現在セッションと解釈する。「振り返って」「reflection」だけ言われたら基本これ。

Step 2: correction episode を抽出する（過去ログモードのみ／重いのでサブエージェントに委譲）

このステップは Step 1 で ディレクトリが渡された過去ログモード のときだけ実行する。現在セッションモードなら飛ばして Step 3 へ進み、文脈中の対話からそのまま episode を拾う。

セッションのJSONLから、人間のテキスト発話と Claude(assistant)のテキスト出力を時系列のまま 取り出す（tool_use / tool_result の本体やメタ行は除外）。人間側だけ抜くと「何に対する指摘か」が消えて反省にならないので、必ず両者を並べる。jq で抽出できる（python3 はこの環境では使えない）。全 worktree 分は嵩むので、抽出と一次蒸留は sonnet などの軽量モデルのサブエージェントに委譲し、メインの文脈を汚さない。jq コマンドと委譲プロンプトの雛形は references/mining.md にある。

サブエージェントに拾わせるのは次の2種類:

• 指摘エピソード — 人間が修正/軌道修正/ダメ出し/好みを入れた箇所と、その直前にClaudeが提案・実装した内容のペア。単なるタスク依頼（「Xを実装して」）は対象外。
• Claude自身のつまずき — 人間の明示的なダメ出しが無くても、Claudeが誤った前提で進めた・手戻りした・無駄な遠回りをした・自己訂正した形跡。ここにも再発防止の教訓がある。

各エピソードについて「Claudeは何をしたか / なぜそれが不味かったか / そこから言える一般的な教訓」を返させる（一般 / プロジェクト固有の判別つき）。

Step 3: 候補を原理原則に仕上げる

過去ログモードならサブエージェントの一次蒸留（PART B）を、現在セッションモードなら文脈から直接読み取ったエピソードを、信条1に照らして磨く。各原則は 「Claudeが本来どう振る舞うべきだったか」を述べる一文 + 短い理由 の形にする（人間が何と言ったかの転記ではない）。似たエピソードはまとめ、事象の羅列ではなく一文の主張にする。

Step 4: 行き先を決めて振り分ける（信条3）

各候補について、まず行き先を判定する。

• 一般化できる（具体を剥がしても転用可能な原則が残る）→ グローバル候補。
• そのプロジェクト固有だが、寄り道・つまずきの再発防止に効く（その事実を知っていれば遠回りを避けられた）→ プロジェクト候補。
• どちらでもない（一度きりの語感の好み、再発しない偶発事など）→ 捨てる。

そのうえで各行き先の中で、次の2点でさらに絞る。

• 再発性 — 繰り返しうる「ミスの類型」か。一度きりの偶発は除く。
• 既出でない — その行き先の現行ルール（グローバル候補なら ~/.claude、プロジェクト候補なら対象リポジトリの既存ルール）でまだカバーされていないか。

Step 5: 既存ルールへ統合する（信条2を実践）

Skip / Sharpen / Absorb / Add の判断は両方の行き先で共通して効く。まず対象の現行ルールを読んでから当てる。

5a. グローバル候補 → ~/.claude（claude/CLAUDE.md と claude/rules/*.md） 配置の指針:

• 横断的な設計姿勢（complete実装・設計忠実性・ステートレス設計・公開ポリシーなど）→ CLAUDE.md
• 言語/領域に固有（Go・フロントエンド・テスト・完了チェックなど）→ 該当する rules/<domain>.md
• 既存ファイルに馴染まない新ドメイン → rules/<domain>.md を新設（CLAUDE.md は膨らませない）

5b. プロジェクト候補 → 対象リポジトリの .claude/

• 対象リポジトリの解決 — ディレクトリ指定モードならそのリポジトリルート。現在セッションモードなら現在の作業ツリー。
• 既存の置き場所に合わせる — そのリポジトリが root の CLAUDE.md / .claude/CLAUDE.md / .claude/rules/ のどれを使っているか確認し、それに倣う。無ければ、横断的な事情は .claude/CLAUDE.md、特定領域は .claude/rules/<topic>.md に新設する。
• worktree 越境の禁止 — worktree の中にいるとき、メインリポジトリや別 worktree の .claude/ を直接書き換えない。現在の作業ツリー内の .claude/ に書き、通常の commit/merge で本体へ運ばせる。指定モードで別リポジトリが対象なら、それも Step 6 の承認を得てから触れる。
• 固有知識なので具体は剥がさないが、それでも信条2（肥大させない）は効く。既存のプロジェクトルールと重複・矛盾しないか確認してから足す。

統合後、変更した各ファイルの行数を before/after で確認する。純増が大きい、または特定ファイルが焦点を失って長大化しているなら、重複・陳腐化・過剰に具体的な記述を畳む 整理パス を同じ実行内で行う。

ルール本文は 英語 で書く（グローバル・プロジェクトとも。既存ルールに合わせる。Claudeが最も正確に解釈でき、多言語チームでも共有しやすい）。ユーザーとの対話は日本語で行う。

Step 6: 提案して、承認を得てから適用する

グローバルルールは全プロジェクトに、プロジェクトルールはそのチーム全員に影響する。勝手に書き換えない。グローバルとプロジェクトを分けて 次をユーザーに提示する:

• 採用した教訓と、その行き先（グローバル / どのリポジトリのプロジェクトルール）、当てた戦略（Skip/Sharpen/Absorb/Add）、配置先ファイル
• 捨てた候補とその理由（一度きり・既出 など）
• 変更の diff と、ファイルごとの before/after 行数

承認を得てから書き込む。既存の意図を壊していないか、worktree 越境していないか、最後にもう一度確認する。