self-improvement

自己改善

このスキルには 2 つのモードがあります。

1. 受動的な記録（常に有効で、スキルの呼び出しは不要） — すべてのエラー、修正、提案、学びは、発生した時点ですぐに ~/.learnings/ に記録されます。これは CLAUDE.md を通じて Claude の動作に組み込まれており、このスキルを起動する必要はありません。

2. 能動的なレビューと昇格（/self-improvement で起動） — 蓄積された学びを確認し、価値のあるものを CLAUDE.md に昇格させ、GitHub の PR／Issue を分析し、セッション終了時の振り返りを行います。昇格はここでのみ行われ、自動では行われません。

ログファイル

~/.learnings/ に、構造化された Markdown ファイルを 5 つ保持します（存在しない場合は作成してください）。

• ~/.learnings/LEARNINGS.md — 修正、知識の不足、ベストプラクティス、提案
• ~/.learnings/ERRORS.md — コマンドの失敗、例外、予期しない動作
• ~/.learnings/FEATURE_REQUESTS.md — ユーザーから依頼されたものの、提供できなかった機能
• ~/.learnings/CHANGELOG.md — CLAUDE.md への昇格（および取り消し）をすべて記録する、恒久的な追記専用の記録
• ~/.learnings/ARCHIVE.md — レビュー済みのすべての項目（昇格または見送り）を移動します。ユーザーが明示的に確認を求めない限り、コンテキストには読み込まれません。

受動的な記録（常に有効）

すべてのエラー、修正、提案、学びは、例外なく、価値があるかどうかを判断することなく、すぐに記録されます。目的は完全な記録を作ることです。後のセッションで取捨選択できるため、このセッションの役割は記録することです。

すぐに記録してください。許可を求めたり、作業の切れ目を待ったりしないでください。出来事の直後が最も文脈を把握できています。記録した後、何を記録したかをユーザーに簡潔に伝えてください（例：「ポートの競合を ERRORS.md に記録しました」）。くどくど説明する必要はありません。

記録項目の対象

• ユーザーによる修正：「実際にはこうするべきです……」「いいえ、そうしないでください……」「それは……なので間違っています」→ LEARNINGS.md
• 知識の不足：古い情報を伝えた、プロジェクトの規約を見落とした、または修正を受けた → LEARNINGS.md
• 提案：ユーザーがより良い方法、ツール、パターンを提案した → LEARNINGS.md
• コマンド／ツールの失敗：シェルコマンドの失敗、API 呼び出しのエラー、ファイル操作が想定どおりに動作しなかった → ERRORS.md
• 機能リクエスト：ユーザーから依頼されたものの、実行できなかったこと → FEATURE_REQUESTS.md
• 繰り返し発生するパターン：同じセッション内で同じミスを複数回した → LEARNINGS.md（優先度を高に引き上げる）

記録不要の項目

• 再発しないタイプミスや、些細な自己修正
• 一時的な状況（ネットワークの瞬断、サーバーの一時的なダウン）が原因の失敗
• プロジェクトの CLAUDE.md に、まったく同じ詳細がすでに記載されている事項

エントリー形式

各エントリー ID には、セッション間およびプロジェクト間での重複を避けるため、6 文字のランダムな 16 進数ハッシュ（例：a3f7c1）を使用します。記録時にハッシュを生成してください。ランダム生成や SHA の一部の使用など、6 文字の 16 進数であれば、どの方法でも構いません。

LEARNINGS.md

## [LRN-a3f7c1] Short descriptive title
- **Timestamp**: ISO-8601
- **Priority**: low | medium | high | critical
- **Status**: pending | promoted
- **Area**: frontend | backend | infra | tests | docs | config | workflow | other
- **What happened**: Brief description of the correction or gap
- **Lesson**: The concrete takeaway
- **Source**: e.g., "User correction in conversation", "PR #42", "Issue #17"
- **Suggested fix**: Specific action or rule change

ERRORS.md

## [ERR-b2e9d4] Short descriptive title
- **Timestamp**: ISO-8601
- **Priority**: low | medium | high | critical
- **Status**: pending | resolved
- **Area**: (same categories as above)
- **Command/action**: What was attempted
- **Error**: The failure message or description
- **Root cause**: Why it failed (once known)
- **Fix**: What resolved it or what to do differently next time
- **Reproduction**: Steps to reproduce (if useful)

FEATURE_REQUESTS.md

## [FEAT-c8d2a5] Short descriptive title
- **Timestamp**: ISO-8601
- **Priority**: low | medium | high | critical
- **Status**: pending | implemented | promoted
- **Area**: (same categories)
- **Request**: What the user asked for
- **Context**: Why they needed it, what they were trying to accomplish
- **Workaround**: What was done instead, if anything

昇格（/self-improvement からのみ実行）

昇格とは、すべての将来の会話で引き継がれるよう、知見を CLAUDE.md ファイルに書き込むことです。昇格は自動では行われず、ユーザーが明示的に /self-improvement を実行し、昇格する内容を確認した場合にのみ行われます。

これは意図的な仕様です。自動昇格すると CLAUDE.md が肥大化し、望まない項目が追加される可能性があります。何を恒久的な指針とするかは、常にユーザーが関与して決めるべきです。

ユーザーが /self-improvement を実行したとき

1. ~/.learnings/ から保留中のエントリーをすべて読み込みます（ステータス：pending）
2. 昇格する価値のある候補の概要をテーマ別にまとめて提示します
3. 候補ごとに、昇格に値する可能性がある理由と、昇格先を説明します
4. 各候補について、ユーザーが承認、却下、または修正するまで待ちます
5. ユーザーが明示的に承認したものだけを昇格します
6. 確認したエントリーをすべてアーカイブします — 昇格したエントリーも見送ったエントリーも ~/.learnings/ARCHIVE.md に移動し、元のファイルから削除します（下記の「アーカイブ」を参照）

