auto-improvement

概要

自動改善スキルは、効果指標を追跡し、エラーから学び、繰り返し発生する失敗パターンを特定し、同じ間違いを防ぐためにワークフローを適応させる、自己改善型のフィードバックループを実装します。場当たり的な調整ではなく、体系的な自己評価を通じて、エージェントが時間の経過とともに測定可能な形で改善できるようにします。このスキルがなければ、同じ間違いがセッションをまたいで繰り返されますが、このスキルがあれば、すべてのエラーが恒久的な改善につながります。

このスキルは常に有効です。 すべてのセッションで自動的に実行され、無効にすることはできません。

---

フェーズ 1：指標の収集

すべてのタスクの開始時に、重要な意思決定ポイントを計測します。

1. タスクの開始時刻と初期見積もりを記録する
2. 期待される結果と成功基準を定義する
3. 各意思決定ポイントを追跡する（選択したアプローチ、検討した代替案）
4. 修正回数を記録する（出力を何回修正したか）
5. ユーザーからの修正を改善のシグナルとして追跡する

主要な指標

指標	計算式	目標	測定期間
初回成功率	修正なしのタスク数 / タスク総数	>80%	セッションごと
平均修正回数	修正総数 / タスク総数	<1.5	セッションごと
エラー再発率	繰り返し発生したエラー数 / エラー総数	<10%	直近10セッション
完了時間の精度	実際の時間 / 見積もり時間	0.8-1.2	タスクごと
ユーザー修正率	ユーザーによる修正数 / 出力総数	<5%	セッションごと

追跡テンプレート

## Session Metrics -- [Date]

### Tasks
| Task | Estimated | Actual | Revisions | Success | Error Type |
|------|-----------|--------|-----------|---------|------------|
| ...  | 30m       | 45m    | 1         | Partial | Execution  |

### Summary
- Tasks completed: X
- First-attempt success: X/Y (Z%)
- Total revisions: N
- Errors by category: Comprehension(n), Execution(n), Process(n)
- Improvement actions taken: [list]

停止：エラー分析に進む前に、指標収集の設定を完了してください。計測を省略しないでください。

---

フェーズ 2：エラー分析

エラーが発生したら、以下の分類体系を使って直ちに分類します。

エラー分類

カテゴリー	サブカテゴリー	例	典型的な根本原因
理解	要件の読み違い	Yを求められたのに、機能Xを実装した	確認不足
理解	誤った前提	GraphQLが使われているのにRESTだと思い込んだ	コンテキストの把握不足
実行	構文エラー	TypeScriptの型注釈が無効	APIの仕様への不慣れ
実行	ロジックエラー	ページネーションでのオフバイワンエラー	テストカバレッジの不足
実行	統合エラー	APIエンドポイントまたはペイロード形式の誤り	ドキュメントの確認不足
プロセス	手順の省略	コミット前にテストを実行し忘れた	プロセスに従わなかった
プロセス	順序の誤り	仕様を理解する前にコードを書いた	方法論より性急さを優先
判断	過剰な設計	単一のユースケースのために抽象化を構築した	時期尚早な最適化
判断	設計不足	「単純な」タスクだからとエラー処理を省略した	複雑さの過小評価
知識	未知のAPI	非推奨のメソッドを使用した	古い学習データ
知識	フレームワークの知識不足	App Routerに誤ったNext.jsのパターンを使用した	先にドキュメントを確認する必要がある

重大度レベル

レベル	定義	必要な対応
致命的	タスクを完全にやり直す必要がある	直ちに根本原因を分析し、ガードレールを追加する
重大	大幅な手戻りが必要（タスクの50%超）	根本原因を分析し、チェックリスト項目を追加する
軽微	小さな修正が必要（30分未満）	パターンを記録し、再発しているか確認する
表面的	スタイルまたは好みに関する問題	今後の参考として記録し、プロセスは変更しない

エラーログ形式

## Error Log Entry

