実験中...

Claude Codeが同じエラーを繰り返す原因は、フィードバックループの欠如です。構造化ログ・8軸パターン検出・SKILL.md自動修正の3パターンで自己改善を実装します。

AIエージェントの「失敗学習」とは何か

LLMエージェントは推論時に出力を評価・修正するself-correctionを持ちます（Self-Refine, Madaan et al. 2023）。ただし重要な制限があります。

記憶を持たない: 前回の失敗を「覚えて」はいない
暗黙の学習をしない: 重みは変わらず、プロンプト/ツール定義を書き換える必要がある
対策を永続化できない: 避けられても翌日は同じエラーが再発する

つまり「失敗から学ぶ」には、失敗を外部ストレージに記録 → パターンを抽出 → 設定ファイルを更新するサイクルが必要です。

典型的な失敗パターン3例

パターンA: 依存関係の見落とし（env） — worktree作成直後のnode_modules不在
パターンB: フォーマットルールの不整合（lint） — Biome設定と出力スタイルの不一致
パターンC: 型定義の不足（type-check） — strict: trueでも型アノテーション不足

共通するのは「1回目に対策を書いていれば2回目は防げた」という点です。

3つの設計パターン（概要）

#	パターン	何をするか	最小構成
1	構造化ログ	エラーを8カテゴリに分類記録	CLAUDE.mdに3行追記
2	8軸パターン検出	繰り返し・漏れ・不足を数値化	errors.md + 週1振り返り
3	SKILL.md自動修正	修正diffを生成・承認	skill-retrospective

レベル1（CLAUDE.mdへの3行追記）だけでも「同じエラーに3回ハマる」問題はかなり減ります。この記事はskill-retrospectiveを実装例に紹介します。

パターン1: 構造化ログ（skill-retrospective）

skill-retrospectiveは実行履歴からSKILL.mdの修正diffを自動生成するメタスキルです。

1. COLLECT  → ~/.claude/journal/ からエントリ読み込み
2. FILTER   → 前回レトロスペクティブ以降の未分析エントリを抽出
3. ANALYZE  → 8軸でパターン検出
4. CORRELATE → 該当スキルのSKILL.mdを読み、ギャップを特定
5. PROPOSE  → 修正diffを生成
6. PRESENT  → ユーザーに承認/却下を確認
7. APPLY    → SKILL.mdを編集、コミット
8. PERSIST  → レトロスペクティブ結果をメモリに保存

全部構造化データで回るのがポイントです。

ジャーナル: 構造化された実行ログ

各スキルがjournal.shを呼び、構造化JSONを~/.claude/journal/に書き込みます。

# 成功時
$SKILLS_DIR/skill-retrospective/scripts/journal.sh log dev-flow success \
  --issue 42 --duration-turns 6 --mode single

# 失敗時
$SKILLS_DIR/skill-retrospective/scripts/journal.sh log dev-flow failure \
  --error-category lint --error-msg "Biome: 3 violations" \
  --error-phase "4_validate" --recovery "auto-fix applied" --recovery-turns 2

JSONの構造例です。

{
  "version": "1.0.0",
  "id": "20260430T103000-dev-flow",
  "timestamp": "2026-04-30T10:30:00Z",
  "skill": "dev-flow",
  "outcome": "failure",
  "duration_turns": 8,
  "context": { "project": "corporate-site", "issue": 42, "mode": "single" },
  "error": {
    "phase": "4_validate",
    "category": "lint",
    "message": "Biome: 3 violations"
  },
  "recovery": {
    "action": "auto-fix applied",
    "successful": true,
    "turns_spent": 2
  }
}

エラーは8カテゴリに分類。envとlintで7割でした。

Skillsなしでも使えるポイント: CLAUDE.mdに「エラーが起きたら errors.md に追記」と1行書くだけで構造化ログの第一歩になります。

パターン2: 8軸パターン検出

ジャーナルが溜まったら8つの軸でパターンを検出します。最初は5軸でしたが実運用の課題を受け3軸追加しました。

軸	何を見るか
Recurring failures	同じエラーが2回以上（例: `node_modules missing`が3回）
Instruction gaps	SKILL.mdに対策記述がない
Guard deficiency	前提条件チェック不足
Workflow inefficiency	リカバリに2ターン超（5超で重大）
Environment issues	環境系エラーの集中
Phase bottleneck	子スキルで遅延・失敗が集中（中央値の2倍超）
Efficiency trend	ターン数の増減傾向（先週比+30%等）
Coverage audit	未実装スキルを検出（65中15が未計測）

最初の5軸は「個別のエラーを直す」役割、追加の3軸は全体の健全性を俯瞰する役割です。初回は「71%に記録がなかった」と判明しました。

スコアリングで優先順位をつける

pattern_score = frequency * impact * preventability

