learn

会話から学ぶ

会話を分析して得られた教訓を抽出し、AI アシスタントの設定ファイルまたは新しいスキルに保存します。

引数

学習対象を絞り込む任意のテキストです（例：sandbox workaround、that build fix）。

$ARGUMENTS が help、--help、-h、または ? の場合は、ワークフローをスキップして references/options.md を読みます。

$ARGUMENTS が空でないヘルプ以外の文字列の場合は、ステップ 2 でフォーカスフィルターとして使用し、指定されたトピックに関連する学びのみを提示し、無関係な調査結果はスキップします。

プロセス

1. 設定と既存のスキルを検出する

for f in CLAUDE.md GEMINI.md AGENTS.md .cursorrules .github/copilot-instructions.md \
  .windsurf/rules/rules.md .continuerc.json; do
  [ -f "$f" ] && wc -l "$f"
done
find .cursor/rules -name "*.mdc" -exec wc -l {} \; 2>/dev/null
find . -name "SKILL.md" -type f 2>/dev/null | grep -v node_modules | \
  xargs grep -l "^name:" | while read -r f; do grep -m1 "^name:" "$f" | sed 's/name: //'; done

設定の検出：

• 設定が 1 つ見つかった場合 → それを使用します
• 複数の設定が見つかった場合 → 続行する前に、必ず references/multiconfig-routing.md を最後まで読むこと
• 設定が見つからない場合 → 初期化コマンドを提示するために、必ず references/assistant-configs.md を最後まで読むこと。その後、終了します。この段階では refactoring.md、options.md、multiconfig-routing.md を読み込まないでください。

設定ファイルのサイズしきい値：

• 400 行未満：問題ありません。そのまま追加します
• 400～500 行：慎重に追加し、ファイルが大きくなってきていることを伝えます
• 500 行超：続行する前に、必ず references/refactoring.md を最後まで読むこと。その後、リファクタリングを提案します。この経路では、Route A の変更も適用する場合を除き、assistant-configs.md を読み込まないでください。

2. 会話を分析する

既定では採用しません。候補となる学びはそれぞれ、次の 3 つのフィルターを順番に通過する必要があります。

1. これは忘れてしまうでしょうか？ 開発者なら誰でもすでに知っていること（npm install の後に npm start を実行する、ブランチを切り替える前にコミットする、エラーを注意深く読むなど）はスキップします。基本的な知識を設定に加えると内容が薄まり、エージェントが読み飛ばすようになります。
2. これはすでに記載されていますか？ 設定内の項目を検索してトピックを確認します。見つかった場合は、ルールをもう 1 つ追加するより、既存の文言を強化するほうが適切です。
3. これは普遍的なものですか、それともローカルなものですか？ 環境固有の回避策（壊れたキーリング、特定のリポジトリのツールに関する癖など）をグローバルなルールにする場合は、適用範囲を明記する必要があります。

3 つすべてを通過した候補のみ、次の種類に分類します。

• 修正：フラグや環境変数を変更してコマンドを再試行した、誤った前提を訂正した
• 発見：文書化されていない動作、連携上の癖、環境要件
• ワークフロー：セッション中に考案され、繰り返し実行すべき複数手順のパターン
• 指示違反：設定にすでに記載されていることをユーザーが改めて指摘する必要があった場合は、新しいルールを追加するのではなく、文言を強化する必要があるかもしれません
• 矛盾：この学びは既存の内容と矛盾するか、既存の内容に優先しますか？ ユーザーが矛盾を指摘していなくても、追加ではなく置き換えの対象としてフラグを立てます

フィルターを通過するものが何もない場合は、目新しい発見はなかったとユーザーに伝えて終了します。実行を正当化するために学びを捏造しないでください。

3. 各学びの保存先を決める

各学びについて、誰かが名前を指定して呼び出すでしょうか？ と考えます。ユーザーが「[X] ワークフローを実行して」と言う場面を想像できるなら、それはスキルです。そうでなければ、設定項目です。

1. これはワークフローとして実行する複数手順の手順書ですか？ 学びに順番に実行する 3 つ以上の番号付きステップがある場合、プロジェクト固有であっても、新しいスキルにします。デプロイのチェックリスト、リリース手順書、「X を追加する」ワークフローはいずれもスキルです。単一の事実や注意点は設定項目です。該当する場合 → Route C（新しいスキル）。
2. このトピックを扱う既存のスキルがありますか？ → Route B（そのスキルを更新）。
3. 設定ファイルが大きすぎますか（500 行超）？ → Route C またはリファクタリングを提案。
4. それ以外 → Route A（設定ファイル）。