**ID:** ERR-[YYYY]-[MMDD]-[NNN]
**Date:** [date]
**Task:** [what was being done]
**Severity:** [Critical / Major / Minor / Cosmetic]
**Category:** [Category > Subcategory]

### What Happened
[Description of the error and its observable impact]

### Root Cause
[Why this error occurred — the actual underlying reason]

### What Was Tried
1. [First attempt to resolve]
2. [Second attempt if applicable]
3. [Final resolution]

### Resolution
[What ultimately fixed the problem]

### Time Lost
[Estimated time wasted due to this error]

### Prevention
- **New checklist item:** [if applicable]
- **Memory update:** [what was persisted]
- **Guardrail added:** [if applicable]

### Recurrence Check
- [ ] Similar error seen before? [Yes/No — reference previous ID]
- [ ] Guardrail added? [Yes/No]

停止：修正に進む前に、すべてのエラーを必ず分類して記録してください。ログへの記入を省略しないでください。

---

フェーズ 3：パターン認識

エラーが3件以上蓄積したら、パターンを分析します。

1. 関連するエラーを失敗カテゴリーごとにグループ化する
2. 環境要因のトリガー（特定のファイル形式、フレームワーク、パターン）を特定する
3. 一貫して遅延を引き起こすワークフローのボトルネックを検出する
4. 強化する価値のある成功パターンを認識する
5. アンチパターンと、それに対応する是正措置を対応付ける

パターン検出の判断表

シグナル	パターン	アクション
同じエラーが2回を超える	繰り返し発生する失敗	ガードレールを作成する（必須）
同じカテゴリが3回を超える	全般的な弱点	そのカテゴリのプリフライトチェックリストを追加する
時間の見積もりが一貫して50％を超えて外れる	見積もりの盲点	見積もりのヒューリスティックを調整する
同じ領域でユーザーから修正を受ける	知識の不足	その分野を深く学習する
特定の領域で成功率が90％を超える	強みとなるパターン	文書化して強化する
特定のフレームワークの周辺にエラーが集中する	フレームワークの知識不足	そのフレームワークのコンテキスト検出を実施する

成功パターンの強化

パターンが一貫して成功につながる場合は、文書化してください。

## Positive Pattern: [Name]
OBSERVATION: [What was done and why it worked]
EVIDENCE: [Sessions/tasks where this pattern succeeded, with success rate]
REINFORCEMENT: [How to ensure this pattern continues to be applied]

STOP：パターンの認識は証拠に基づく必要があります。1回の発生だけからパターンを作成してはいけません。

---

フェーズ 4：適応

特定したパターンに基づいて改善を生成し、実施します。

プリフライトチェックリスト

リスクの高い操作の前に実行するチェックリストを作成します。

## Pre-Flight: Before Writing [Framework] Code
- [ ] Identify the framework and version (check package.json / composer.json)
- [ ] Identify the routing pattern (pages/ vs app/, file-based vs code-based)
- [ ] Check for existing patterns in the codebase (find similar files)
- [ ] Verify the API surface in documentation (do not assume from memory)
- [ ] Check for project-specific conventions (linter config, type config)

ガードレールルール

## Guardrail: [Operation Type]
BEFORE [specific operation]:
1. [Check 1]
2. [Check 2]
3. [Check 3]
4. [Check 4]

TRIGGERED BY: [keywords or conditions that activate this guardrail]
ADDED BECAUSE: [Error ID that caused this guardrail to be created]
EFFECTIVENESS: [Track whether this guardrail has prevented errors]

適応の判断表

エラーパターン	適応の種類	例
理解に関するエラーの繰り返し	ワークフローに確認手順を追加する	「実装する前に、要件を自分の言葉で言い換えてください」
実行に関するエラーの繰り返し	プリフライトチェックリストを追加する	「フレームワークのコードを書く前に、バージョンとルーターの種類を確認してください」
プロセスに関するエラーの繰り返し	厳格なチェックポイントを追加する	「コミット前にSTOPマーカーを設ける：テストを実行しましたか？」
判断に関するエラーの繰り返し	判断基準の表を追加する	「抽象化するかインライン化するか：頻度が3回を超えるか、複雑さが中程度を超える場合」
知識に関するエラーの繰り返し	コンテキスト検出の手順を追加する	「APIを使用する前に、記憶ではなく最新のドキュメントを確認してください」

