self-improvement

自己改善スキル

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

クイックリファレンス

状況	対応
コマンド／操作が失敗した	.learnings/ERRORS.md に記録する
ユーザーから修正された	カテゴリを correction として .learnings/LEARNINGS.md に記録する
ユーザーが不足している機能を求めた	.learnings/FEATURE_REQUESTS.md に記録する
API／外部ツールが失敗した	統合の詳細とともに .learnings/ERRORS.md に記録する
知識が古くなっていた	カテゴリを knowledge_gap として .learnings/LEARNINGS.md に記録する
より良い方法が見つかった	カテゴリを best_practice として .learnings/LEARNINGS.md に記録する
既存の項目と類似している	**See Also** でリンクし、優先度の引き上げを検討する
幅広く適用できる学び	CLAUDE.md、AGENTS.md、および／または .github/copilot-instructions.md に昇格する
ワークフローの改善	AGENTS.md（ボットのワークスペース）に昇格する
ツールの注意点	TOOLS.md（ボットのワークスペース）に昇格する
行動パターン	SOUL.md（ボットのワークスペース）に昇格する

セットアップ

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

mkdir -p .learnings

assets/ からテンプレートをコピーするか、ヘッダー付きのファイルを作成します。

記録形式

学びの項目

.learnings/LEARNINGS.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)

---

エラーの項目

.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. Metadata の後に解決ブロックを追加する：

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

その他のステータス値：

• in_progress - 現在対応中
• wont_fix - 対応しないことを決定（Resolution notes に理由を追加する）
• promoted - CLAUDE.md、AGENTS.md、または .github/copilot-instructions.md に昇格済み

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

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

昇格するタイミング

• 複数のファイル／機能に適用される学び
• すべてのコントリビューター（人間または AI）が知っておくべき知識
• 同じ間違いの繰り返しを防ぐ
• プロジェクト固有の規約を文書化する

昇格先

対象	記載する内容
CLAUDE.md	すべての Claude とのやり取りに関するプロジェクトの事実、規約、注意点
AGENTS.md	エージェント固有のワークフロー、ツールの使用パターン、自動化ルール
.github/copilot-instructions.md	GitHub Copilot 向けのプロジェクトのコンテキストと規約
SOUL.md	行動指針、コミュニケーションスタイル、原則（ボット）
TOOLS.md	ツールの機能、使用パターン、統合時の注意点（ボット）

昇格方法

1. 要約：学びを簡潔なルールまたは事実にまとめる
2. 追加：対象ファイルの適切なセクションに追加する（必要に応じてファイルを作成する）
3. 元の項目を更新する：
   • **Status**: pending → **Status**: promoted に変更する
   • **Promoted**: CLAUDE.md、AGENTS.md、または .github/copilot-instructions.md を追加する

昇格の例

学び（詳細）：

プロジェクトでは pnpm workspaces を使用しています。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 に追加する）
   • アーキテクチャ上の問題がある（→ 技術的負債のチケットを作成する）

定期的なレビュー

区切りのよいタイミングで .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

レビューでの対応

• 解決済みの項目を完了扱いにする
• 該当する学びを昇格させる
• 関連するエントリーをリンクする
• 繰り返し発生する問題をエスカレーションする

検出のきっかけ

次のようなことに気付いたら、自動的に記録します：

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

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

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

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

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

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

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

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

優先度のガイドライン

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

領域タグ

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

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

ベストプラクティス

1. すぐに記録する - 問題の直後が最も状況を思い出しやすい
2. 具体的に書く - 今後のエージェントがすぐに理解できるようにする
3. 再現手順を含める - 特にエラーの場合
4. 関連ファイルをリンクする - 修正が容易になる
5. 具体的な修正案を提示する - 「調査する」だけで済ませない
6. 一貫したカテゴリーを使う - 絞り込みが可能になる
7. 積極的に昇格させる - 迷ったら CLAUDE.md または .github/copilot-instructions.md に追加する
8. 定期的にレビューする - 古い学びは価値が失われる

Gitignore の設定 विकल्प

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

.learnings/

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

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

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

フックとの連携