昇格の基準（推薦時）

次の条件に当てはまるエントリーの昇格を提案します。

1. 幅広く適用できる — 1つの会話やファイルにとどまらず適用できる
2. 再発する可能性が高い — 今後、Claude が同じ問題に遭遇する可能性が十分にある
3. まだ文書化されていない — まず昇格先の CLAUDE.md を確認します

昇格先

プロジェクトの CLAUDE.md（プロジェクトのルート） — プロジェクト固有の規約、パターン、注意点向けです。

ユーザーの CLAUDE.md（~/.claude/CLAUDE.md） — プロジェクトにかかわらず適用される、プロジェクト横断の知識向けです。

目安：「まったく別のプロジェクトでも役立つか？」はい → ユーザーの CLAUDE.md。いいえ → プロジェクトの CLAUDE.md。

昇格方法（ユーザーの承認後）

1. 適切なセクションを探すため、昇格先の CLAUDE.md を読み込みます（必要に応じてセクションを作成します）
2. 簡潔で自己完結したエントリーを記述します — 元の会話がなくても理解できる内容にします
3. ~/.learnings/CHANGELOG.md にエントリーを追記します（下記の形式を参照）
4. 元のエントリーをアーカイブします（下記の「アーカイブ」を参照）
5. 何をどこに昇格したかをユーザーに伝えます

確認したエントリーのアーカイブ

/self-improvement で確認したエントリーはすべて、昇格したか見送ったかにかかわらずアーカイブします。これにより、アクティブな学習ファイルを未確認のエントリーだけに絞りつつ、完全な履歴を保存できます。

1. 元のファイル（LEARNINGS.md、ERRORS.md、または FEATURE_REQUESTS.md）からエントリー全体を ~/.learnings/ARCHIVE.md に移動します
2. アーカイブしたエントリーに - **Disposition**: promoted to <target> | skipped (<reason>) フィールドを追加します
3. 元のファイルからエントリーを削除します

アーカイブは追記専用で、ユーザーが明示的に求めない限り（例：「アーカイブを見せて」「前回何を見送った？」「アーカイブで X を検索して」）、コンテキストに読み込まれません。これにより、コンテキストウィンドウが消費されるのを防ぎます。

昇格変更履歴

昇格はすべて ~/.learnings/CHANGELOG.md に記録します — 永続的な追記専用の監査記録です。

## [PROMO-f4a8e2] Short title matching the source entry
- **Timestamp**: ISO-8601
- **Source**: LRN-a3f7c1 (or ERR-, FEAT- reference)
- **Target**: project CLAUDE.md | user CLAUDE.md (~/.claude/CLAUDE.md)
- **Section**: Which section of the target file it was added to
- **What was promoted**: The exact text or a close summary of what was written
- **Why**: One sentence on why this deserved promotion

変更履歴のエントリーを編集または削除してはいけません — 昇格が誤りだと判明した場合は、削除した内容と理由を説明する新しい [REVERT-<hex>] エントリーを追加し、その後、昇格先の CLAUDE.md から該当項目を削除します。

昇格するエントリーは簡潔に保ちます。必要であれば具体例を添え、1〜2文に要約します。

昇格してはいけないもの

• 一時的な状況に対する一度限りの回避策
• 単一ファイルまたは狭い範囲のコンテキストに固有のもの
• 修正内容にすでに含まれているデバッグ手順（コード自体が記録になります）
• 昇格先の CLAUDE.md にすでに記載されているもの（必ず先に確認してください）

GitHub の PR と Issue から学ぶ

ユーザーから GitHub の履歴（PR、Issue、ディスカッション）をもとに学ぶよう依頼された場合は、gh CLI を使ってパターンを分析します。

# Fetch closed PRs with review comments
gh pr list --state closed --limit 50 --json number,title,reviews,comments

# Look at a specific PR's review feedback
gh pr view <number> --json reviews,comments,body

次の内容を抽出します。

• 繰り返し寄せられるレビュアーからの指摘 → LEARNINGS.md に追加する教訓
• 却下されたアプローチ（およびその理由）→ 避けるべきパターン
• Issue でよく見られるバグのパターン → ERRORS.md に追加するエントリー
• 頻繁に要望される機能 → FEATURE_REQUESTS.md に追加するエントリー

一度限りの事例ではなく、複数の PR／Issue で見られるパターンに重点を置きます。エントリーには必ず出典となる PR または Issue の番号を記載します。

原則

すべてを記録し、選別して反映します。 エラー、訂正、提案、学びはすべて記録します。フィルタリングしたり、重要度を判断して除外したりしません。ログは完全な記録です。CLAUDE.md への反映は選別して行う手順であり、ユーザーから依頼があった場合にのみ実施します。

曖昧ではなく、具体的に書きます。 「非推奨の API を使わないでください」では役に立ちません。「このコードベースでは os.path.join を使わないでください。すべての箇所で pathlib.Path を使用しています（utils.py を参照）」なら役に立ちます。

理由を記録します。 未来の Claude は背景を覚えていません。元の会話がなくても理解できるよう、教訓はそれだけで意味が通じる形にします。

関連する項目をリンクします。 エラーが学びや機能リクエストに関連する場合は、相互に参照できるようにします。

確認を求めずに記録し、許可を得て反映します。 記録は自動で手間がかかりません。記録して、ユーザーに簡潔に伝えるだけです。反映には、/self-improvement によるユーザーの明示的な承認が必要です。