STOP：すべての適応は、保存する前に過去のデータに照らして検証する必要があります。

---

フェーズ 5：フィードバックループと検証

改善が実際に効果を上げているか測定します。

1. 現在のエラー率をベースライン（改善前）と比較する
2. 各ガードレールによる防止件数を追跡する
3. エラーを明確に減らす改善をアーカイブする
4. エラーを減らさない、またはオーバーヘッドが増える改善を元に戻す
5. メモリファイルを通じて、セッション間で学びを共有する

振り返りテンプレート

## Retrospective -- [Period]

### What Went Well
- [Pattern/approach that consistently succeeded]
- [New technique that improved outcomes]

### What Went Poorly
- [Recurring error pattern with frequency]
- [Process gap that caused rework]

### Error Trends
| Category | This Period | Last Period | Trend |
|----------|------------ |-------------|-------|
| Comprehension | 3 | 5 | Improving |
| Execution | 7 | 4 | Worsening -- investigate |
| Process | 1 | 3 | Improving |
| Knowledge | 4 | 4 | Stable |

### Root Cause Analysis (Top 3 Errors)
1. **[Error pattern]** -- Root cause: [analysis] -- Fix: [action]
2. **[Error pattern]** -- Root cause: [analysis] -- Fix: [action]
3. **[Error pattern]** -- Root cause: [analysis] -- Fix: [action]

### Improvement Actions
| Action | Priority | Status | Expected Impact | Actual Impact |
|--------|----------|--------|-----------------|---------------|
| Add pre-flight check for X | High | Done | -30% execution errors | [measured] |
| Update memory with Y pattern | Medium | Done | -20% knowledge errors | [measured] |
| Create guardrail for Z | High | In Progress | Prevent critical error class | [pending] |

### Metrics vs. Targets
| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| First-attempt success | >80% | 75% | Below target |
| Revision count | <1.5 | 1.8 | Below target |
| Error recurrence | <10% | 8% | On target |

---

メモリファイルとの統合

保存する内容

ファイル	更新するタイミング	内容
memory/learned-patterns.md	新しいパターンを発見したとき、またはエラーパターンを特定したとき	コーディング規約、フレームワークのパターン、アンチパターン
memory/user-preferences.md	ユーザーがスタイル、形式、またはアプローチを修正したとき	コミュニケーションの好み、コードスタイル、ツールの選択
memory/decisions-log.md	重要なアーキテクチャ上の決定、またはアプローチ上の決定を行ったとき	決定、理由、検討した代替案
memory/project-context.md	新しいプロジェクトのコンテキストを発見したとき	技術スタック、アーキテクチャ、依存関係

更新手順

1. エラーまたは成功から得られた学びを特定する
2. 既存のメモリエントリーと競合しないか確認する
3. 競合する場合：新しい情報と日付を加えて既存のエントリーを更新する
4. 新しい情報の場合：コンテキスト、証拠、日付を含むエントリーを追加する
5. 有効でなくなったエントリーを削除する（技術が変わった、プロジェクトが進化したなど）

直感をパターンとして保存してはいけません。必要な証拠は、最低2回の発生です。

---

継続的改善サイクル

Execute Tasks -> Collect Metrics -> Analyze Errors -> Identify Patterns
      ^                                                       |
      |                                                       v
      +-- Persist to Memory <-- Validate Impact <-- Implement Improvements
                                      |
                                      +-- Did not work? -> Revert, try different approach

---

アンチパターン／よくある間違い