最も明確な判断基準：実行に 1 つを超えるコマンドが必要なら、おそらくスキルです。覚えておくべき単一の事実なら、設定項目です。

4. クロス設定の同期ルールを保持する

対象範囲：Markdown ベースの設定のみ — CLAUDE.md、GEMINI.md、AGENTS.md、.github/copilot-instructions.md、.cursorrules、.windsurf/rules/rules.md。対象外：.cursor/rules/*.mdc と .continuerc.json（Markdown 以外の形式です。これらのミラールール検出は今後の対応です）。

Markdown の対象範囲内で、複数の設定ファイルが存在する場合：

1. 検出：検出した各設定ファイルで、ミラールールのテキストを探します。たとえば、別の設定ファイル名の近くにある keep ... in sync、mirror ... to、apply the equivalent change to のようなパターンです。
2. ステップ 1 の選択を尊重します。ユーザーが選択した設定ファイルのみを操作します。選択されていない設定ファイルにあるミラールールを理由に、対象を広げてはいけません。ユーザーは意図的に対象を絞っている可能性があります（例：Copilot ファイルはスタイルに限定されている）。
3. 保持：編集のたびにミラールールのテキストを残します。セクションを書き換える際に、ミラールールを上書きしてはいけません。
4. 相互に追加：選択された設定ファイルに、他の選択された設定ファイルへの参照を含むミラールールがない場合は、追加します（例：.github/copilot-instructions.md に相互ルールがない場合、ファイルの先頭に Keep CLAUDE.md in sync: mirror rule changes back to CLAUDE.md を追加します）。

**理由：**ミラールールは不可欠です。今後のセッションで設定ファイルを同期し続ける方法を示します。一方の設定ファイルだけを黙って更新したり、書き換え時にミラールールを削除したりすると、設定ファイル間に食い違いが生じ、ルールも失われます。ただし、対象を絞ることが妥当なケースは多いため、ユーザーの選択は引き続き優先されます。

5. ルールのテキストを監査する

作成した各ルールを文の区切りとエムダッシュの区切りで分割します。各断片について、ルール、修正、明白でない理由、具体例のどれに当たるかを明示するか、削除します。インシデントの説明、複数の節からなる根拠、トリガーの言い換えは、このチェックを満たしません。

結果を次のステップの Cut in audit: 行に記録します。下書きが最小限かどうかをユーザーが尋ねる必要があるなら、監査が不十分だったのではなく、実施されていません。

6. 計画を提示して確認を待つ

計画を示す前に、根底にある観察内容が同じ候補を重複排除します。2つの候補が、異なる経路で同じ事実を述べている場合（例：CLAUDE.md の箇条書きとスキル参照ルール、または採用候補と、同じ観察内容に対する「却下された別経路」）、経路を1つだけ選び、他は除外します。同じ事実について、却下した別経路を計画や却下リストに別項目として列挙してはいけません。1つの観察内容につき、1行です。

実施予定の内容をすべて示します。

**[Category]**: [Brief description]
- Source: [what triggered this learning]
- Proposed change: [exact text to add, post-audit]
- Cut in audit: [clauses cut, or "none" + one-word defense per kept clause]
- Destination: [file] ([current lines] → [projected lines])

学習事項が複数ある場合はすべて列挙してから、次のように尋ねます。

Ready to apply. Approve all, or review each one?

このステップでユーザーが応答するまで、ファイルを変更してはいけません。

7. 変更を適用する

経路 A — 設定ファイル（CLAUDE.md、GEMINI.md など）：書き込み前に、書式とセクションの規約について references/assistant-configs.md を必ず全体を通して読むこと。この経路では、ファイルが 500 行を超える場合を除き、refactoring.md を読み込んではいけません。追記する前に、既存の設定ファイルで関連する内容を検索します。見つかった場合は、重複する項目を追加するのではなく、既存箇所の更新を提案します。新しいルールが既存のルールと矛盾する場合は、要約でその衝突を明示します（原則 4）。次に適切なセクションを特定し、既存の構成を保ったまま追記するか、セクションを作成します。書き込みのたびに、ステップ 4 の同期ルールの保持を適用します。

経路 B — 既存のスキル：skills/[name]/SKILL.md を読み、関連するセクションに追記し、既存の構成を維持します。

経路 C — 新しいスキル：skills/[name]/SKILL.md を作成します。description フィールドによって、スキルが実際に有効化されるかが決まります。スキルが何をするのか、いつ使うのかを明記し、トリガーとなるキーワード（動作を表す動詞、ファイル形式、分野の用語）を含める必要があります。「デプロイを支援する」のような曖昧な説明では、スキルは有効化されません。

---
name: [topic]
description: [WHAT it does + WHEN to use it + trigger keywords]
---

# [Topic]

## Process

### 1. [First Step]
[Details]

8. 要約

変更したファイルを、変更前後の行数、更新または作成したセクション、作成したスキルがあればその名前とともに列挙します。矛盾を解決した場合は、どのルール同士が矛盾し、どちらを採用したかを明記します。設定間の同期ルールを守った場合（維持または相互反映した場合）も、その旨を記載します。

このセッションで報告した Issue。 セッション中のツール呼び出し履歴を確認し、gh issue create の実行と、セッション中に出力された https?://github\.com/[^/]+/[^/]+/issues/\d+ に一致する URL を探します。Issue が報告されていた場合は、このセッションで報告した Issue という小見出しの下に、Issue ごとに箇条書きで記載します。

### Issues filed this session
- #301 — CI: split verify-pr.yaml into per-stack workflows
  https://github.com/owner/repo/issues/301

報告された Issue がなければ、小見出しも省略します。重複を除外する際は、(owner, repo, number) の組（または正規化された Issue URL）を使います。複数のリポジトリに関わるセッションでは、同じ Issue 番号でも owner/repo のパスが異なることがあるため、番号だけで重複を除外すると無関係な Issue が誤って統合されます。タイトルをセッションの出力から復元できない場合は、「— 」の部分を省略し、URL を記載します。

原則

1. ノイズを排除し、見落としにくい学びだけを含めます。 肥大化した設定は、エージェントが読み飛ばす原因になります。開発者なら誰でも知っていること（「npm start の前に npm install を実行する」「ブランチを切り替える前にコミットする」など）は省略し、ユーザーが必要に応じて再検討できるよう、除外した項目を伝えます。
2. 適用範囲を明記し、一度限りの修正を一般化しません。 今日うまくいった回避策が、環境の異なる次のセッションで問題を引き起こすことがあります。修正のきっかけとなった条件（壊れたキーリング、特定の macOS バージョン、このリポジトリ固有のビルド上の問題など）を示し、今後のエージェントが適用するかどうか判断できるようにします。「常に Z を使う」のような無条件の表現ではなく、「X が失敗した場合」や「Y の代替策として」のような条件を付けます。
3. 1 つのトピックは 1 か所に記載します。 ルールが設定やスキルのどこかにすでにある場合は、その記述を更新します。同じトピックについて 2 つの項目があると曖昧になり、エージェントが先に読んだ弱い方に従う可能性があります。別の箇条書きを追加するより、既存の記述を強化します。
4. 矛盾を明示し、黙って重複させたり置き換えたりしません。 学びが既存の内容と矛盾する場合は、計画と要約で矛盾を明記したうえで置き換えを提案します（「理由 Y により、既存のルール X を置き換えます」）。黙って置き換えると、ルールが変更されたことにユーザーが気づけません。黙って重複させると、エージェントがどちらを先に読むかによって一貫しない動作をします。
5. 必要最小限のルール文にします。 すべての節に、ルール、修正、見落としやすい理由、または具体例のいずれかが必要です。下書きの後、「これが最小限の文字数か？」と見直します。根拠を説明できない節は削ります。シェルの終了動作について段落で説明するより、`cd dir && cmd`（`cd` が失敗すると `cmd` は実行されません）の方が簡潔です。事例の説明や複数の節からなる影響は、ルール本文ではなくコミットメッセージに記載します。

曖昧な学びは絶対に書きません。 「デプロイには注意してください」では何も学べません。「CDN キャッシュが壊れたアセットを隠すため、本番環境への反映前にステージング環境でスモークテストを実行する」のように、実行可能で理由も説明した内容にします。この禁止事項だけは、他のすべての原則に不可欠な要素が具体性であるため、例外なく守ります。