frequency: 発生回数
impact: 重大度（env=3, lint=1）
preventability: 対処可能性（記述なし=3, 部分的=2, 対処済み=1）

スコア9以上は即座に修正提案、4以上は含め、4未満は放置。掛け算で優先順位をつけて強制浮上させる仕組みです。

応用: 最初の5軸はerrors.mdを月末に眺めるだけでも手動で回せます。

パターン3: SKILL.md自動修正

パターン検出後、SKILL.mdの修正diffを生成します。

node_modules不整合 (env, 3回発生, スコア3×3×3=27)
→ git-prepare/SKILL.mdに「worktree作成後にnpm ciを検証」をdiff提案

承認・修正して承認・却下の3択が提示され、人間が判断する設計です。

dev-flow-doctor: ワークフローの健康診断

dev-flow-doctorは全体の健康度をスコアリングします。

ヘルススコアの計算

score = 100
score -= (failure_rate * 30)        # 失敗率が高い → 最大-30
score -= (avg_recovery_turns * 5)   # リカバリが遅い → 最大-25
score -= (stale_worktrees * 2)      # 放置worktree → 最大-10
score -= (orphaned_dirs * 3)        # 孤立ディレクトリ → 最大-15
score -= (duration_outlier_pct * 10) # 異常に長い実行 → 最大-10
score -= (env_errors_pct * 15)      # 環境エラーの割合 → 最大-15

100点から減点方式です。

スコア	判定	推奨アクション
80-100	Healthy	軽微な最適化のみ
60-79	Fair	上位2件の指摘を対処
40-59	Needs Attention	`/skill-retrospective`を実行
0-39	Critical	体系的なレビューが必要

7つの診断チェック

数字でボトルネックが見えるのが違いです。

#	チェック	検出基準
1	実行規模分布	shape（micro/standard/complex）比率の確認
2	失敗フェーズ分布	implement30%超で分析不足、validate40%超で自動化要
3	エラーカテゴリ分布	`lint`40%超/`env`30%超で対策検討
4	Worktree健全性	7日以上放置・孤立ディレクトリを検出
5	平均リカバリターン数	2.0未満は問題なし、5.0超で改善タイミング
6	成功率トレンド	直近7日 vs 全期間の改善/悪化判定
7	所要時間の外れ値	平均ターン数の3倍超を検出、平均8ターン超で要最適化

Health Score: 72/100 (Fair) | Period: 2026-03-01 ~ 2026-04-30
Executions: 127 (success: 108, failure: 7, partial: 12)
validateフェーズの失敗38%・env系エラー25%・直近7日の成功率90%(全期間85%)
→ dev-validateにauto-fixモード追加、git-prepareにdependency check追加

dev-flow-doctorが検出し、skill-retrospectiveが提案します。

session-save/load: コンテキストを失わない仕組み

もう1つ重要な要素がセッション間のコンテキスト永続化です（状態管理の記事）。/session-saveは進捗を永続化し、未分析の失敗（--limit 100で照会、1件でも「3件あり」等と通知）を知らせます。/session-loadが前回コンテキストを復元し、3セッションで1つの改善サイクルが回ります。

自己改善サイクルの全体像

journal.shで記録 → dev-flow-doctorが7診断でヘルススコア算出
→ skill-retrospectiveが8軸検出でSKILL.md修正diff生成・承認
→ session-save/loadがコンテキストを永続化して次セッションへ

ジャーナル記録 → 定量診断 → パターン検出 → SKILL.md修正 → コンテキスト永続化。人間の介入を最小限に回り続けます。

実際に回してみた所感

導入直後は分析データがなく、20スキルにjournal.shの呼び出しを追加して1週間ログを溜めました。2週目に/skill-retrospective --since 7dを実行。上位3パターン: npm ci漏れ（env, 5回, スコア45）。Biome formatエラー（lint, 8回, スコア8）。strict エラー（type-check, 3回, スコア6）。スコア45は「Critical」超過で反省。

3週目以降、修正済みSKILL.mdで上位2エラーがほぼ消え、スコアが64→82に上昇。構造的な改善は人間の承認が必要で、完全自動は目指していません。

注意点・Tips

ディスク使用量: JSON 1エントリ約500B。1日10回×90日で約450KB
頻度は週1で十分: 毎日だとノイズが多い
修正diffは鵜呑みにしない: 構造変更は人間レビュー必須

skill-retrospectiveを使わなくても今日からできること

設計パターン自体はCLAUDE.mdへの追記だけで再現できます。

最小構成: CLAUDE.mdに3行追加する

## エラー記録ルール
- エラーが発生したら `errors.md` に「日付 / カテゴリ(lint|test|env|config) / 内容 / 対処」を追記すること
- 同じカテゴリのエラーが3回記録されていたら、このCLAUDE.mdに再発防止策を追記すること
- セッション終了時に errors.md を確認し、未対処のパターンがあれば報告すること

