knowledge-capture

ナレッジの記録

概要

実質的なやり取りには、必ず何らかの兆候があります。デバッグセッションでは、隠れたコードベースの慣習が明らかになります。ユーザーからの訂正は、好みを示します。計画の失敗は、盲点を明らかにします。こうした観察結果を記録することは負担ではなく、能力に対する複利のような投資です。

基本原則： 難しい問題を解決しても、発見したことを記録しなければ、次回はまたゼロから解決することになります。

例外なし。回避策なし。近道なし。

最優先の指令

EXTRACT INSIGHT FROM EVERY MEANINGFUL INTERACTION

振り返りをせずに終わるやり取りは、投資の無駄です。コンテキストを持ち、答えを見つけ、うまくいったことを確認したのに、そのすべてを捨ててしまったのです。

言い訳は無用です：

• 作業が「日常的」だと感じたからといって、記録を省略しないでください
• 「まもなくコンテキストを切り替える」からといって、記録を省略しないでください
• 教訓が「自明」だと思えるからといって、記録を省略しないでください
• すべてのコンテキストがあると自明に思えることも、ゼロから始めると見えなくなります

振り返り、要点をまとめ、残してください。それだけです。

使用するタイミング

次の場合は必須です：

• 複雑な機能を実装した後（どのパターンが効果的でしたか？）
• 手ごわい不具合を解決した後（根本原因を示す特徴は何でしたか？）
• 問題を明らかにするレビューのフィードバックを受けた後（次回は何を変えるべきですか？）
• ユーザーから訂正された後（新たな好みが判明しました）
• 計画を大幅に修正した後（何を見誤っていましたか？）
• 試行錯誤を通じてコードベースの慣習を発見した後（次のセッションに同じ道のりをたどらせないようにしましょう）

例外（人間に確認してください）：

• 1行で済む些細な修正
• 新しい情報が得られなかったやり取り
• ユーザーが明示的に記録を望まない場合

「記録することは何もない」と思いそうになったら、立ち止まってください。それは合理化です。

記録の手順

AFTER completing any meaningful task:

1. REFLECT: What succeeded? What failed? What was unexpected?
2. DISTILL: What generalizable pattern or insight emerges?
3. DEDUPLICATE: Is this already recorded? Does it contradict something stored?
4. PERSIST: Write it to the appropriate memory file with date and context
5. PRUNE: Remove any prior entries that newer evidence invalidates

Omit any step = insight permanently lost

記録のライフサイクル

digraph capture_lifecycle {
    rankdir=TB;
    node [shape=box style=filled];

    task [label="Meaningful Task\nCompleted" fillcolor=lightyellow shape=doublecircle];

    reflect [label="REFLECT\nWhat occurred?\nWhat surprised me?" fillcolor="#ccccff"];
    distill [label="DISTILL\nAbstract the insight\nfrom the specifics" fillcolor="#ccccff"];
    exists [label="Already\nrecorded?" shape=diamond fillcolor="#fff3e0"];
    conflicts [label="Contradicts\nan existing entry?" shape=diamond fillcolor="#fff3e0"];
    persist [label="PERSIST\nSave to memory\nwith date + context" fillcolor="#ccffcc"];
    prune [label="PRUNE\nRemove outdated\nentry" fillcolor="#ffcccc"];
    cluster [label="CLUSTER\n3+ related insights?\nForm a conviction" fillcolor="#ccffcc"];
    promote [label="PROMOTE\nHigh-confidence conviction\n-> CLAUDE.md rule" fillcolor="#e8f5e9"];
    skip [label="Skip\n(already known)" fillcolor="#eeeeee"];

    task -> reflect;
    reflect -> distill;
    distill -> exists;
    exists -> skip [label="yes, identical"];
    exists -> conflicts [label="no"];
    conflicts -> prune [label="yes"];
    prune -> persist;
    conflicts -> persist [label="no"];
    persist -> cluster;
    cluster -> promote [label="3+ confirmations"];
    cluster -> task [label="await further\nevidence" style=dashed];
}

