retro

retro

概要

作業セッションの最後に、摩擦点（ユーザーとエージェントの間でつまずいたこと）を特定し、 それぞれの根本原因を突き止め、次回以降のセッションがより円滑に進むよう、具体的な編集内容を提案します。 これらはリポジトリに反映されるため、バージョン管理され、すべてのマシンで同期されます。

中心となる原則：繰り返される摩擦点 = 不足しているルール。レトロでは、セッションで暗黙に示されたフィードバックを、 事後検証と同じように、保存され、実行に移せるテキストに変換します。

このスキルは現在進行中の会話（すでにコンテキストに含まれている会話）を分析します。外部のトランスクリプトファイルは解析しません。

使用する場面

• ユーザーが「レトロ」「セッションの振り返り」「どこでつまずいた？」「retro」と言う、または /retro を実行したとき
• セッションの終わり、または何度もやり取りを重ねたタスクの後
• ユーザーが一時的な不満を、継続的な改善につなげたいとき

使用しない場面：

• セッションが単純だった場合（質問が1つだけで、修正もなかった場合）→ 反映すべき特筆事項はないと伝えます
• コンテキストが大幅に圧縮されている場合 → レトロで確認できるのはコンテキストに残っている内容だけだと伝えます（ 制限事項を参照）

制限事項

• レトロで確認できるのは現在コンテキストにある会話だけです。圧縮が行われている場合、序盤の摩擦点が 失われている可能性があります。そのことを明示し、作り上げないでください。
• 測定は行いません（ここでは OpenTelemetry のメトリクスはありません）。摩擦の兆候を定性的に分析します。

特定する摩擦の兆候

会話を確認し、それぞれについて該当するターンとともに記録します：

兆候	見分け方
ユーザーによる修正	「違う」「むしろ」「実は」「そうではなく」、指示の言い換えなど
方向転換	エージェントが誤った方向に進んだ後、ユーザーが軌道修正する
誤った仮定	エージェントが不正確なこと（パス、慣例、意図）を仮定し、後で訂正する
繰り返しの確認	最初に確認できていれば避けられたはずの要件を把握するために、何度もやり取りする
放棄されたアプローチ	作業を破棄したり、後からやり直したりする
手作業での修正	エージェントが作成したものを、ユーザー自身が修正する
権限の拒否	必要な許可が事前に用意されていなかったため、操作がブロックされる
ツール使用時の摩擦	リポジトリへの不慣れ（ツールチェーン、パス、慣例）が原因でコマンドが失敗する

ワークフロー

1. 分析する

会話を読み返し、特定した摩擦点を列挙します。それぞれについて、何が起きたのか、いつ起きたのか、どのような影響があったのか （時間のロス、手直し、不満）を記録します。

2. 根本原因を突き止める

摩擦点ごとに、次の問いに答えます：最初から何があれば、これを防げたでしょうか？ 典型的な原因は次のとおりです：

• エージェントが知っておくべきだったルール／慣例の不足 → rules/ または CLAUDE.md が対象
• 再利用できる一連の手順など、手続きに関するノウハウの不足 → skills/ が対象
• ユーザー側の指示の曖昧さ → 設定の編集ではなく、より明確な伝え方についてのメモ
• 繰り返し発生しない一時的なコンテキスト不足 → 反映しない（過剰な反映はノイズになります）

摩擦点のすべてをルールに変換しないでください。一時的な摩擦点にルールを設ける必要はありません。 今後も 再発する可能性が高いものを優先してください。

3. 各レッスンを適切な保存先に振り分ける

レッスンの性質	保存先	理由
再利用可能なノウハウ（手順、ワークフロー）	.claude/skills/<nom>/SKILL.md	呼び出し可能で、description によって起動される
覚えておくべきルール／事実、特定のトピックに関するもの	.claude/rules/<sujet>.md	毎回のセッションで自動読み込みされ、バージョン管理される
中核となる、横断的で常に有効な規約	CLAUDE.md	常にコンテキストに含まれ、チーム全体に共有される
1 台だけに固有の事実	自動メモリ（~/.claude/…）	まれなケース。同期されないため、避けること

「リポジトリ内」の保存先（rules/skills/CLAUDE.md）はすべて Git でバージョン管理されるため、マシン間で同期され、チームで共有されます。これを既定の選択肢とします。

4. 提案する — そして STOP

提案の表を提示し、まだ何も書き込まず、ユーザーの明示的な承認を待ちます。形式：

Frictions de la session :

1. <friction> (tour ~N)
   Cause racine : <cause>
   → Proposition : <action> dans <fichier cible>
     Texte exact à ajouter/modifier :
     ----
     <le contenu précis>
     ----

2. …

Aucune capitalisation pour : <frictions jugées ponctuelles, listées avec une phrase de justification>

提案のルール：

• 曖昧な「X を改善する」ではなく、書き込む正確なテキストを提示します。
• 正確な対象ファイルを示します。
• 既存のルールが関係する場合は、重複させず、変更（統合／更新）を提案します。rules/ と CLAUDE.md が肥大化しないよう、ADD / MERGE / DELETE の考え方を適用します。
• 記録しない内容と、その理由も明記します（ノイズを抑えるための透明性）。

表の後に、「すべて／一部／何も適用しませんか？」 と尋ねて、回答を待ちます。

5. 適用する

承認を得たら、採用された提案だけを書き込みます。

• 新しい事実／ルール → .claude/rules/<sujet>.md を作成／編集する
• 新しいノウハウ → .claude/skills/<nom>/SKILL.md を作成する（frontmatter に name と description を記載し、このスキルの構成をモデルとして使用する）
• 横断的な規約 → CLAUDE.md を編集する

6. 締めくくる

• 書き込んだ内容をまとめます（ファイルの一覧）。
• これらはバージョン管理されるファイルであることを伝え、コミットを提案します（勝手にコミットせず、/commit を提案します）。

ガードレール

• 承認を得る前に書き込まない（ステップ 4 は必須）— commit スキルと同様です。
• 過度に記録しない：健全なセッションでもルールが何も生まれないことがあります。それも妥当な結果です。
• 重複するルールを追加するより、既存のルールを変更することを優先します。
• 確認せずにコミットしないでください。
• 振り返りの対象が圧縮済み／部分的なコンテキストだけの場合は、セッション全体を網羅したかのように装わず、その旨を伝えます。