self-improvement

自己改善スキル

継続的に改善できるよう、学びやエラーを Markdown ファイルに記録します。コーディングエージェントは後からこれらを処理して修正に活用でき、重要な学びはプロジェクトのメモリに昇格されます。

インストールコマンドについては、references/installation.md を参照してください。エージェントの有効化やフックの設定（任意）については、references/hooks-setup.md を参照してください。これらはスキルのインストールまたは設定時にのみ読んでください。

self-healing と併用してください： self-healing は実行中の復旧を担う仕組みで、タスクの途中で問題が発生した場合に診断、パッチ適用、検証を行い、.learnings/HEALS.md に HEAL- エントリーを記録します。自己改善（このスキル）は受動的な蓄積と昇格を担うレイヤーで、修正内容、知識の不足、機能リクエストを記録し、繰り返し発生する復旧時の引き継ぎ事項を恒久的なメモリに昇格させます。両者は .learnings/ を共有しますが、異なるファイルに書き込みます。検証の規律は self-healing に、昇格のロジックはここにあります。

クイックリファレンス

状況	アクション
タスクの途中で障害が発生し、エージェントが今すぐ修正する必要がある	代わりに self-healing を使う（検証済みの HEAL- を .learnings/HEALS.md に記録します）
コマンドや操作が過去に失敗した（現在復旧作業中ではない）	.learnings/ERRORS.md に記録します
ユーザーから修正を指摘された	カテゴリーを correction として .learnings/LEARNINGS.md に記録します
ユーザーが不足している機能を求めている	.learnings/FEATURE_REQUESTS.md に記録します
API や外部ツールが失敗した	統合の詳細とともに .learnings/ERRORS.md に記録します
self-healing の引き継ぎブロックが昇格ルールを満たす（下記の昇格ルールを参照）	抽出したルールを CLAUDE.md / AGENTS.md / 新しいスキルに昇格させます
知識が古くなっていた	カテゴリーを knowledge_gap として .learnings/LEARNINGS.md に記録します
より良い方法が見つかった	カテゴリーを best_practice として .learnings/LEARNINGS.md に記録します
繰り返しのパターンを簡素化／堅牢化する	Source: simplify-and-harden と安定した Pattern-Key を付けて .learnings/LEARNINGS.md に記録または更新します
既存のエントリーと類似している	**See Also** でリンクし、優先度の引き上げを検討します
幅広く適用できる学び	CLAUDE.md、AGENTS.md、および／または .github/copilot-instructions.md に昇格させます

セットアップ

プロジェクトのルートに .learnings/ ディレクトリがない場合は作成します：

mkdir -p .learnings

assets/ のファイルテンプレート（LEARNINGS.md、ERRORS.md、FEATURE_REQUESTS.md）をコピーするか、ヘッダー付きのファイルを作成します。

記録形式

学びのエントリー

.learnings/LEARNINGS.md に追記します：

保存する学びには、昇格しない場合でも、記録時に保守用のフィールドをすべて付けます。 references/context-maintenance.md を使用し、不明な点は明示してください。

## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
One-line description of what was learned

### Details
Full context: what happened, what was wrong, what's correct

### Suggested Action
Specific fix or improvement to make

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: simplify.dead_code | harden.input_validation (optional, for recurring-pattern tracking)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

### Context Maintenance
- Decay-Type: reality | decision | dependency | relevance | unknown
- Decay-Rate: fast | medium | slow | durable | unknown (brief basis)
- Authority: source or unknown; Owner: known role or unknown
- Revalidation: method; invalidating triggers; when to check; unavailable-source behavior
- Validation: pending | verified | unresolved; Last-Validated: date or none; Evidence: checked source or none
- Disposition: unassessed | retain | revise | externalize | retire; Application: proposed | applied

---

エラーエントリー

.learnings/ERRORS.md に追記します：

## [ERR-YYYYMMDD-XXX] skill_or_command_name

**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
Brief description of what failed

### Error

実際のエラーメッセージまたは出力

### Context
- Command/operation attempted
- Input or parameters used
- Environment details if relevant

### Suggested Fix
If identifiable, what might resolve this

### Metadata
- Reproducible: yes | no | unknown
- Related Files: path/to/file.ext
- See Also: ERR-20250110-001 (if recurring)

---

機能リクエストのエントリー

.learnings/FEATURE_REQUESTS.md に追記します：

## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 timestamp
**Priority**: medium
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Requested Capability
What the user wanted to do

### User Context
Why they needed it, what problem they're solving

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built, what it might extend

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_feature_name

---

ID の生成

形式：TYPE-YYYYMMDD-XXX

