self-improvement

自己改善スキル

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

クイックリファレンス

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

OpenClaw のセットアップ（推奨）

OpenClaw は、このスキルの主要なプラットフォームです。ワークスペースベースのプロンプトインジェクションを使用し、スキルを自動的に読み込みます。

インストール

ClawdHub 経由（推奨）：

clawdhub install self-improving-agent

手動：

git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agent

ワークスペースの構成

OpenClaw は、各セッションに次のファイルを挿入します。

~/.openclaw/workspace/
├── AGENTS.md          # Multi-agent workflows, delegation patterns
├── SOUL.md            # Behavioral guidelines, personality, principles
├── TOOLS.md           # Tool capabilities, integration gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

学習ファイルの作成

mkdir -p ~/.openclaw/workspace/.learnings

次に、ログファイルを作成します（または assets/ からコピーします）。

• LEARNINGS.md — 修正、知識の不足、ベストプラクティス
• ERRORS.md — コマンドの失敗、例外
• FEATURE_REQUESTS.md — ユーザーが求めた機能

昇格先

学びが広く適用できるとわかったら、ワークスペースファイルに昇格させます。

学びの種類	昇格先	例
行動パターン	SOUL.md	「簡潔にし、免責事項を避ける」
ワークフローの改善	AGENTS.md	「長いタスクではサブエージェントを起動する」
ツールの注意点	TOOLS.md	「Git push の前に認証を設定する必要がある」

セッション間の通信

OpenClaw は、セッション間で学びを共有するためのツールを提供します。

• sessions_list — アクティブなセッション／最近のセッションを表示します
• sessions_history — 別のセッションのトランスクリプトを読み取ります
• sessions_send — 別のセッションに学びを送信します
• sessions_spawn — バックグラウンド作業用のサブエージェントを起動します

オプション：フックを有効にする

セッション開始時に自動リマインダーを表示するには：

# Copy hook to OpenClaw hooks directory
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement

# Enable it
openclaw hooks enable self-improvement

詳細については、references/openclaw-integration.md を参照してください。

---

汎用セットアップ（その他のエージェント）

Claude Code、Codex、Copilot、その他のエージェントでは、プロジェクト内に .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 のメモに理由を追加します）
• promoted - CLAUDE.md、AGENTS.md、または .github/copilot-instructions.md に昇格済み

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

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

昇格するタイミング

• 複数のファイルや機能にまたがって適用される学び
• 人間または AI のすべてのコントリビューターが知っておくべき知識
• 繰り返し発生するミスを防ぐもの
• プロジェクト固有の規約を記録するもの

昇格先

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

昇格方法

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

昇格の例

学び（詳細）：

プロジェクトでは 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 に追加）
   • アーキテクチャ上の問題（→ 技術的負債のチケットを作成）

定期的なレビュー

自然な区切りのタイミングで .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 フロントマターを記述する
   • 名前はフォルダー名と一致させる
   • スキルフォルダー内に 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?"

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

OpenClaw

アクティベーション：ワークスペースへの注入＋エージェント間メッセージング セットアップ：上記の「OpenClaw Setup」セクションを参照してください 検出：セッションツールとワークスペースファイルを通じて行います

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

エージェントにかかわらず、次のような場合は自己改善を適用してください。

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

Copilot Chat との連携

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

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

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

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