洞察の分類

効果的なパターン

きれいな結果につながったコードのアプローチ、デバッグの手法、アーキテクチャの選択です。これらは強化すべき肯定的な兆候です。

Sample entry:
  Date: 2025-04-10
  Context: Built retry logic for third-party webhook delivery
  Insight: Exponential backoff with random jitter eliminated thundering-herd spikes
  Confidence: medium (validated once)

失敗とその解決策

何がうまくいかなかったのか、どう解決したのか、再発をどう防ぐのか。失敗からは、最も価値の高い教訓が得られます。

Sample entry:
  Date: 2025-04-12
  Context: Logging middleware silently swallowed request bodies after refactor
  Insight: Any change to middleware ordering demands a full integration test pass -- blast radius is total
  Confidence: high (validated by production incident)

ユーザーの好み

ユーザーが採用している文体、ツールの好み、慣習です。訂正や明示的な発言を通じて把握します。

Sample entry:
  Date: 2025-04-13
  Context: User corrected my naming approach
  Insight: User requires camelCase for variables, PascalCase for types, and no abbreviations anywhere
  Confidence: high (direct correction)

プロジェクト固有の知識

アーキテクチャの詳細、隠れた落とし穴、重要なファイル、文書化されていない暗黙知です。

Sample entry:
  Date: 2025-04-14
  Context: Spent 15 minutes searching for runtime config
  Insight: All runtime configuration lives in src/config/runtime.ts, not in .env files
  Confidence: high (verified in source)

保存方法

Claude Code のメモリシステムを活用します：~/.claude/projects/[project]/memory/

メモリファイルの分類

ファイル	目的	記録例
effective-patterns.md	明確な成果につながったコードのアプローチと戦略	「API の境界で Zod スキーマを使うと、不正なデータが伝播する前に検出できる」
failure-analysis.md	根本原因のパターンと診断手法	「ローカルでは通るのに CI で失敗するテストは、たいていタイムゾーンまたはロケールの前提に起因する」
project-map.md	アーキテクチャ、重要なファイル、コードベースの慣習	「データベースのマイグレーションは db/migrations/ にあり、pnpm db:migrate で実行する」
human-preferences.md	ユーザーが求める文体、ツールの好み、慣習	「ユーザーは明示的なエラー型を求め、文字列ベースのエラーを認めない」

記録の構成

記録するすべての洞察には、次の内容を含める必要があります：

### [Concise title]
- **Date:** YYYY-MM-DD
- **Context:** What was happening when this was discovered
- **Insight:** The generalized takeaway
- **Confidence:** low / medium / high
- **Confirmations:** Number of times this has been validated

重複排除の手順

新しい記録を書く前に、対象のメモリファイルを確認してください。洞察がすでに存在する場合：

• 同じ洞察で確信度も同じ場合 -> 完全にスキップする
• 同じ洞察で確信度が高まった場合 -> 確信度を更新し、確認回数を増やす
• 矛盾する洞察の場合 -> 古い記録を置き換え、矛盾があったことを記す

成熟のサイクル

個々の洞察は、集約されて確信へと変わると、大きな力を発揮します。

洞察から確信へ

Insight 1: "This project validates forms with zod" (medium confidence)
Insight 2: "API route handlers also validate payloads with zod" (medium confidence)
Insight 3: "User corrected me for using manual validation instead of zod" (high confidence)

    Converge into conviction

Conviction: "This project ALWAYS validates at every boundary using zod"
Confidence: high (confirmed across 3 interactions)

確信からルールへ

確信の信頼度が高くなった場合（3 回以上のやり取りで確認済み）、プロジェクトの CLAUDE.md ルールへの昇格候補になります。

Conviction: "This project always validates with zod"
  -> Confirmed 3+ times
  -> Propose to user: "I have observed that this project consistently
    uses zod for validation. Should I codify this as a project rule in CLAUDE.md?"
  -> User approves -> add to CLAUDE.md

