kpt
セッション(エージェントとの一続きの作業)を振り返り、次のセッションが同じところでつまずかないように環境を直す。 Keep・Problem・Try を並べて終わりにしない。Try は「何をどこに変えるか」と「効いたかの見分け方」を決めて記録し、 次の振り返りで確かめる。
前回の記録 → 1. 前回の Try を検証 → 2. 一次資料を読む → 3. Keep / Problem → 4. Try を決める → 5. 承認・反映 → 6. 記録
↓
次の振り返りの 1. へ
記録の出力先
記録の中身(6. の形)はどこに出しても同じで、出力先だけを選べる。ユーザーが依頼の中で言った出力先を使う。
言わなければ、指示ファイル(CLAUDE.md、AGENTS.md、copilot-instructions.md など)に kpt の出力先: <出力先> と書いてあればそれを使い、
どちらも無ければファイルに書く。
| 出力先 | 書き方 | 前回の記録の読み方 |
|---|---|---|
| ファイル(既定) | .kpt/<YYYY-MM-DD>-<英語の短い名前>.md(ワークスペースのルート)。別のフォルダを言われればそこへ |
同じフォルダの最新のファイル |
| エージェントの長期記憶 | エージェントが持つ記憶の機能(Claude Code のメモリなど)に、題を KPT <YYYY-MM-DD> として 1 件で保存する |
題が KPT で始まる最新の記憶 |
| ltm-use | ltm-use の save に渡す(題 KPT <YYYY-MM-DD> <セッションの題>、本文に記録の全文) |
ltm-use の recall で KPT を探し、最新の 1 件 |
| wiki-use | wiki-use の ingest に渡す | wiki-use の query で KPT を探し、最新の 1 件 |
| ほかのスキル・道具 | そのスキルの保存の操作に記録の全文を渡す(チケットにするなら Try を 1 件ずつ) | そのスキルの検索の操作で最新の 1 件 |
出力先のスキル・道具が使えないとき(入っていない、設定が無い)は、黙ってファイルに切り替えない。使えない理由を伝え、ファイルに書いてよいかを訊く。
終わっていない Try は新しい記録に引き継ぐので、検証で読むのは最新の 1 件だけでよい。 記録をコミットするかはユーザーに任せる。
1. 前回の Try を検証する
最新の記録の Try のうち、状態が「試す」のものを 1 つずつ、その「確かめ方」に照らして今回のセッションを見る。 先に、Try の変更が置き場所に今も残っているかを見る(消えていれば「確かめられない」とし、消えた理由を書く)。
| 判定 | 根拠 | 次にすること |
|---|---|---|
| 効いた | 確かめ方に書いた信号が今回のセッションに出た | 状態を「効いた」にし、Keep に載せる |
| 効かなかった | 同じ Problem がまた起きた | Problem に戻し、なぜ効かなかったかを 3. で掘る。同じ Try を言い換えて出し直さない |
| 確かめられない | 今回のセッションにその場面が無かった | 引き継ぐ。3 回続けて確かめられなければ確かめ方が悪いので、書き直すか捨てる |
判定には今回のセッションの中の根拠(発言・コマンドの出力・差分)を添える。根拠を示せない「たぶん効いた」は「確かめられない」とする。
2. 一次資料を読む
ユーザーが指すセッションを読む。指定が無ければ今のセッション。記憶ではなく、会話・コマンドの出力・差分・CI の結果・
レビューのコメントから拾う。Claude Code の過去のセッションは ~/.claude/projects/ の下に .jsonl で残っている。
引用する出力に秘密(トークン・認証ヘッダ・パスワード)があれば <REDACTED> に置き換える。
3. Keep と Problem を洗い出す
どちらも事実で書き、1 項目に根拠を 1 つ(どこで何が起きたか)添える。
Keep は次も同じようにやる価値があることだけ。たまたまうまくいったことは載せない。
Problem は症状で止めず、環境で直せる原因までたどる。「なぜそうなったか」を、次の観点のどれかに届くまで繰り返す。
| 観点 | 兆候 |
|---|---|
| 道しるべ | 必要なファイルや情報を探すのに手間取った。ファイル間に書かれていない依存があった |
| 自動の検査 | 検査で捕まえられたはずの誤りを人やレビューが見つけた。検査はあるのに繋がっていない、壊れている |
| 決まり | 守るべき決まりが書かれていない、曖昧、または読まれない場所にある |
| 進め方 | 再現や確認をせずに推測で直した。承認を待たずに作った |
| 情報の入手 | 判断に要る情報(ログ、外部サービスの状態)に届かなかった |
| 道具の無駄 | 高くつく呼び出しや、同じ探索の繰り返しがあった |
| 指示ファイルの肥大 | 常に読み込まれる指示ファイルに、振る舞いを変えない文や検査に移せる文がある |
原因が 1 つに絞れないときは、候補を 2〜3 個挙げ、それぞれ「これが原因なら、何を変えれば次は起きないか」を言える形にする。 言えない候補は捨てる。
Problem は重い順(ユーザーの手戻りや時間を多く使った順)に並べる。人を責める書き方をしない。
4. Try を決める
Problem 1 つにつき Try は多くて 1 つ。1 回の振り返りで Try は多くて 3 つ(多いと次回に確かめきれない)。 「気をつける」「意識する」は Try にしない。環境の変更にする。
各 Try には次の 2 つを書く。
- 何を変えるか: 置き場所(ファイル・検査・スキル)と変更の中身。
- 確かめ方: 効いていれば、次のセッションで何が起きる(起きない)か。観察できる信号で書く。
例: 「同じ種類の誤りを
npm testが落とし、レビューで指摘されない」。書けなければ願望なので、削るか絞る。
置き場所は次の順に考える。
- 機械で判定できる誤り(決まった書き方、使ってはいけない API、ファイルの置き場所)は検査にする(lint の規則、テスト、CI、pre-commit)。 先にリポジトリの既存の検査コマンドと CI を見て、検査があるのに繋がっていない・壊れているならそれを直す。
- 判断を要する決まりは、レビューで読まれる場所(コーディング規約、レビューの観点)に書く。
- 常に読み込まれる指示ファイル(CLAUDE.md、AGENTS.md、copilot-instructions.md)には、他の文書への道しるべだけを足す。 ここは毎回文脈を使うので、足す前に削れる文を探す。
- 特定の作業でだけ要る手順はスキルにする。
1 つの Try が大きい(複数のファイルにまたがる、設計の判断が要る)ときは、その場で直さず、単独で終えて確かめられる単位に切って チケット(issue)にする。チケットには、できるようになること・受け入れ条件・先に終わっているべきチケットを書く。
5. 見せて、承認されたものだけ反映する
前回の Try の判定、Keep、Problem、Try をユーザーに見せる。Try ごとに反映してよいかを訊く。
- 承認された小さな Try はその場で反映し、検査なら一度走らせて、今回の誤りを捕まえることを確かめる。
- 承認された大きな Try はチケットにする。
- 断られた Try は状態を「捨てた」にして理由を残す(同じ提案を繰り返さないため)。
承認なしに指示ファイル・検査・スキルを変えない。
6. 記録する
選んだ出力先に新しい記録を書く。空の節は書かない。終わっていない Try(「試す」のもの)は前回の記録から引き継いで載せる。
# KPT <YYYY-MM-DD> <セッションの題>
対象: <セッションの範囲と、読んだ一次資料>
## 前回の Try の検証
- <Try> — 効いた / 効かなかった / 確かめられない(<回数>回目): <根拠>
## Keep
- <事実> — <根拠>
## Problem
- <事実> — <根拠>。原因: <たどり着いた原因>
## Try
- <何を変えるか>(置き場所: <パス>)
- 確かめ方: <効いていれば次のセッションで何が起きる・起きないか>
- 状態: 試す / 効いた / 効かなかった / 捨てた(<理由>)
- 反映: <コミット・チケット>