これだけで記録→検出→改善が回り始めます。

段階的にレベルアップするなら

レベル	やること	必要なもの
1	CLAUDE.mdにエラー記録ルールを書く	CLAUDE.mdだけ
2	errors.mdを週1で振り返り、CLAUDE.mdに対策追記	5分/週の習慣
3	カテゴリ別の発生回数をカウント、推移を見る	スプレッドシートでもOK
4	8軸フレームワークで構造的に分析	この記事の知識
5	skill-retrospectiveで全自動化	リポジトリ

レベル1-2だけでも、「同じエラーに3回ハマる」問題はかなり減ります。

AIエージェントのエラー処理設計: よくある疑問

Q. self-correctionとどう違うか？ 同一セッション内の反省か、外部ストレージで記憶を代替するかの違いです。本設計はプロンプト・ツール定義ファイルを更新します。

Q. AIに任せるリスクは？ diff生成のみ自動化し人間の承認を要件にして暴走を避けています。考え方はLLM非依存です。

Q. 他のLLMエージェント（GPT-5, Gemini等）でも使えるか？ ジャーナル記録・パターン検出・設定ファイル更新という考え方はLLM非依存です。ただしコード例はClaude CodeのSKILL.md仕様に基づいています。

背景: なぜ「自己改善」が必要なのか

Skillsで自動化しても、失敗パターンの蓄積と改善は人間の頭の中にしかなかった。フィードバックループが抜けていたためskill-retrospectiveを作りました。

まとめ

「AIツールが学習する」と聞くと大げさですが、やっていることはシンプルです。構造化されたログを溜めて、パターンを見つけて、設定ファイルを書き換える。違いは全部データで回ることです。

気軽に相談する

Claude Code エージェント・安全設計完全ガイド — 本記事含む13本で解説。エージェント活用・Hooks安全設計・並列開発を体系的にカバーしています。

AIエージェントが同じミスを繰り返さない3つの設計パターン【Claude Code実装例】

AIエージェントの「失敗学習」とは何か

典型的な失敗パターン3例

3つの設計パターン（概要）

パターン1: 構造化ログ（skill-retrospective）

ジャーナル: 構造化された実行ログ

パターン2: 8軸パターン検出

スコアリングで優先順位をつける

パターン3: SKILL.md自動修正

dev-flow-doctor: ワークフローの健康診断

ヘルススコアの計算

7つの診断チェック

session-save/load: コンテキストを失わない仕組み

自己改善サイクルの全体像

実際に回してみた所感

注意点・Tips

skill-retrospectiveを使わなくても今日からできること

最小構成: CLAUDE.mdに3行追加する

段階的にレベルアップするなら

AIエージェントのエラー処理設計: よくある疑問

背景: なぜ「自己改善」が必要なのか

まとめ

関連記事

この技術が解決した業務課題

【自社導入事例】ブログ運用を完全自動化 - GitHubリポジトリから記事・サムネイル・SNS投稿まで

【AI開発】2026年版・始め方ガイド — 小規模チームのスタック選定チェックリスト

【AIエージェント × 営業】月5万のSaaSを使わず、2人チームがAI SDRを自作した全体像

関連ソリューション

AI実装支援

関連記事

この技術、実際の現場ではこう使われています

AIエージェントが同じミスを繰り返さない3つの設計パターン【Claude Code実装例】

AIエージェントの「失敗学習」とは何か

典型的な失敗パターン3例

3つの設計パターン（概要）

パターン1: 構造化ログ（skill-retrospective）

ジャーナル: 構造化された実行ログ

パターン2: 8軸パターン検出

スコアリングで優先順位をつける

パターン3: SKILL.md自動修正

dev-flow-doctor: ワークフローの健康診断

ヘルススコアの計算

7つの診断チェック

session-save/load: コンテキストを失わない仕組み

自己改善サイクルの全体像

実際に回してみた所感

注意点・Tips

skill-retrospectiveを使わなくても今日からできること

最小構成: CLAUDE.mdに3行追加する

段階的にレベルアップするなら

AIエージェントのエラー処理設計: よくある疑問

背景: なぜ「自己改善」が必要なのか

まとめ

関連記事

この技術が解決した業務課題

【自社導入事例】ブログ運用を完全自動化 - GitHubリポジトリから記事・サムネイル・SNS投稿まで

【AI開発】2026年版・始め方ガイド — 小規模チームのスタック選定チェックリスト

【AIエージェント × 営業】月5万のSaaSを使わず、2人チームがAI SDRを自作した全体像

関連ソリューション

AI実装支援

関連記事

この技術、実際の現場ではこう使われています