「あれ、このエラー、先週も見た気がする...」
同じlintエラーで止まる。同じnode_modulesの不整合で5分ロスする（あのブラックホールみたいなディレクトリ、不整合のほうが自然状態では？）。同じ型エラーの対処を、何度も手動で指示する。AIエージェントなのに、前回の失敗を覚えていない。
「学習するはずのAIが、毎回同じところでコケるのはなぜ？」...心当たりありませんか？
私たちも半年間、同じ壁にぶつかっていました。Skillsを作り込んでワークフローを自動化しても、失敗パターンの蓄積と改善は人間の頭の中にしかなかった。そこで作ったのが、Skillsが自分自身を書き換える仕組み -- skill-retrospectiveです。
この記事で学べること
- 設計パターン: AIエージェントの失敗を「構造化ログ → パターン検出 → 設定自動修正」の3ステップで回す方法
- 5軸分析フレームワーク: エラーの「なぜ」を構造的に分類する考え方（CLAUDE.mdだけでも使える）
- 定量ヘルス診断: ワークフローの弱点を「雰囲気」ではなく数値で特定するアプローチ
- セッション間の学習永続化: Claude Codeのコンテキスト消失問題に対する実践的な対策
前提知識
- Claude Codeを日常的に使っている（Skillsの利用は問わない）
- 「同じエラーに2回以上ハマった経験がある」（たぶん全員該当）
この記事では私たちが作ったskill-retrospectiveを実装例として紹介しますが、設計パターン自体はCLAUDE.mdへの追記だけでも応用できます。
なぜ「自己改善」が必要なのか
これまでのシリーズでは、Skillsの「使い方」を中心に紹介してきました。
| 記事 | テーマ |
|---|---|
| Skills入門 | 設計思想と自作ガイド |
| 状態管理 | auto-compact対策 |
| Hooks連携 | 品質ゲート自動化 |
| worktree並列 | タスク分解と統合 |
| Agent Team | マルチエージェント協調 |
どれも「Skillsをどう動かすか」の話。でも、動かした結果のフィードバックループが抜けていた。
人間の開発チームなら、スプリントレトロスペクティブで振り返って改善する。CI/CDなら、失敗したビルドのログを見て設定を直す。じゃあAIエージェントのスキルは？ -- 誰かが気づいて、手動でSKILL.mdを編集する。それって、CIのログを見てymlを手書きしてた時代と同じじゃないですか（...え、まだやってる？ やってますよね。私もです）。
skill-retrospective: 失敗から学ぶメタスキル
skill-retrospectiveは、Skillsの実行履歴を分析して、SKILL.mdの修正diffを自動生成するメタスキルです。
全体のフロー
1. COLLECT → ~/.claude/journal/ からエントリ読み込み
2. FILTER → 前回レトロスペクティブ以降の未分析エントリを抽出
3. ANALYZE → 5軸でパターン検出
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": "20260430T103000Z-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つのカテゴリに分類していること。lint、test、build、runtime、config、env、merge、type-check。8つもあるのに、うちのプロジェクトだとenvとlintで7割を占めてました（偏りすぎ）。この分類があるから、後段の分析で「どの種類のエラーが多いか」を定量的に捉えられる。
「またlintで引っかかった」と人間が雰囲気で感じているものを、数字に変える仕組みです。
Skillsなしでも使えるポイント: ジャーナルの仕組みは大げさなスクリプトがなくても再現できます。CLAUDE.mdに「エラーが起きたら
errors.mdに日付・カテゴリ・内容を追記すること」と1行書くだけで、構造化ログの第一歩になる。大事なのはツールではなく**「記録する」という習慣をエージェントに埋め込む**こと。
5軸パターン検出: エラーの「なぜ」を構造的に分析する
ジャーナルが溜まったら、skill-retrospectiveが5つの軸でパターンを検出します。
| 軸 | 何を見るか | 検出例 |
|---|---|---|
| Recurring failures | 同じエラーが2回以上 | node_modules missing が3回 |
| Instruction gaps | SKILL.mdにエラー対策の記述がない | git-prepareにnpm install手順なし |
| Guard deficiency | 前提条件チェックが不足 | lockfileの存在確認がない |
| Workflow inefficiency | リカバリに2ターン超（5超で重大） | validate→fix→validateの繰り返し |
| Environment issues | 環境系エラーの集中 | .env不足、依存関係の不整合 |
単に「エラーが何回起きた」ではなく、なぜそのエラーが防げなかったかを構造的に分析するのがミソです。
スコアリングで優先順位をつける
pattern_score = frequency * impact * preventability
- frequency: 発生回数（多いほど深刻）
- impact: エラーカテゴリの重大度（
env=3,lint=1） - preventability: SKILL.mdでの対処可能性（記述なし=3, 部分的=2, 対処済み=1）
スコア9以上は即座に修正提案（3×3×3の「未対処・重大・頻発」フルコンボ。さすがにヤバい）。4以上はレトロスペクティブに含める。4未満は「まあ、メモしとくね」レベル。
人間のレトロスペクティブで「なんとなく気になってたけど後回し」になるやつを、掛け算で優先順位をつけて強制的に浮上させる（後回しの逃げ道を塞ぐ）。
あなたのプロジェクトでの応用: この5軸フレームワークは、skill-retrospectiveを使わなくても手動で回せます。
errors.mdを月末に眺めて「同じカテゴリのエラーが3回以上あったら、CLAUDE.mdに対策を追記する」。これだけでRecurring failuresとInstruction gapsの2軸はカバーできる。完璧な自動化より、まず記録→振り返りのサイクルを作ることが重要です。
SKILL.md自動修正: diffで提案する
パターンを検出したら、該当スキルのSKILL.mdを読んで、修正diffを生成します。
### Pattern #1: node_modules不整合 (3回発生)
**影響スキル**: git-prepare
**エラーカテゴリ**: env
**根本原因**: worktree作成後にnpm installが実行されない
**再発リスク**: 高
**スコア**: 3 x 3 x 3 = 27
**修正案** (git-prepare/SKILL.md):
## Post-Checkout Steps
...
+ ## Dependency Check (Auto-added by retrospective)
+ After checkout/worktree creation, verify dependencies:
+ ```bash
+ if [[ -f package-lock.json ]] && [[ ! -d node_modules ]]; then
+ npm ci
+ fi
+ ```
ユーザーには3つの選択肢が提示されます。
- 承認 -- そのまま適用
- 修正して承認 -- 内容を調整してから適用
- 却下 -- この提案をスキップ
完全自動ではなく、人間が最終判断する。AIが「自分の説明書を勝手に書き換える」のはさすがに怖いので（暴走フラグ）、承認ゲートを入れています。--applyフラグで信頼モードにもできますが、慣れてからの話。
dev-flow-doctor: ワークフローの健康診断
skill-retrospectiveが「個別の失敗パターン」を見るのに対して、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つの診断チェック
dev-flow-doctorは7つのチェック項目を順に実行します。
Check 1: モード分布 -- single vs parallelの使用比率。auto-detectが正しく機能しているか。
$SKILLS_DIR/skill-retrospective/scripts/journal.sh query \
--skill dev-flow --limit 200 | \
jq 'group_by(.context.mode // "unknown") |
map({mode: .[0].context.mode // "unknown", count: length})'
「全部singleモードで動いてる」なら、auto-detectが保守的すぎる可能性がある（シングルモード教の信者になってないか確認）。逆に「parallelばかり--force-parallelで強制指定」なら、auto-detectが期待通りに動いていない。
Check 2: 失敗フェーズ分布 -- どのフェーズで失敗が集中しているか。
implementフェーズの失敗が30%を超えていたら、Issue分析の深度が足りない（3回に1回コケてるなら、石の多い道を歩いてます）。validateフェーズが40%を超えていたら、事前lintの自動化が必要。数字でボトルネックが見えるのが、雰囲気レトロスペクティブとの決定的な違いです。
Check 3: エラーカテゴリ分布 -- lintが40%を超えていたらエディタ設定の見直し。envが30%を超えていたらdev-env-setupの統合を検討。
Check 4: Worktree健全性 -- 7日以上放置されたworktreeや、kickoff.jsonのない孤立ディレクトリを検出。
Check 5: 平均リカバリターン数 -- 2.0未満なら問題なし。5.0を超えたら、skill-retrospectiveで改善提案を回すタイミング。
Check 6: 成功率トレンド -- 直近7日 vs 全期間を比較。改善傾向ならレトロスペクティブが機能している証拠。悪化傾向なら新しい失敗パターンが発生中。
Check 7: 所要時間の外れ値 -- 異常に長い実行を検出。parallelモードなら想定内。singleモードで12ターン超えは、何かがおかしい。
診断レポートの例
## Dev Flow Health Report
**Health Score**: 72/100 (Fair)
**Period**: 2026-03-01 ~ 2026-04-30
**Total Executions**: 127 (success: 108, failure: 7, partial: 12)
### Findings
1. **[WARN]** validateフェーズの失敗が38% → 事前lint自動化を推奨
2. **[WARN]** env系エラーが全体の25% → worktree後のdep installを自動化
3. **[INFO]** 直近7日の成功率90% (全期間: 85%) → 改善傾向
### Recommended Actions
- [ ] dev-validateにauto-fixモードを追加
- [ ] git-prepareにdependency checkを追加（← retrospectiveが提案済み）
ポイントは、dev-flow-doctorが問題を検出して、skill-retrospectiveが修正を提案する連携です。診断と治療を分けることで、それぞれの責務がシンプルになる。
ヘルススコアの考え方だけ持ち帰る: 減点方式のスコアリングは、自分のプロジェクトの「健康度」を定期的に把握するのに便利です。たとえば「直近1週間のClaude Code作業で、手動リトライが何回あったか」をカウントするだけでも、ワークフローの弱点が可視化される。スコアの計算式より、「定期的に数えて比較する」という習慣のほうが大事です。
session-save/load: コンテキストを失わない仕組み
ここまでの話は「実行ログ → 分析 → 改善」のサイクル。でも、もう1つ重要な要素があります。セッション間のコンテキスト永続化です。
Claude Codeはセッションが終わると文脈を失います（金魚かな？ と言いたいところだけど事実。auto-compactで途中でも失う。状態管理の記事で詳しく書きました）。レトロスペクティブの結果も、次のセッションに引き継がれなければ意味がない。
session-saveの役割
セッション終了時に/session-saveを実行すると、以下を永続化します。
- タスクの進捗
- 下した判断とその理由
- コード変更のサマリー
- 学んだことやインサイト
そして、レトロスペクティブとの連携チェックが入ります。
# 未分析の失敗エントリを確認
$SKILLS_DIR/skill-retrospective/scripts/journal.sh query \
--outcome failure --limit 100 2>/dev/null | jq 'length'
1件でもあれば、「3件の新規失敗エントリあり。/skill-retrospectiveで分析できます」と通知。フルの分析は走らせず、気づきだけ与えて判断は人間に委ねる設計です。
session-loadの役割
次のセッション開始時に/session-loadを実行すると、前回のコンテキストを復元します。CLAUDE.md、前回のメモリ、チェックポイント。
この「save → load」のサイクルが、レトロスペクティブの結果を次のセッションに引き継ぐ橋になっています。
Session A: 作業 → 失敗ログ記録 → /session-save（失敗通知あり）
↓
Session B: /session-load → /skill-retrospective → SKILL.md修正
↓
Session C: /session-load → 修正済みSKILL.mdで作業 → 同じエラーが出ない
3セッションで1つの改善サイクルが回る。人間がやることは「/session-saveと/session-loadを忘れずに打つ」だけ（RULES.mdに書いておけば、エージェントが自発的にやってくれる）。
自己改善サイクルの全体像
ここまでの要素を組み合わせると、こうなります。
┌─────────────────────────────────────────────────┐
│ 各スキル（dev-flow, dev-kickoff, bug-hunt...） │
│ → journal.sh で実行結果を記録 │
└───────────────┬─────────────────────────────────┘
│ ~/.claude/journal/*.json
▼
┌─────────────────────────────────────────────────┐
│ dev-flow-doctor │
│ → 7つの診断チェック → ヘルススコア算出 │
│ → 「どこが弱いか」を定量的に特定 │
└───────────────┬─────────────────────────────────┘
│ 問題箇所の特定
▼
┌─────────────────────────────────────────────────┐
│ skill-retrospective │
│ → 5軸パターン検出 → SKILL.md修正diff生成 │
│ → ユーザー承認 → 適用 │
└───────────────┬─────────────────────────────────┘
│ 改善されたSKILL.md
▼
┌─────────────────────────────────────────────────┐
│ session-save / session-load │
│ → コンテキスト永続化 → 次セッションに引き継ぎ │
│ → 未分析失敗の通知 │
└─────────────────────────────────────────────────┘
ジャーナル記録 → 定量診断 → パターン検出 → SKILL.md修正 → コンテキスト永続化。この一連のサイクルが、人間の介入を最小限にしながら回り続ける。
実際に回してみた所感
最初の1週間: ジャーナルが溜まるのを待つ
skill-retrospectiveを導入した直後は、分析するデータがない。まずは各スキルにjournal.shの呼び出しを1行追加して（「1行だけだから」と言いつつ、20スキルに追加するのは地味にしんどい）、1週間ほどログを溜めました。
2週目: 最初のレトロスペクティブ
/skill-retrospective --since 7dを実行。出てきたパターンの上位3つ。
- worktree作成後のnpm ci漏れ（env, 5回, スコア45）-- git-prepareのSKILL.mdに手順が一切なかった
- Biome formatエラーの繰り返し（lint, 8回, スコア8）-- dev-validateに
--fixモードの記述はあったが、デフォルトで有効になっていなかった - TypeScript strict エラー（type-check, 3回, スコア6）-- 新規ファイル作成時のtsconfig設定が不明確
1番目のスコア45は「Critical」を大幅に超えていて、もっと早く気づくべきだったと反省。人間の感覚では「たまにある」程度だったのに、数字にすると5回も（「たまに」の定義、見直したほうがいいかもしれない）。
3週目以降: サイクルが回り始める
修正済みのSKILL.mdで作業すると、1番目と2番目のエラーがほぼ消えた。dev-flow-doctorのスコアが64→82に上昇。数字で改善を確認できるのが、雰囲気レトロスペクティブとの違い。
ただし、修正diffの品質はまちまち。単純な「手順追加」は的確だけど、「ワークフローの順序変更」のような構造的な改善は、人間が修正して承認する必要がある。完全自動は目指していない。あくまで「下書きを作ってくれるアシスタント」です。
注意点・Tips
- ジャーナルのディスク使用量に注意: JSON 1エントリは約500B。1日10回実行 × 90日で約450KB。心配するほどじゃないけど、半年放置すると「いつの間にか数千件」になるので、古いエントリの定期アーカイブは考えておくと吉
- レトロスペクティブの頻度は週1で十分: 毎日回すとノイズが多すぎて「対処すべきパターン」と「偶発的なエラー」の区別がつかない。1週間溜めて初めて「繰り返し」が見える
- 修正diffは鵜呑みにしない: 単純な手順追加は的確だけど、ワークフロー構造の変更は人間のレビュー必須。AIの「自分で自分を書き換える」提案は、過剰に保守的か、逆に大胆すぎることがある（ちょうどいい塩梅は人間が決める）
- 最初はerrors.mdから始めてOK: フルのジャーナル基盤を作る前に、CLAUDE.mdへの3行追記で効果を実感してから拡張するのが現実的。「完璧な基盤を作ってから始めよう」は永遠に始まらないフラグ
skill-retrospectiveを使わなくても今日からできること
この記事ではskill-retrospectiveの実装を紹介しましたが、設計パターン自体はCLAUDE.mdへの追記だけで再現できます。
最小構成: CLAUDE.mdに3行追加する
## エラー記録ルール
- エラーが発生したら `errors.md` に「日付 / カテゴリ(lint|test|env|config) / 内容 / 対処」を追記すること
- 同じカテゴリのエラーが3回記録されていたら、このCLAUDE.mdに再発防止策を追記すること
- セッション終了時に errors.md を確認し、未対処のパターンがあれば報告すること
これだけで記録→検出→改善のサイクルが回り始めます。ジャーナルスクリプトもスコアリングも不要。AIエージェントは指示されれば記録するし、パターンを見つけたら報告する。足りないのはツールではなく、「記録して振り返れ」という明示的な指示です。
段階的にレベルアップするなら
| レベル | やること | 必要なもの |
|---|---|---|
| 1 | CLAUDE.mdにエラー記録ルールを書く | CLAUDE.mdだけ |
| 2 | errors.mdを週1で振り返り、CLAUDE.mdに対策追記 | 5分/週の習慣 |
| 3 | カテゴリ別の発生回数をカウント、推移を見る | スプレッドシートでもOK |
| 4 | 5軸フレームワークで構造的に分析 | この記事の知識 |
| 5 | skill-retrospectiveで全自動化 | リポジトリ |
レベル1-2だけでも、「同じエラーに3回ハマる」問題はかなり減ります。私たちもレベル1から始めて、手動運用の限界を感じてからskill-retrospectiveを作りました。
まとめ
「AIツールが学習する」と聞くと大げさに聞こえるかもしれません。でもやっていることはシンプルです。構造化されたログを溜めて、パターンを見つけて、設定ファイルを書き換える。人間の開発チームがレトロスペクティブでやっていることと、本質的に同じ。
違いは、全部データで回ること。「なんとなく気になってた」を数字にして、「いつか直そう」をスコアで強制浮上させて、「同じミスを繰り返さない」をCLAUDE.mdやSKILL.mdの修正で担保する。
大事なのはツールの導入ではなく、フィードバックループを構造化するという考え方。CLAUDE.mdへの3行追記から始めるか、skill-retrospectiveで全自動化するかは、あなたのプロジェクトの規模と痛みの深さ次第です。
「あれ、このエラー、先週も見た気がする」をもう言わなくて済む世界、意外と近くにあります。