• TYPE：LRN（学び）、ERR（エラー）、FEAT（機能）
• YYYYMMDD：現在の日付
• XXX：連番またはランダムな 3 文字（例：001、A7B）

例：LRN-20250115-001、ERR-20250115-A3F、FEAT-20250115-002

エントリーの解決

問題を修正したら、エントリーを更新します：

1. **Status**: pending を **Status**: resolved に変更します
2. メタデータの後に解決ブロックを追加します：

### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: Brief description of what was done

その他のステータス値：

• in_progress - 作業中
• wont_fix - 対応しないと決定した（解決メモに理由を追加します）
• promoted - CLAUDE.md、AGENTS.md、または .github/copilot-instructions.md に昇格した
• promoted_to_skill - 再利用可能なスキルとして抽出した（「スキルの自動抽出」を参照）

プロジェクトメモリへの昇格

学びが幅広く適用できる場合（一度限りの修正ではない場合）は、恒久的なプロジェクトメモリに昇格させます。

昇格するタイミング

• 複数のファイルや機能に適用できる学び
• すべての貢献者（人間または AI）が知っておくべき知識
• 繰り返し発生するミスを防止するもの
• プロジェクト固有の規約を記録するもの

昇格先

対象	含める内容
CLAUDE.md	すべての Claude とのやり取りに関するプロジェクトの事実、規約、注意点
AGENTS.md	エージェント固有のワークフロー、ツールの使用パターン、自動化ルール
.github/copilot-instructions.md	GitHub Copilot 向けのプロジェクトのコンテキストと規約

昇格の方法

メインエージェントが、学習エントリまたは learning-aggregator のギャップレポートを使ってこの手順を実行します。専用のエージェントプリセットは必要ありません。

1. 適格性と関連性を確認します。 以下の昇格ルールを適用し、 裏付けとなるエントリと関連ファイルを読み、既存の指示を確認します。 ルールがすでに網羅されている場合は、重複させずに既存の対象を記録します。 古くなった根拠や競合するルールは、人間による確認のためにフラグを立てます。 エントリを黙って退けたり、既存のガイダンスを上書きしたりしないでください。
2. パターンを、具体的な文脈を含む実行可能な1～3文に要約します。 適切な対象とセクションを選び、構成と、指示ファイル間で必要な同期を維持します。 昇格によって変更するのは指示であり、アプリケーションコードではありません。
3. 指示を書き込む前に、提案する差分を提示して人間の承認を得ます。 承認された変更のみを適用します。Copilot では、チャットで差分を提示して確認を求めます。 スキルの編集には、以下で説明する明示的な対象範囲を指定した承認が必要です。
4. 昇格後、ソースエントリを更新します。**Status**: promoted を設定し、 **Promoted**: <target files> と Promoted-Date: YYYY-MM-DD を記録し、 ソース ID と Pattern-Key は保持します。適用していない提案を昇格済みとしてマークしないでください。 昇格の承認は、コミットや公開を許可するものではありません。
5. ルールに明確な合否条件がある場合は、eval-creator 用の評価候補としてフラグを立てます。 Pattern-Key、ルール、対象、ソース ID、再発の根拠、アサーション、検証方法を含めます。

ギャップレポートに tracker が含まれている場合は、引き継ぎ時に Pattern-Key として保持します。 インラインの出典情報を使うプロジェクトでは、ルールの上に `` を置くこともできます。不明なフィールドは省略します。トラッカーのコメントは任意です。

昇格時のコンテキスト保守

昇格時に記録時の契約を見直します。利用可能な場合は context-decay を使用します。 メタデータは学習エントリに保持し、指示にはルールまたは検索用ポインターのみを残します。 レビューによって再発状況や適格性が変わることはありません。references/context-maintenance.md を参照してください。 古くなったスキルのガイダンスについては、最初の学習時でも具体的な提案を提示します。 context-decay がなくても、スキルの編集や廃止には明示的な対象範囲を指定した承認が必要です。同じリファレンスを参照してください。

昇格の例

学習（詳細）：

プロジェクトでは pnpm ワークスペースを使用しています。npm install を試しましたが失敗しました。 ロックファイルは pnpm-lock.yaml です。pnpm install を使用する必要があります。

CLAUDE.md 内（簡潔）：

## Build & Dependencies
- Package manager: pnpm (not npm) - use `pnpm install`

学習（詳細）：

API エンドポイントを変更したときは、TypeScript クライアントを再生成する必要があります。 これを忘れると、実行時に型の不一致が発生します。

AGENTS.md 内（実行可能）：

## After API Changes
1. Regenerate client: `pnpm run generate:api`
2. Check for type errors: `pnpm tsc --noEmit`

再発パターンの検出

既存のエントリと似た内容を記録する場合：

