kpt

# 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` が落とし、レビューで指摘されない」。書けなければ願望なので、削るか絞る。 置き場所は次の順に考える。 1. **機械で判定できる誤り**（決まった書き方、使ってはいけない API、ファイルの置き場所）は検査にする（lint の規則、テスト、CI、pre-commit）。 先にリポジトリの既存の検査コマンドと CI を見て、検査があるのに繋がっていない・壊れているならそれを直す。 2. **判断を要する決まり**は、レビューで読まれる場所（コーディング規約、レビューの観点）に書く。 3. **常に読み込まれる指示ファイル**（CLAUDE.md、AGENTS.md、copilot-instructions.md）には、他の文書への道しるべだけを足す。 ここは毎回文脈を使うので、足す前に削れる文を探す。 4. **特定の作業でだけ要る手順**はスキルにする。 1 つの Try が大きい（複数のファイルにまたがる、設計の判断が要る）ときは、その場で直さず、単独で終えて確かめられる単位に切って チケット（issue）にする。チケットには、できるようになること・受け入れ条件・先に終わっているべきチケットを書く。 ## 5. 見せて、承認されたものだけ反映する 前回の Try の判定、Keep、Problem、Try をユーザーに見せる。Try ごとに反映してよいかを訊く。 - 承認された小さな Try はその場で反映し、検査なら一度走らせて、今回の誤りを捕まえることを確かめる。 - 承認された大きな Try はチケットにする。 - 断られた Try は状態を「捨てた」にして理由を残す（同じ提案を繰り返さないため）。 承認なしに指示ファイル・検査・スキルを変えない。 ## 6. 記録する 選んだ出力先に新しい記録を書く。空の節は書かない。終わっていない Try（「試す」のもの）は前回の記録から引き継いで載せる。 ```markdown # KPT <YYYY-MM-DD> <セッションの題> 対象: <セッションの範囲と、読んだ一次資料> ## 前回の Try の検証 - <Try> — 効いた / 効かなかった / 確かめられない（<回数>回目）: <根拠> ## Keep - <事実> — <根拠> ## Problem - <事実> — <根拠>。原因: <たどり着いた原因> ## Try - <何を変えるか>（置き場所: <パス>） - 確かめ方: <効いていれば次のセッションで何が起きる・起きないか> - 状態: 試す / 効いた / 効かなかった / 捨てた（<理由>） - 反映: <コミット・チケット> ```