retrospective-codify

レトロスペクティブの形式知化

タスクの終わりが近づいたら、「これを最初に知っていれば、回り道をせずに済んだ」という知見を抽出し、静的ルール、スキル、常時適用ルールのいずれかとして定着させます。プロンプトに依存しない、再現可能な形式で反映することを優先します。

使用する場面

• タスクの完了直前、またはユーザーが「学びを残して」や「形式知化して」と言ったとき
• 試行錯誤を経て解決にたどり着いたとき（最初の試みで行き詰まった、誤った仮説を立てた、ドキュメントがなく時間を浪費した、など）
• 将来、同様のタスクを再び行う可能性があるとき

使用しない場面：

• 最初の試みでうまくいった簡単なタスク（抽出するものがありません）
• プロジェクト固有の一度限りの対応（コミットメッセージで十分です）

ワークフロー

1. 失敗と成功を対比する：現在のタスクについて、次の3点を書き出します。

   • 最初の試み（何をしたか／どのように失敗したか）
   • 最終的な解決策（何がうまくいったか）
   • つなぐ知見（なぜ最初の試みでは解決できなかったか）

2. 「最初に知っておくべきこと」を言語化する：知見を1〜3文にまとめます。振り返りではなく、未来の自分への指示として、命令形で書きます（「Xをしてはいけない」／「まずYを確認する」）。

3. 分類する：以下の判断表に従って、出力先を決めます。