1. まず検索します：grep -r "keyword" .learnings/
2. エントリをリンクします：メタデータに **See Also**: ERR-20250110-001 を追加します
3. 問題が繰り返し発生する場合は、優先度を上げます
4. 根本的な修正を検討します：問題の繰り返しは、多くの場合、次のことを示しています。
   • ドキュメントの不足（→ CLAUDE.md または .github/copilot-instructions.md に昇格）
   • 自動化の不足（→ AGENTS.md に追加）
   • アーキテクチャ上の問題（→ 技術的負債のチケットを作成）

Simplify & Harden フィード

このワークフローを使って、simplify-and-harden スキルから繰り返し発生するパターンを取り込み、長期的に使えるプロンプトのガイダンスにします。

取り込みワークフロー

1. タスクの概要から simplify_and_harden.learning_loop.candidates を読み取ります。
2. 各候補では、安定した重複排除キーとして pattern_key を使用します。
3. .learnings/LEARNINGS.md で、そのキーを持つ既存のエントリを検索します。
   • grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md
4. 見つかった場合：
   • Recurrence-Count を増やします
   • Last-Seen を更新します
   • 関連するエントリやタスクへの See Also リンクを追加します
5. 見つからない場合：
   • 新しい LRN-... エントリを作成します
   • Source: simplify-and-harden を設定します
   • Pattern-Key、Recurrence-Count: 1、First-Seen／Last-Seen を設定します

昇格ルール（システムプロンプトへのフィードバック）

以下のすべてを満たす場合、繰り返し発生するパターンをエージェントのコンテキスト／システムプロンプトファイルに昇格させます。

• Recurrence-Count >= 3
• 少なくとも 2 つの異なるタスクで確認されている
• 30 日以内に発生している

昇格先：

• CLAUDE.md
• AGENTS.md
• .github/copilot-instructions.md

この 3 条件のルールが、このスキルにおける唯一の昇格基準です。セルフヒーリングする Handoff ブロックのクイックリファレンス行と、アグリゲーターのスキル（learning-aggregator、learning-aggregator-ci）でも、同じルールを使用します。

昇格するルールは、長いインシデント報告ではなく、短い予防ルール（コーディングの前／最中に行うこと）として記述します。

定期レビュー

自然な区切りで .learnings/ をレビューします。

レビューするタイミング

• 新しい大きなタスクを始める前
• 機能の実装が完了した後
• 過去の学びがある領域で作業するとき
• 開発が活発な期間は毎週

簡易ステータス確認

