learning

name	learning
argument-hint	[記録したい学び / 補足]
description	Extract lessons that make next time easier. Firing means invoking this skill now, mid-turn — naming it in the closing next-action list does not count as firing it. Fire when: (1) a reusable insight emerges at a work boundary — a bug workaround found, a gotcha cleared, the right procedure/command/config figured out after trial and error, a tip for avoiding a repeated mistake. (2) a session wraps up — review the whole session and extract its lessons.
summary	「次回から楽になる学び」を抽出するスキル。呼び出すとは今すぐ実行することを指す—— 会話末尾のネクストアクション欄に挙げるだけでは呼び出したことにならない。以下の状況で呼び出す: (1) 再利用できる知見が出た区切りで実行する。具体的には、バグの回避策が分かった / ハマりどころを抜けた / 試行錯誤の末に正しい手順やコマンド・設定の使い方が判明した / 同じ失敗を繰り返さないコツに気づいた、といった場面。 (2) セッションの締めにも実行し、セッション全体を振り返って学びを抽出する。

Learning

作業の区切り、またはセッション全体を振り返り、次回から楽になる学びを抽出して、その汎用性（どこまで通用するか）に応じた置き場へ記録するスキル。

なぜやるか: ここに置いた学びは、次に同じ状況へ出会ったとき（自分や他のエージェントが）参照され、調べ直しややり直しの時間を減らす。だから「次に時間を節約できる知見」を、汎用性に応じた正しい置き場へ置く。

このスキルが属する複利エンジニアリング全体（汎用性1軸の思想・置き場・サイクル）の地図は README.md を参照。

ユーザからの補足（あれば考慮する）: $ARGUMENTS

プロセス

0. セットアップ

複利エンジニアリングのプロジェクト置き場を用意する。毎回このステップを通る。

まず存在ゲートと決定論的セットアップをスクリプトに任せる:

~/.claude/skills/learning/scripts/setup.sh

スクリプトは repo-local（<repo>/.learnings/index.md）の有無を判定し、不足分だけをテンプレからコピーする（既存は上書きしない・冪等）。CLAUDE.md には触れない。

出力が all set なら、この節はここで終わり。ACTION NEEDED (model) が出たら、その項目だけを次の要領で対応する（出るのは今回作成した分のみ）。

• [repo] 作業サイクル節の追記 — repo の CLAUDE.md に「作業サイクル」節が無ければ assets/templates/project/cycle-section.md の内容をそのまま追記する。この節は @.learnings/index.md（backtick で囲まない）の常時ロード指定を含むので、これ1つで index の自動ロードも成立する。既存 CLAUDE.md の編集はユーザに確認してから行う。追記時、その repo で使える review / refactor / test 系 skill（例: self-code-review, tdd-refactoring）を該当ステップに紐づける。該当 skill が無ければ汎用テンプレのまま残す。

1. 対象を振り返る

振り返りの対象（今回の作業の区切り、またはセッションの締めならセッション全体）で何をしたかを整理する。

• 実施した主な作業内容
• 変更したファイルや機能
• 直面した課題や解決した問題
• 使用したツールや技術

2. 抽象化フェーズ

具体的な作業内容から、汎用的な学びや知見を抽出する。

原則:

• 局所最適化にならないよう、システム全体との整合性・バランスを意識する。
• ただし、具体的で細かい内容でも重要なものは例外的に拾う。
• すでに記録済みの内容は重複させない。

拾う観点の例: 設計上の判断基準や理由 / 技術選定の背景 / 陥りやすい落とし穴とその回避方法 / パフォーマンス・セキュリティ上の考慮 / 開発効率を上げる手法 / バグの回避策・正しい手順やコマンド・設定の使い方。

3. 保存先の判断（蒸留）

抽出した学びごとに、それが成り立つと確信できる範囲だけを見て保存先を1つ選ぶ。判定に汎用性以外の要素（surface のしやすさ等）を混ぜない。

汎用性	保存先
あらゆる作業で効く普遍的な話	グローバル CLAUDE.md（実体 ~/.claude/CLAUDE.md）
特定領域における普遍的な話	skill（新規作成 or 既存 skill へ追記）
プロジェクト固有だが再利用性のある話	<repo>/.learnings/（index.md ＋ <slug>.md）

