self-improvement

自己改善スキル

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

初回使用時の初期化

何かを記録する前に、プロジェクトまたはワークスペースのルートに .learnings/ ディレクトリとファイルが存在することを確認してください。不足しているものがあれば作成します。

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nCorrections, insights, and knowledge gaps captured during development.\n\n**Categories**: correction | insight | knowledge_gap | best_practice\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/ERRORS.md ] || printf "# Errors\n\nCommand failures and integration errors.\n\n---\n" > .learnings/ERRORS.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nCapabilities requested by the user.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

既存のファイルを上書きしないでください。.learnings/ がすでに初期化されている場合、これは何も行いません。

ユーザーから明示的に詳細な記録を求められない限り、シークレット、トークン、秘密鍵、環境変数、ソースファイルや設定ファイル全体を記録しないでください。生のコマンド出力や会話記録全体ではなく、短い要約や機密情報を伏せた抜粋を優先してください。

自動リマインダーやセットアップの支援が必要な場合は、フックの統合で説明するオプトイン方式のフックワークフローを使用してください。

クイックリファレンス

状況	対応
コマンド／操作が失敗した	.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 に記録します
繰り返し使われるパターンを簡素化／堅牢化する	Source: simplify-and-harden と安定した Pattern-Key を付けて .learnings/LEARNINGS.md に記録／更新します
既存の項目と類似している	**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 向けに作り直しました：https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement

ワークスペースの構成

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

上記のヘッダーを使って、ファイルをインラインで作成します。このパスを明示的に信頼している場合を除き、現在のリポジトリやワークスペースからテンプレートを読み込まないでください。

エージェントファイル AGENTS.md、CLAUDE.md、または .github/copilot-instructions.md に参照を追加し、学びを記録するよう自分に促します。（これはフックベースのリマインダーに代わる方法です）

自己改善ワークフロー

エラーや修正が発生した場合：

1. .learnings/ERRORS.md、LEARNINGS.md、または FEATURE_REQUESTS.md に記録します
2. 広く適用できる学びを見直し、次のファイルに反映します：
   • CLAUDE.md - プロジェクトの事実と規約
   • AGENTS.md - ワークフローと自動化
   • .github/copilot-instructions.md - Copilot のコンテキスト

記録形式

学びのエントリー

.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)
- 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)

---

エラーエントリー

.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
- Summary or redacted excerpt of relevant output (avoid full transcripts and secret-bearing data by default)

### 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 - 対応しないことを決定（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	行動指針、コミュニケーションスタイル、原則（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 に追加）
   • アーキテクチャ上の問題（→ 技術的負債のチケットを作成）

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
• 該当する場合は、OpenClaw のワークスペースレベルのガイダンス用の SOUL.md／TOOLS.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"
      }]
    }]
  }
}

これは任意です。推奨されるデフォルトはアクティベーターのみのセットアップです。PostToolUse は、フックスクリプトがコマンド出力を調べてエラーパターンを検出することに問題がない場合にのみ有効にしてください。

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

スクリプト	フックの種類	目的
scripts/activator.sh	UserPromptSubmit	タスク後に学習内容を評価するようリマインドします
scripts/error-detector.sh	PostToolUse (Bash)	コマンドエラーが発生したときにトリガーします

詳しい設定方法とトラブルシューティングについては、references/hooks-setup.md を参照してください。

スキルの自動抽出

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

スキル抽出の基準

次のいずれかに該当する学習内容は、スキルとして抽出できます。

基準	説明
繰り返し発生	類似する2件以上の問題への See Also リンクがある
検証済み	ステータスが 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 リンク（繰り返し発生する問題）
• 優先度が高く、ステータスが解決済み
• カテゴリーが 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?"

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