# Count pending items
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority items
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["

# Find learnings for a specific area
grep -l "Area\*\*: backend" .learnings/*.md

レビュー時の対応

• 解決済みの項目を処理します
• 該当する学びを昇格させます
• 関連するエントリをリンクします
• 繰り返し発生する問題をエスカレーションします
• 一度限りのエントリや未昇格のエントリを含め、保存された学びをレビューします。ソース、判断、依存関係、またはレビュー時点が変わった場合は、references/context-maintenance.md を使用して既存の契約を更新します。利用可能な場合は context-decay を使用します。レビューは、再発の証拠でも、経過時間に基づく削除の根拠でもありません。

検出トリガー

次のようなことに気づいた場合は、自動的に記録します。

修正（→ correction カテゴリーの学び）：

• 「いいえ、それは違います……」
• 「実際には、こうあるべきです……」
• 「その説明は間違っています……」
• 「それは古い情報です……」

機能リクエスト（→ 機能リクエスト）：

• 「これもできますか……」
• 「こうできたらいいのに……」
• 「何か方法はありますか……」
• 「なぜできないのですか……」

知識の不足（→ knowledge_gap カテゴリーの学び）：

• ユーザーが、知らなかった情報を提供する
• 参照したドキュメントが古い
• API の動作が自分の理解と異なる

エラー（→ エラーエントリ）：

• コマンドが 0 以外の終了コードを返す
• 例外またはスタックトレースが発生する
• 予期しない出力や動作がある
• タイムアウトまたは接続エラーが発生する

優先度のガイドライン

優先度	使用する状況
critical	中核機能を妨げる、データ損失のリスクがある、またはセキュリティ上の問題がある
high	影響が大きい、一般的なワークフローに影響する、または問題が繰り返し発生する
medium	影響は中程度で、回避策がある
low	軽微な不便、まれなケース、あると便利なもの

領域タグ

コードベースの領域で学びを絞り込むために使用します。

領域	範囲
frontend	UI、コンポーネント、クライアント側のコード
backend	API、サービス、サーバー側のコード
infra	CI/CD、デプロイ、Docker、クラウド
tests	テストファイル、テストユーティリティ、カバレッジ
docs	ドキュメント、コメント、README
config	設定ファイル、環境、設定項目

ベストプラクティス

1. すぐに記録する - 問題が起きた直後が、コンテキストを最もよく把握できるタイミングです
2. 具体的に記述する - 後続のエージェントがすばやく理解できるようにします
3. 再現手順を含める - 特にエラーの場合は重要です
4. 関連ファイルをリンクする - 修正しやすくなります
5. 具体的な修正案を提案する - 単に「調査する」だけにしないでください
6. 一貫したカテゴリーを使用する - 絞り込みに役立ちます
7. 選択的に昇格する - 昇格ルールを適用し、コピーした事実がすぐに古くなりそうな場合は、情報源を参照するポインターを優先します
8. 定期的にレビューする - 古くなった学びは価値を失います

Gitignore のオプション

学びをローカルに保持する（開発者ごと）：

.learnings/

リポジトリで学びを追跡する（チーム全体）： .gitignore に追加しないでください。学びが共有知識になります。

ハイブリッド（テンプレートは追跡し、エントリは無視する）：

.learnings/*.md
!.learnings/.gitkeep

フックとの統合

自動リマインダーはオプトインです。Claude Code、Codex CLI、Copilot では、イベントと出力の仕様がそれぞれ異なります。references/hooks-setup.md を参照してください。Amp はスキルをオンデマンドで読み込み、ターンごとのリマインダーには別のネイティブプラグインを使用します。references/amp-setup.md を参照してください。リマインダーは学びを書き込まず、記録を保証するものでもありません。

スキルの自動抽出

学びに再利用可能なスキルにするだけの価値がある場合、付属のヘルパーを使って抽出します。

スキル抽出の基準

次のいずれかに該当する場合、学びはスキル抽出の対象になります。

基準	説明
繰り返し発生する	類似する問題への See Also リンクが2つ以上ある
検証済み	ステータスが resolved で、修正が機能している
自明ではない	発見するために実際のデバッグや調査が必要だった
幅広く適用できる	プロジェクト固有ではなく、複数のコードベースで役立つ
ユーザーから指定された	ユーザーが「これをスキルとして保存して」などと伝えている

抽出のワークフロー

1. 候補を特定する：学びが抽出基準を満たしている
2. ヘルパーを実行する（または手動で作成する）：

   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improvement/scripts/extract-skill.sh skill-name
   

3. SKILL.md をカスタマイズする：学びの内容をテンプレートに記入する
4. 学びを更新する：ステータスを promoted_to_skill に設定し、Skill-Path を追加する
5. 確認する：新しいセッションでスキルを読み、単独で完結していることを確認する

手動での抽出

手動で作成する場合：

1. skills/<skill-name>/SKILL.md を作成する
2. assets/SKILL-TEMPLATE.md のテンプレートを使用する
3. Agent Skills spec に従う：
   • name と description を含む YAML frontmatter を記述する
   • 名前はフォルダー名と一致させる
   • スキルフォルダー内に README.md を置かない

抽出を検出するトリガー

学びをスキルにすべきことを示す、次のようなシグナルに注意してください。

会話内：

• 「これをスキルとして保存して」
• 「これに何度も遭遇する」
• 「これは他のプロジェクトでも役立ちそう」
• 「このパターンを覚えておいて」

学びのエントリ内：

• 複数の See Also リンク（繰り返し発生する問題）
• 高い優先度と解決済みのステータス
• カテゴリーが best_practice で、幅広く適用できる
• 解決策を称賛するユーザーからのフィードバック

スキルの品質ゲート

抽出前に、次の点を確認してください。

• 解決策がテスト済みで、機能している
• 元のコンテキストがなくても説明が明確である
• コード例が単独で完結している
• プロジェクト固有の値がハードコードされていない
• スキルの命名規則（小文字、ハイフン）に従っている

マルチエージェントのサポート

エージェントの種類にかかわらず、次の場合は自己改善を行ってください。

1. 自明ではないことを発見したとき - 解決策がすぐには明らかでなかった
2. 自分の誤りを訂正したとき - 最初のアプローチが間違っていた
3. プロジェクトの慣習を学んだとき - 文書化されていないパターンを発見した
4. 予期しないエラーに遭遇したとき - 特に、原因の特定が難しかった場合
5. より良いアプローチを見つけたとき - 元の解決策を改善できた

Copilot Chat との統合

Copilot ユーザーは、関連する場合に次の内容をプロンプトに追加してください。

このタスクを完了した後、自己改善スキルの形式を使用して、.learnings/ に記録すべき学びがあるか評価してください。

または、クイックプロンプトを使用してください。

• 「これを学びに記録して」
• 「この解決策からスキルを作成して」
• 「関連する問題がないか .learnings/ を確認して」