自動で昇格させてはいけません。 CLAUDE.md に項目を追加する前に、必ずユーザーの同意を得てください。恒久的なルールに関する最終的な決定権は人間にあります。

セッション開始時のレビュー

プロジェクトで新しいセッションを開始するとき：

1. プロジェクトのすべてのメモリファイルを読みます
2. まだ統合されていない、関連する知見のまとまりを特定します
3. 古くなっている可能性のある項目（記録日が古い、信頼度が低い、再確認されていない）にフラグを立てます
4. 昇格の準備ができた確信を提示します

信頼度の段階

段階	意味	根拠	対応
低	暫定的な兆候	単発で、未確認	記録し、確認できるか注視する
中	可能性の高いパターン	2 回確認済み、または強い指標が 1 つある	記録し、関連する場合に適用する
高	確立された事実	3 回以上確認済み、またはユーザーが明示的に宣言	記録し、一貫して適用し、昇格を検討する

認知の落とし穴

合理化	実際
「ここには記録することが何もない」	どのタスクからも兆候が得られます。注意深く確認できていないだけです。
「自然に思い出せる」	思い出せません。次のセッションは白紙の状態から始まります。メモリファイルが継続性を保ちます。
「記録するほどのことではない」	小さな知見も積み重なります。小さな観察が 3 つ集まれば、強力な確信になります。
「自明なことだ」	十分な文脈がある今のあなたにとっては自明です。来週、前提知識のない状態で始めるときには自明ではありません。
「記録には時間がかかりすぎる」	項目の記録には 30 秒。同じ知見を再発見するには 30 分かかります。
「ユーザーは求めていない」	ユーザーが求めているのは品質です。経験から学ぶことこそ、品質を長期的に向上させる方法です。
「メモリファイルが煩雑になってきた」	それは整理の問題であり、記録の問題ではありません。整理を増やし、記録をやめてはいけません。
「これはこのプロジェクトだけに当てはまる」	プロジェクト固有の知識は最も価値があります。だからこそ、プロジェクトごとに保存するのです。

ガードレール

禁止事項：

• 難しいデバッグセッションの後に振り返りを省略する
• 日付と文脈を記載せずに項目を保存する（日付のない知見は劣化します）
• ユーザーの承認なしに CLAUDE.md にルールを自動追加する
• 重複を排除せずに同じ知見を二重に記録する
• 新しい証拠と矛盾する項目を保持する
• 一般化できるパターンではなく、実装の細部を記録する

必須事項：

• 重要な作業を完了した後は必ず振り返る
• 保存する前にメモリを確認する（重複を排除する）
• すべての項目に信頼度を付ける
• 確信を CLAUDE.md のルールに昇格させる前に、ユーザーの同意を得る
• 新しい証拠によって無効になった項目を整理する
• 項目を時系列ではなくトピック別に整理する

統合

このスキルは他のスキルに情報を提供します：

• godmode:fault-diagnosis -- 過去の失敗分析が、現在のトラブルシューティングに役立ちます
• godmode:pattern-matching -- 記録された規約が、コードの一貫性を高めます
• godmode:test-first -- 過去のテスト失敗が、今後のテスト戦略に役立ちます
• godmode:task-planning -- 過去の計画の失敗により、誤った判断の繰り返しを防ぎます
• godmode:quality-enforcement -- 記録された品質パターンが、品質の基準を引き上げます

このスキルには他のスキルから情報が提供されます：

• godmode:review-response -- レビューのフィードバックが、記録される知見になります
• godmode:completion-gate -- 検証の失敗が、記録される教訓になります
• godmode:comprehension-check -- ウォークスルーで得た知見が、保存される観察事項になります
• godmode:task-runner -- 計画の実行を通じて、何がうまくいき、何がうまくいかないかが明らかになります

好循環：

Work -> Capture -> Persist -> Apply -> Work better -> Capture more