ども！毎日 Claude Code と一緒に仕事している龍ちゃんです。
この記事を読むと、こんなことができるようになります。
- 「また同じミスだ」をゼロにする — セッション中のミスを「教訓ファイル」として即記録する方法
- CLAUDE.md・スキル・設定を教訓ベースで改修して、Claude Code 環境を自分仕様に育てられる
- 教訓ファイルをバグチケットとして消化→削除するサイクルで、改善が自然と回り続ける
毎日 Claude Code と話してると、同じ回避を繰り返してないか？
毎日Claude Codeと話していると「あれ、この問題、先週もやったな」ってデジャブを感じています。その場その場でプロンプトを工夫して乗り越えてはいるんですが、同じ摩擦が繰り返し起きてないか？と。
Claude Code を日常的に使っていると、セッションごとに新しい切り口で問題が起きますよね。「この指示だと意図通りに動かない」「なぜかこのコマンドがエラーになる」みたいなやつです。
そのたびにプロンプトを工夫したり、入力を変えて回避する — これ自体は普通のことで、短時間で結果を出すためには必要な判断です。
ただ振り返ってみると、実は同じパターンの問題が何回も起きていたりします。僕も「あ、これ3回目だ」と気づいた瞬間がちょっと「ぞわ！」とします。。その場の回避で作業は進む。でも回避だけで終わらせていると、同じ摩擦がずっと残り続けませんか？
いつかは改善点として整理しないと、Claude Code 環境が育たない。じゃあミスを記録して改修に回す流れを作っておこう、というのが今回の話です。
セッションから情報を吸い出して課題と解決策を整理する
まず全体像を見てもらったほうがイメージしやすいので、先に流れを整理しますね。
やっていることはシンプル
ポイントは「教訓ファイルはバグチケット」だということです。永続的なナレッジとして積み上げるのではなく、改修したら消す。「ファイルがある = まだ対応していない」というシンプルなルールにしています。
これ、地味に重要で。残しておくと「解決済みなのか未解決なのか」が分からなくなりません？消すことで改修が完了したことが一目でわかります。
なぜセッションから吸い出すのか
セッション中には AI の挙動・自分の指示・回避策のすべてが記録されています。問題が起きた直後が一番情報量が多い — 文脈も意図も再現手順も揃っている。後から「あれなんだっけ」と思い出すよりはるかに正確です。
僕がやっているのは「人間が書くのは意図だけ、事実と分析は AI に任せる」という分担です。「こうしてほしかったんだけど、こうなった」という意図だけ伝えれば、根本原因の分析まで AI がやってくれます。
吸い出し方 — 即起票とエクスポートの2パターン
具体的にどうやって教訓を抽出するか。2つの方法があって、場面によって使い分けています。
方法A: セッション中にその場で教訓ファイルを生成（即起票）
ミスや意図のズレが起きた → 回避策を打った → そのタイミングで AI にまとめさせる、というやり方です。
セッションの文脈がまだ残っているうちに書かせるのがポイントで、問題が起きた直後に実行するから情報の鮮度が最大限に保たれます。実際に僕が投げるのはこんな感じです。
今回、スキルAに関してエラーが頻発して回避をしたと思うんだけど、
原因と対応についてまとめてくださいこれだけで、セッション中の文脈を拾って教訓ファイルを生成してくれます。この即起票の流れ自体をスキルにしておくと、/lesson のようにワンコマンドで教訓ファイルが生成できるので便利です。向いているのは、問題が起きた直後で原因がわりと明確なケースです。
方法B: セッションを丸ごとエクスポート → あとから分析
Claude Code には /export コマンドがあって、セッション全体をテキストに保存できます。
/exportでクリップボードに/export session.mdでファイルに出力
会話・ツール呼び出し・Bash コマンド・MCP 呼び出しが丸ごと残ります。~/.claude/projects/<cwd>/*.jsonl にも全セッションが自動保存されているので、後から拾うことも可能です。
エクスポートしたファイルを別のセッションで指定して、こんな感じで頼みます。
前回のセッションの振り返りをしたいです。
ファイルを読み込んで人間の指示とClaudeの受け取りで
齟齬が起きた箇所を解析して分析して対応方法を考えてくださいこれだけで、AI がセッション全体を読み込んで横断的にパターンを見つけてくれます。
向いているのは、1日の終わりや週次のふりかえり、「最近なんか同じことよく直してるな」みたいなセッション横断の繰り返しパターンを見つけたいときです。
使い分けの目安
| 方法A（即起票） | 方法B（エクスポート→分析） | |
|---|---|---|
| タイミング | 問題発生の直後 | 作業後・定期ふりかえり |
| 発見できるもの | 個別の意図のズレ・バグ | セッション横断の繰り返しパターン |
| 手間 | 一言で完了 | エクスポート→分析の2ステップ |
| 文脈の鮮度 | 最大限残っている | やや薄れる |
実用的なのは方法Aでその場の問題を拾い、方法Bで見逃したパターンを定期的に回収する併用です。
教訓ファイルのフォーマット
どちらの方法でも、最終的に出力するのはこの形式にしています。
# 教訓: {タイトル}
## 起因
何が起きたか。事実ベースで記述。
## 分析
なぜ起きたか。根本原因を掘り下げる。
## 教訓
次回どうするか。具体的なアクション。
## 適用範囲
この教訓が当てはまるケース。「何が起きたか」「なぜ起きたか」の事実と分析は AI が書く。「こうしてほしかった」という意図は人間が補う。この分担がうまく機能しています。
実際の教訓ファイルはこんな感じ
実際に僕の手元で生成された教訓ファイルの抜粋です。
# 教訓: plan.md の推奨モデルを無視した Opus → Sonnet 委譲失敗
## 起因
実装計画（plan.md）で「推奨モデル: Sonnet」と明記したにもかかわらず、
「実装を続けてください」と指示を受けた Opus が Sonnet に委譲せず
直接実装に着手しようとした。
## 分析
3つの要因が重なった:
1. **「実装して」を「自分で書け」と解釈するバイアス**
- 計画フェーズでは冷静に Sonnet 推奨と判断できたのに、
実行フェーズで自分の計画を無視した
2. **ロール切り替えの失敗**
- 正しいロール: オーケストレーター（Sonnet に指示を出し、進捗を管理）
3. **CLAUDE.md ルールの実行時無視**
## 教訓
1. 実装開始時に plan.md の「推奨モデル」セクションを最初に確認する
2. Sonnet 推奨の場合、Opus はオーケストレーターに徹する
## 適用範囲
- plan.md に「推奨モデル」セクションがある全ての実装タスクテンプレートに沿って書かせると「何が・なぜ・どう直すか」が揃うので、改修に回すときに方針を考える手間がほぼなくなります。
実例で見る「吸い出し→改善→削除」
実際にどんな改修になるか、僕の手元で起きた事例で見ていきますね。
サムネイルパス問題 → スキルの実装方式を変更
「テンプレートの相対パスが Playwright 実行時に壊れる」という問題が、実は3回繰り返し発生していたんですよね。
最初は「パスを直せば動く」で済ませていたんですが、3回目でさすがに「これ構造の問題だな」と気づいて、教訓ファイルを書かせました。
教訓ファイルが根本原因を突いていて「HTML の保存先が変わると即アセットが壊れる構造的問題」と。発生パターンも3つ特定してくれていました。
対処療法で直していたら何度でも同じことが起きていたはずで、「templates/ 内でレンダリング→PNG だけ移動」という方式に変更することで構造ごと直しました。これが教訓ファイルの真価で、根本原因が明確だから対処療法ではなく構造的な改修になるんですよね。
改修が終わったら、教訓ファイルを削除。これでサイクルが1周です。削除のタイミングは2つのやり方があって、改修を入れたらその場で消すか、1週間など期間を決めて定期的にまとめて消すか。僕は改修直後に消す派ですが、まとめて振り返りたい人は定期削除のほうが合うかもしれません。どちらでも「ファイルがある = 未対応」というルールさえ守れば機能します。
他にもこんな事例
僕の手元で起きた他の事例も紹介しておきますね。改修先がバラバラなのがポイントです。
| 問題 | 教訓ファイルの分析 | 改修先 |
|---|---|---|
| plan.md に「推奨モデル: Sonnet」と書いたのに Opus が直接実装しようとした | 「実装して」を「自分で書け」と解釈するバイアス | CLAUDE.md にルール追記 |
uv run html-screenshot が Failed to spawn エラー | workspace member のスクリプトはルートから自動解決されない | スキルのコマンド例 を修正 |
教訓ファイルがなければ「またこれか」で終わっていた問題ばかりです。教訓ファイルが「どこを直すべきか」まで教えてくれるので、改修の方針を考える時間がほぼゼロになります。
まとめ: Claude Code 環境は「使って→吸い出して→直す」で育てる
セッションの中に改善のヒントが全部あります。それを吸い出す仕組み（教訓ファイル）を持っておくだけで、改善が自然と回り始めます。
まとめると、
- 教訓ファイルはバグチケット。溜めずに消化して、消す
- 方法Aで問題発生の直後に拾い、方法Bで定期的に見直す
- AI に根本原因を分析させれば、改修先まで特定してくれる
この「1回のミスを確実に拾う」仕組みが積み重なると、「3回繰り返したら仕組みにする」というサイクルにも自然と繋がっていきます。僕が以前書いた Copilot チャット履歴から copilot-instructions.md と SKILL.md を育てる方法 で紹介したポストモーテムの考え方の前段として、まずは1回の問題を漏らさず拾うところから始めてみてください。
Claude Code の設定ファイルの書き方や運用のコツは 公式のベストプラクティスも参考になります。
ほなまた〜