エージェントのフックを通じて自動リマインダーを有効にします。これはオプトインです。フックを明示的に設定する必要があります。

クイックセットアップ（Claude Code / Codex）

プロジェクトに .claude/settings.json を作成します：

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }]
  }
}

これにより、各プロンプトの後に学びを評価するリマインダーが挿入されます（オーバーヘッドは約50～100トークンです）。

完全なセットアップ（エラー検出を含む）

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/error-detector.sh"
      }]
    }]
  }
}

利用可能なフックスクリプト

スクリプト	フックの種類	目的
scripts/activator.sh	UserPromptSubmit	タスク後に学びを評価するよう促す
scripts/error-detector.sh	PostToolUse (Bash)	コマンドエラーを検出する

詳しい設定方法とトラブルシューティングについては、references/hooks-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 リンク（再発する問題）
• 優先度が高く、ステータスが resolved
• カテゴリが best_practice で、幅広く適用可能
• 解決策を称賛するユーザーからのフィードバック

スキルの品質ゲート

抽出する前に、以下を確認します。

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

マルチエージェント対応

このスキルは、エージェントごとの有効化方法により、さまざまな AI コーディングエージェントで動作します。

Claude Code

有効化：フック（UserPromptSubmit、PostToolUse） 設定：フック設定を含む .claude/settings.json 検出：フックスクリプトによる自動検出

Codex CLI

有効化：フック（Claude Code と同じパターン） 設定：フック設定を含む .codex/settings.json 検出：フックスクリプトによる自動検出

GitHub Copilot

有効化：手動（フックはサポートされていません） 設定：.github/copilot-instructions.md に追加します。

## Self-Improvement

After solving non-obvious issues, consider logging to `.learnings/`:
1. Use format from self-improvement skill
2. Link related entries with See Also
3. Promote high-value learnings to skills

Ask in chat: "Should I log this as a learning?"

検出：セッション終了時に手動で確認

Bot

有効化：ワークスペースへの注入 + エージェント間メッセージング 設定：~/.bot/bot.json でワークスペースのパスを設定します 検出：セッションツールおよびワークスペースファイル（AGENTS.md、SOUL.md、TOOLS.md）を通じて行います

Bot は、プロンプトファイルを注入するワークスペースベースのモデルを使用します。詳細な設定については、references/bot-integration.md を参照してください。

エージェントに依存しないガイダンス

エージェントに関係なく、次の場合は自己改善を適用します。

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

Copilot Chat との統合

Copilot ユーザーは、必要に応じてプロンプトに次の内容を追加します。

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

または、次のクイックプロンプトを使用します。

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

Bot との統合

Bot は、用途ごとに特化したファイルを使用し、ワークスペースベースでプロンプトを注入します。

ワークスペース構造

~/bot/                    # Default workspace (configurable)
├── AGENTS.md              # Multi-agent workflows, delegation patterns
├── SOUL.md                # Behavioral guidelines, communication style
├── TOOLS.md               # Tool capabilities, MCP integrations
└── sessions/              # Session transcripts (auto-managed)

Bot の昇格先

学習タイプ	昇格先	例
エージェントの連携	AGENTS.md	「ファイル検索を調査エージェントに委任する」
コミュニケーションスタイル	SOUL.md	「簡潔にし、免責事項は避ける」
ツールの注意点	TOOLS.md	「MCP サーバー X では認証の更新が必要」
プロジェクトの事実	CLAUDE.md	標準的なプロジェクト規約

エージェント間の学習

Bot はセッションベースのコミュニケーションに対応しています。

• sessions_list - アクティブなセッションと最近のセッションを確認します
• sessions_history - 別のセッションのトランスクリプトを読み込みます
• sessions_send - 別のセッションにメッセージを送信します

ハイブリッド設定（Claude Code + Bot）

両方を使用する場合：

1. プロジェクト固有の学習内容には .learnings/ を使用します
2. プロジェクト横断的なパターンには Bot のワークスペースファイルを使用します
3. 価値の高い学習内容を両方のシステムに同期します

設定、昇格形式、トラブルシューティングの詳細については、references/bot-integration.md を参照してください。