4. 重複を確認する（必須）：提案する前に、既存の知識と照合します。重複または関連するルールがある場合は、「新規追加」ではなく「既存の項目に追記／更新」を選びます。この手順を省くと、スキル／ルールが肥大化します。

   知見から検索キーを2〜3個抽出します（ツール名、API 名、症状を表す語、対義語など）。例：知見が「pnpm v10 を使う」なら、pnpm、packageManager、lockfile を使います。

   照合対象と最低限の検索数：

   # skill duplicates (global)
   ls ~/.claude/skills/
   Grep "<key>" ~/.claude/skills/*/SKILL.md
   
   # CLAUDE.md duplicates
   Grep "<key>" ~/.claude/CLAUDE.md
   Grep "<key>" <project-root>/CLAUDE.md   # if there is a matching project
   
   # lint rule duplicates
   ls <project-root>/rules/
   Grep "<key>" <project-root>/rules/
   

   検索結果を次の4段階に分類します。

   • 新規：該当なし → 通常の提案
   • 既存項目に追記：関連するスキル／ルールがあり、新しい情報が補足的な内容である → 「既存項目に追記」を提案する
     • 「一部重複」（知見の一部が既存項目でカバーされ、残りが新しい場合）もこの段階に含まれます。重複部分は「重複を確認」に、新しい部分は「採用候補」（[skill append] または [rule]）に、それぞれ分けて記載します。
   • 既存項目と重複（提案不要）：既存項目が同じ知見をすでに完全にカバーしている → 提案はゼロ件にします。ただし、監査可能性を保つため、提示形式では「重複を確認」の行を残します。「重複を確認」の行には、根拠として既存のスキル名と該当セクション名（または行番号）を記載します。
   • 判断不能：エージェントが重複かどうかを判断できない → 該当結果をユーザーに示し、判断を仰ぎます。

5. 書き出す：選択した形式に応じて、以下のテンプレートに従い成果物を作成します。

6. 確認する：差分をユーザーに提示し、承認を得ます。却下された場合は、スキルではなくセッションメモとして残します。

分類の判断基準

digraph classify {
    "Mechanically detectable?" [shape=diamond];
    "Short instruction to apply every time?" [shape=diamond];
    "Involves multi-step procedure or judgment?" [shape=diamond];
    "ast-grep rule / lint" [shape=box];
    "CLAUDE.md rule" [shape=box];
    "skill" [shape=box];
    "keep as note" [shape=box];

    "Mechanically detectable?" -> "ast-grep rule / lint" [label="yes"];
    "Mechanically detectable?" -> "Short instruction to apply every time?" [label="no"];
    "Short instruction to apply every time?" -> "CLAUDE.md rule" [label="yes"];
    "Short instruction to apply every time?" -> "Involves multi-step procedure or judgment?" [label="no"];
    "Involves multi-step procedure or judgment?" -> "skill" [label="yes"];
    "Involves multi-step procedure or judgment?" -> "keep as note" [label="no"];
}

判断基準	出力先	例
コード／設定の構文レベルで検出可能	ast-grep ルール、または既存のリンター設定	「Array.from(set).length を使わず、set.size を使う」
短く、常に適用され、判断を必要としない	CLAUDE.md（ユーザー共通／プロジェクト）	「pnpm v10 以降を使う」
手順、状況に応じた判断、またはテンプレートが必要	新しいスキル、または既存のスキルへの追記	「MoonBit 用 C バインディングの作成手順」
プロジェクト固有で一度限り	採用しない（コミットメッセージ／PR の説明に残す）	—

原則：ast-grep を優先：静的に検出できるものは、プロンプトやドキュメントに書かず、必ず ast-grep ルールにします（ユーザー共通ルールとして設定します）。

CLAUDE.md の書き込み先：

• 言語やツールをまたぐ一般的なルール → ~/.claude/CLAUDE.md
• 特定のリポジトリに限定されるルール → そのリポジトリの CLAUDE.md

出力テンプレート

ast-grep ルール

ast-grep-practice スキルを参照してください。rules/ ディレクトリに YAML を追加し、必ず rule-tests/ に有効なケースと無効なケースのペアを記述してください。

CLAUDE.md に追記

# <append to existing section>
- <one imperative sentence> (reason: <short rationale>)

理由を必ず括弧内に記載してください（将来の自分がエッジケースを判断できるようにするためです）。

新しいスキル

writing-skills（superpowers）の最小テンプレートに従ってください：

---
name: <kebab-case>
description: Use when <specific situation> / <symptom>
---

# <Title>

## Purpose
## When to use
## Workflow
## Pitfalls

具体例

例 1：ast-grep ルールとして定式化する（機械的に検出可能）

• 最初の試み：TypeScript で、Array.from(set).length を使って Set のサイズを取得しましたが、レビューで非効率だと指摘されました。
• 最終的な解決策：set.size を使います。
• 気づき：Set / Map のサイズには、.size プロパティを使います。Array.from(...).length は構文レベルで検出できます。

-> rules/no-array-from-size.yml を追加：

id: no-array-from-size
language: TypeScript
severity: warning
rule:
  pattern: Array.from($COLL).length
message: Set/Map のサイズは .size プロパティを使う。

例 2：CLAUDE.md のルールとして定式化する（短く、常時有効なルール）

• 最初の試み：pnpm install を実行したところ、ロックファイルの形式の差分により CI が失敗しました。
• 最終的な解決策：pnpm のバージョンを v10 系に合わせました。
• 気づき：pnpm はバージョンによってロックファイルを変更します。常に v10 以降を使ってください。

-> ~/.claude/CLAUDE.md の「ツール」セクションに追記：

- pnpm は v10 以上を使う（理由: lockfile 形式が v9 以前と非互換で CI 差分が出る）

例 3：新しいスキルとして定式化する（手順と判断が必要）

• 最初の試み：MoonBit から C ライブラリを呼び出すために複数の方法を試しましたが、FFI 宣言とスタブの配置で行き詰まりました。
• 最終的な解決策：extern "c" 宣言、moonbit.h を使うスタブ、moon.pkg.json の native-stub / link.native 設定を組み合わせます。
• 気づき：これは単一の手順には収まりません。宣言、スタブ、ビルド設定という 3 つの層をまとめて理解する必要があります。

-> 手順とテンプレートを新しいスキル moonbit-c-binding として切り出します（これはすでに存在するため、重複チェックを行い「既存に追記」を選ぶケースです）。

危険信号（合理化に注意）

次のような考えが浮かんだら、いったん立ち止まってください。

浮かんでくる合理化	実際のところ
「プロジェクト固有だけど、念のためスキルにしておこう」	スキルが肥大化し、検索性が低下します。コミットメッセージや PR で十分です。
「承認を省いて先に書いてしまおう。あとで見せればいい」	CLAUDE.md / スキルを独断で変更すると、今後の挙動が予測不能になります。必ず「提案 -> 承認 -> 書き出し」の順にしてください。
「ast-grep でも書けそうだけど、自然言語のルールとして書くほうが早い」	静的に検出できる内容を文章で書いても、エージェントは従いません。ast-grep を優先してください。
「気づきは薄いけど、面目を保つために何か書かないと」	提案が 0 件でも正しい答えです。振り返りが空でも問題ありません。
「重複チェックは面倒だから省いて、重複はあとで消そう」	重複したルールが残ると、挙動が分かれます。重複チェックは必須です。
「失敗した側は省いて、最終的な解決策だけを書こう」	失敗の内容を書かないと、将来の自分が同じ落とし穴にはまります。

ユーザーへの提示形式

タスクの最後に、以下の形式で棚卸し結果を提示してください。教訓は複数あってもかまいません。判断の記録を残すため、重複と不採用も明示してください。

## Retrospective

### Lesson 1: <short label>
- First failure: <1 line>
- Final solution: <1 line>
- Insight: <1 line>

### Lesson 2: <short label>      # omit this block if there is only 1 lesson
- First failure: <1 line>
- Final solution: <1 line>
- Insight: <1 line>

## Proposals

Adoption candidates:
- [lint] <rule name>: <1 line> (artifact: <path>, from lesson N)
- [skill append] <existing skill name>: <1 line> (from lesson N)
- [skill new] <skill name>: <1 line> (from lesson N)
- [rule] CLAUDE.md (global/project): <1 line> (from lesson N)

Duplicate detected (no proposal needed):
- <lesson N>: fully covered by <section name or line number> of existing <skill/rule name> -> no addition

Not adopted:
- <lesson N>: <one-line reason for non-adoption> (e.g. project-specific / hard to express in lint across files / absorbed by another lesson)

Please indicate which to adopt by number or item name. Zero proposals is also a valid conclusion.

形式のルール：

• 教訓が 1 件だけの場合は、### Lesson N の見出しを省略し、振り返りブロックを 1 つだけ記載してください
• 「採用候補」「重複を検出」「不採用」のいずれかが空の場合、そのセクション全体を省略してください（「なし」とは書かないでください）
• 提案の各行は必ず「from lesson N」で終えてください（複数の教訓にまたがる場合は、「from lessons 1, 3」のように列挙できます）
• 「採用候補」が空で「重複を検出」だけが残る場合、締めの文を Please indicate which to adopt から No adoption candidates. Please review for the record. に置き換えてください
• ユーザーが採用するよう指示した項目だけを書き出してください。黙って書き出してはいけません。

提示例：すべての教訓がすでに反映済み（重複を検出したもののみ）

## Retrospective

### Lesson 1: <label>
- First failure: ...
- Final solution: ...
- Insight: ...

## Proposals

Duplicate detected (no proposal needed):
- Lesson 1: fully covered by `<section name>` of existing skill `<skill name>` -> no addition

No adoption candidates. Please review for the record.

表示例：部分的な重複（既存の内容に追加＋重複を検出）

## Proposals

Adoption candidates:
- [skill append] <existing skill name>: <1 line for the new portion> (from lesson 1, complements existing section `<section name>`)

Duplicate detected (no proposal needed):
- Lesson 1 (version value portion): already covered by the tools section in `~/.claude/CLAUDE.md` -> no append needed

よくある失敗

• 粒度が細かすぎる：一度限りの詳細（特定の関数名、特定のバージョン）をルール化している場合は、「何を確認するか」のレベルまで抽象化します
• プロンプトのように書きがち：静的に検出できるルールを自然言語で CLAUDE.md に書いている場合は、ast-grep のルールに移します
• 理由を書かない：ルールの根拠が残されていないため、将来の自分が従う理由を判断できません。必ず Why: を添えます
• 独断で書き出す：ユーザーの承認を得ずに CLAUDE.md やスキルを更新しています。必ず「提案 → 承認 → 書き出し」の順に進めます
• 失敗を言語化しない：「最終的な解決策は X」とだけ書き、最初の手順が行き詰まった理由を残していません。失敗した側の説明がないと、将来の自分も同じ落とし穴にはまります

関連スキル

• superpowers:writing-skills — 新しいスキルを書くためのテンプレートと TDD の流れ
• ast-grep-practice — リントルールとしてルール化する際の記述方法とテスト方法
• update-config — settings.json / permissions の変更が必要な場合