してはいけないこと	うまくいかない理由	代わりにすること
ガードレールを設けずに同じ間違いを3回繰り返す	防止策がないため、エラーが繰り返し発生します	2回目の発生後にガードレールを作成します
指標を追跡するだけで、それに基づいて行動しない	成果につながらない取り組みで、測定しているふりにすぎません	すべての指標に行動を起こす基準値を設けます
1回のエラーを受けて過剰に修正する	1度の悪い経験だけで、ツールを永久に避ける理由にはなりません	パターンを作成する前に、2回以上の発生を確認します
すべてのエラーを同じように扱う	表面的な問題に労力を費やすことになります	発生頻度 × 影響度に基づいて優先順位を付けます
根拠なくメモリを更新する	誤ったパターンによって、今後のセッションに悪影響を及ぼします	保存する前に2つ以上の事例を確認します
チェックリストを増やしすぎて負担にする	チェックリスト疲れにより、すべてを使わなくなります	チェックリストは最大5項目とし、使われていないものは廃止します
外的要因だけを責める	内部のプロセス改善を見落とします	自分に何ができたかを必ず検討します
改善を検証しない	改善が実際に機能しているか判断できません	改善の前後でエラー率を比較します
古くなったパターンを保存し続ける	古いアドバイスが新たなエラーを招きます	定期的にメモリを見直し、不要な情報を削除します
振り返りをまったく行わない	全体像を見失い、個々のエラーだけに注目してしまいます	タスクを10件実行するごとに振り返りを予定します

---

合理化を防ぐためのガード

考え	実際のところ
「このエラーは一度きりです」	それでも記録してください。再発した場合、データが残っています。
「指標の収集は作業を遅らせます」	指標を収集しなければ、同じ間違いを繰り返すことになります。
「このタスクにチェックリストは大げさです」	以前に同様のタスクで失敗したため、チェックリストがあります。必ず使ってください。
「この教訓は覚えておきます」	覚えていられません。セッションは独立しています。メモリに保存してください。
「このエラーは私のせいではありません」	外的要因でも内的要因でも、パターンを記録してください。防止するのはあなたの役目です。
「振り返りは時間の無駄です」	振り返りをしなければ、傾向を把握できません。必ず実施してください。
「成功率は十分に高いです」	十分な状態では停滞します。目標は継続的な改善です。

エラーの記録を省略してはいけません。指標の収集を省略してはいけません。これらは必須です。

---

連携ポイント

スキル	関係
self-learning	知識に関するエラーを防ぐプロジェクトのコンテキストを提供します
resilient-execution	失敗した再試行がエラー分析に役立ちます
circuit-breaker	停滞イベントは重大なエラーの兆候です
verification-before-completion	検証の失敗をきっかけにエラーを記録します
planning	改善アクションが今後の計画の質を高めます
code-review	レビューで見つかった事項がパターン認識に役立ちます

---

具体例

エラーパターンから作成したガードレール

Error: ERR-2026-0212-003 — Dropped production table during migration
Error: ERR-2026-0301-007 — Applied migration without rollback plan

Pattern: Database operations without safety checks (2 occurrences)

Guardrail Created:
## Guardrail: Database Operations
BEFORE any database migration or schema change:
1. Check if there is an existing migration framework
2. Verify the current schema state
3. Create a rollback plan
4. Test migration on a copy first

TRIGGERED BY: any task involving database, schema, migration, model
ADDED BECAUSE: ERR-2026-0212-003, ERR-2026-0301-007
EFFECTIVENESS: 0 errors in 5 subsequent database tasks

ポジティブなパターンの文書化

## Positive Pattern: Context Discovery First
OBSERVATION: Tasks where project context was gathered first had
a 92% first-attempt success rate vs. 64% without.
EVIDENCE: Sessions 2026-02-01 through 2026-03-15 (47 tasks)
REINFORCEMENT: Always run context discovery before implementation.
Minimum: check package.json, read existing code in same domain,
identify conventions.

---

スキルタイプ

RIGID — エラーの追跡、分類、改善サイクルを一貫して実施する必要があります。繰り返し発生するエラー（2回以上）には、具体的な予防策を必ず講じてください。メモリファイルを更新する際は、根拠に基づくパターンのみを使用してください。すべてのセッションで、指標の収集とエラーの記録が必須です。振り返りを省略してはいけません。