• グローバル CLAUDE.md だけは追加のゲートを通す。汎用性の判定で行き先が「あらゆる作業で効く普遍的な話」になっても、それだけでは昇格しない。全セッションに常時ロードされる最も高価な層なので、「無いと明確に損をする」と言えるものに限る。「あると良い」程度なら1段下（skill）へ落とす。損の言明はプロセス4の失敗シナリオ3点で確かめる。
• 手順の形をした学びを取りこぼさない。「次に同じ状況が来たらこの手順をなぞる」と言えるものは、たいてい「特定領域における普遍的な話」に当たる。断片的に見えても 2〜3 ステップで skill にする価値があり、複数の学びが1つの手順の別々の断片になっている場合はまとめて1つの skill として切り出す。散文で書くと読めても実行できる形にならない。skill 化すべきか迷ったものは、skill 候補としてプロセス4の承認に載せてユーザーの判断を仰ぐ。
• 新規 skill 化はサブエージェントに委譲する。skill 作成は手順が多くコンテキスト消費が大きいので、skill-creator を使うサブエージェントへ「何を・どんなトリガ（description）で引ける skill にするか」を渡して任せる。
• 同じ学びに再遭遇したら、再記録しない。それは既存の学びが使用時点に surface していない（＝効いていない）というループの故障。なぜ surface しなかったか（配置ミス／skill の description が弱い／index 要約が悪い 等）を診断し、根本を直す。

4. 承認と反映

AskUserQuestion ツールを使い、メニュー形式で候補を提示する。

承認を求めるときは、分類（「昇格するか・行き先はどこか」）ではなく書き込まれる成果物を見せる。追加先によって判断に要る情報が違う。

追加先	必ず添えるもの
グローバル CLAUDE.md	追記する literal な行 / どの節に入るかと前後の既存項目 / その節の他項目と scope が揃っているか
プロジェクト CLAUDE.md	同上（節と前後）
skill	どの skill の・どの手順に入るか / 既存手順との重複
<repo>/.learnings/	新規ファイルか既存の精密化か / 隣接する既存エントリ名

いずれの場合も、期待効果を失敗シナリオの形で書く:

1. この記述が無いと、どの場面で・どう間違うか（利益の言明ではなく、具体的な誤りの筋書き）
2. その誤りは実際に起きたか（今回の観測・過去の実例）
3. 既存のどれも止められないと言える根拠（該当箇所を名指しする）

3つを具体的に書けないなら昇格しない合図。特に 2 で「実際には正しく振る舞えていた」なら、その記述は効いていない。

ユーザが選択した候補のみを反映する。グローバル CLAUDE.md への追記と skill の新規作成・追記はグローバル資産の変更なので、必ずこの承認を経てから行う。

.learnings/<slug>.md に置く学びは を既定として書き、.learnings/index.md へ次の形で1行だけ追記する。グローバル CLAUDE.md / skill へ置く場合は、その保存先の慣習に従う。

- `<slug>.md` — <本文の主見出し>

見出しをそのまま写し、要約を別に書かない。index は常時ロードされる固定費なので1行の長さがそのまま全セッションに効くうえ、写しであれば索引は本文に無いことを書けない（要約だけが精密化されて本文と食い違う事故が起きない）。裏返しに、見出し自体が単体で想起トリガーになるよう書く必要がある — 何をすべきか・何を疑うべきかが見出しだけで分かる形にする。主見出しとは、slug のエコーや「学び」「根拠」のような汎用節名を除いた最初の見出しを指す（階層は問わない）。

既存の別形式（— タイトル — 1行要約 の行や、 に沿わない本体）は有効なものとして扱い、書き換えない。新しく足す行だけを上の形にすればよく、混在してよい。

```markdown ### タイトル

学び: 何が効くか / 何を避けるか

根拠: いつ・どこで分かったか

適用範囲: どんな場面で使えるか

例外・前提: 使えない場面・前提条件

</learning-entry-format>

### 5. 報告する

今回 記録した学びを、保存先とあわせて一覧でユーザに報告する。

## 重要事項

- このセッション（または今回の区切り）で新たに得られた知見のみを抽出する。既に記録済みの内容は除外する。
- **セッション限りの通り名を持ち込まない**。学びは当時の議論を知らない読者が読むので、その場で流通した比喩・略称・造語は、指すものが分かる表現へ置き換える（比喩は文脈が消えると意味を失い、数値だけが独り歩きする）。数値を引くなら分子・分母・対象範囲を添え、対象や分母が違う集計同士を倍率で並べない。
- 将来の作業で役立つ情報を優先する。Less is More の原則に則り、簡潔で本質的な内容に絞る（一度に詰め込まず数件まで）。
- 似た学びが2つあれば1つに統合する。
- 後で誤りと分かった学びは消さず、「撤回: 理由」を追記して残す（同じ失敗を繰り返さないため）。