instinct-system

Instinct System

1つの学習システムに、3つの階層があります。作業中にClaudeが受け取るあらゆるシグナル――観察されたパターン、ユーザーによる修正、意外な発見――は、必ずいずれか1つの保存先に振り分けられます。

基本原則

1. 3つの階層と、1つの振り分け判断 — Instincts は未確認の仮説です（.claude/instincts.md）。Corrections はユーザーが確認したルールです（MEMORY.md）。Discoveries は物事の仕組みを説明する知見です（.claude/learning-log.md）。ルールは振る舞いを規定し、知見は振る舞いを説明します。Instinctsはルールになる前の段階です。階層を混在させてはいけません。仮説をMEMORY.mdに入れると永続的な知識が汚染され、確認済みのルールをinstinctのままにしておくと忘れられてしまいます。

2. Instinctsはルールではなく仮説です — Instinctは、1回の観察から得た推測として始まり、確認されるまでは効力を持ちません。「あるハンドラーがsealedを使っている」は確信度0.3のinstinctです。「12個すべてのハンドラーがsealedを使っている」は確信度0.9のルールです。確信度（0.3～0.9）によって行動が変わります。0.3では記録し、0.5では言及し、0.7では従い、0.9では昇格させます。

3. ユーザーによる修正は、確信度が最大の確認済みinstinctです — ユーザーから修正を受けたら、確認サイクルを完全に省略します。教訓を一般化し、「なぜそうするのか」とともに、すぐにMEMORY.mdへ記録し、記録した内容を確認します。修正への対応にかかる時間は、ユーザーにとって今日の30秒ですが、今後のすべてのセッションで何時間もの節約になります。1つでも失うのは、このシステムで最もコストの高い失敗です。

4. プロジェクト単位で管理し、グローバルにはしません — あるコードベースで正しいことが、別のコードベースでは誤りかもしれません。Instinctsはプロジェクトごとに保存します。プロジェクト間で移す場合は、確信度を下げたうえでエクスポート／インポートを行い、確信度を最大のまま移すことはありません。

5. セッション開始時に確認し、定期的に整理します — コードを書く前にMEMORY.mdを読み、確信度0.7以上のinstinctを読み込みます。作業領域に関する最近のログも確認します。記録しても見直さない知識は、労力の無駄です。3つの保存先が膨らんだら、すべてを監査します。古くなったinstinct、重複するルール、未確認のログがあると、本来の目的を果たせません。

パターン

階層への振り分け

シグナル	保存先	有効期間
観察されたが、まだ確認されていないパターン（「いつもそうしているようだ」）	.claude/instincts.md、確信度0.3	昇格または破棄されるまで
ユーザーによる修正（「いいえ、Xを使って」「もうそれはしないで」「これを覚えておいて」）	すぐにMEMORY.mdへ一般化して記録	誤りと証明されるまで永続
確信度が0.9に達したinstinct	MEMORY.mdへ昇格し、instinctsから削除	永続
自明ではない発見（バグの根本原因、注意点、回避策、パフォーマンスに関する知見）	.claude/learning-log.md	3～6か月後にアーカイブまたは昇格
同じ注意点が3回以上記録された	予防ルールとしてMEMORY.mdへ昇格	永続
セッションの状態（完了／保留）	終了時の引き継ぎで記録。このシステムの対象外	次のセッションまで

Instinctのライフサイクル（観察・仮説・確認）

1. OBSERVE     — "This handler is internal sealed class. Convention?"
2. HYPOTHESIZE — Write to .claude/instincts.md at confidence 0.3:
                 - Use `sealed` on handler classes | confidence: 0.3 | seen: 1 | last: 2026-06-12
3. SEEK        — Actively check 2-3 related files (find_symbol, get_public_api).
                 Passive observation is not enough.
4. ADJUST      — Confirmed: raise per the adjustment track.
                 Contradicted: halve confidence, note the exception.
                 Mixed: hold steady, note the split.
5. PROMOTE     — At 0.9, present evidence and offer promotion to MEMORY.md.

Instinctの保存形式

.claude/instincts.mdでは、構造化メタデータを付けてカテゴリ別にまとめます。

# Project Instincts

## Code Style [0.7]
- Use `sealed` on all handler classes | confidence: 0.8 | seen: 5 | last: 2026-06-12
- Prefix private fields with underscore | confidence: 0.5 | seen: 2 | last: 2026-06-10

## Architecture [0.7]
- Feature folders use singular names | confidence: 0.7 | seen: 4 | last: 2026-06-12

カテゴリーヘッダーの[0.7]は平均確信度を示します。標準カテゴリは、コードスタイル、アーキテクチャ、命名、テスト、データアクセス、API設計、設定、パフォーマンス、ツールです。

確信度の調整ルール

場当たり的にスコアを付けてはいけません。次の手順に正確に従ってください。

CONFIRMATION:  1st observation → 0.3 | 2nd → 0.5 | 3rd → 0.7 | 4th → 0.8
               5th+ with zero contradictions → 0.9 (promotion candidate)

CONTRADICTION: Any contradiction → halve current confidence (0.7 → 0.35)
               Two in a row → 0.1 (effectively dead)

USER OVERRIDE: Explicit confirm → 0.8 | Explicit correct → 0.0 (remove,
               capture in MEMORY.md instead) | "Sometimes" → cap at 0.5

STALENESS:     No observations for 10+ sessions → flag for review
               Contradicted, unreconfirmed for 5 sessions → remove

確信度に応じたInstinctの活用

0.0–0.2 → IGNORE  — insufficient evidence, do not mention
0.3–0.4 → NOTE    — record internally, do not apply
0.5–0.6 → MENTION — "This project may use [pattern]. Follow it?"
0.7–0.8 → FOLLOW  — apply by default, mention on first use
0.9     → PROMOTE — offer to add to MEMORY.md as a permanent rule

確信度が0.7未満のinstinctを、黙って適用してはいけません。

修正の記録フロー（第2階層）

ユーザーが出力を修正した場合（「いいえ、代わりにXを使って」「そのやり方はしません」「Xを必ず／絶対にしないで」「これを覚えておいて」など）：

1. DETECT      — Recognize the correction signal.
2. ACKNOWLEDGE — "Got it — HybridCache instead of IMemoryCache."
3. GENERALIZE  — Specific: "Don't use IMemoryCache in the Orders endpoint"
                 General:  "Always use HybridCache over IMemoryCache —
                            stampede protection + L1/L2 out of the box."
                 Ask: is this specific to this file? This layer? What's the
                 underlying principle? Store the broadest correct statement.
4. CHECK       — Scan MEMORY.md for overlap. Update an existing rule rather
                 than adding a near-duplicate.
5. STORE       — Write under the right category, one line, rationale after
                 the dash. If a matching instinct exists, remove it — it
                 just graduated.
6. CONFIRM     — "Added to Memory > Data Access: HybridCache over IMemoryCache."

MEMORY.mdの形式は、instinctsと同じカテゴリを使い、1行につき実行可能なルールを1つ記述します。

## Data Access
- Always use HybridCache over IMemoryCache — stampede protection + L1/L2
- Never use repository pattern over EF Core — use DbContext directly

発見の記録（第3階層）

自発的に得られた発見は、発生した時点ですぐに.claude/learning-log.mdへ記録します。その場で書いた2行の記録は、後で再構成した段落よりも有用です。記録の形式：

## 2026-06-12 | Gotcha | MassTransit Consumer Registration Order Matters
Multiple consumers for one message type run in registration order; if the
first throws, the rest are skipped. Caused missed audit events.
**Files:** `src/Shared/Extensions/MassTransitConfig.cs:15-30`
**Resolution:** Independent consumer endpoints or the retry filter.

次のトリガーのいずれかに該当した場合に限り、記録します。

Bug Root Cause        — the cause was NOT where the error appeared
Architecture Decision — discovered WHY something is built a certain way
Gotcha                — framework/library behaved surprisingly
Performance Discovery — unexpected perf behavior, with the measurement
Pattern Found         — reusable codebase pattern worth remembering
External Service      — third-party API behaves differently than documented

この6つのトリガー名は、カテゴリ名としても使います。記録ではそのまま使用してください。意外なことが何もない通常の変更は記録しません。

セッション開始時の読み込み

1. Read MEMORY.md — apply rules proactively, don't wait to be reminded
2. Read .claude/instincts.md — load 0.7+ as defaults, note 0.5–0.6
3. Scan recent learning-log entries for the area you're working in
4. Flag stale instincts (10+ sessions without observation) for review

モード

本能ストアに対する3つの操作です。名前またはトリガーフレーズで呼び出します。

ステータス（「本能を表示」「何を学習しましたか」「本能を一覧表示」）

1. .claude/instincts.mdを読み込み、各項目のメタデータを解析します。
2. 信頼度の降順に並べ、カテゴリごとにまとめて、次の表として表示します。 本能 | 信頼度 | カテゴリ | ステータス（新規／安定／強化／減衰中／昇格候補）。
3. 健全性を要約します。合計件数、平均信頼度、最近強化された項目と減衰中の項目、矛盾する本能があるかどうかを含めます。

エクスポート（「本能をエクスポート」「本能を共有」）

1. .claude/instincts.mdを読み込み、信頼度が0.7を超える項目に絞ります（しきい値は設定可能です）。
2. パターン自体を維持しながら、プロジェクト固有のコンテキスト（ファイルパス、行番号）を取り除きます。
3. 移植可能なメタデータを付けて、.claude/instincts-export.mdに書き込みます。
4. エクスポートした項目とスキップした項目（しきい値未満）を、出力パスとともに報告します。

インポート（「本能をインポート」「本能を読み込む」）

1. エクスポートファイル（ユーザーが指定したパス、または.claude/instincts-export.md）と、現在の.claude/instincts.mdを読み込みます。
2. インポートした本能を1つずつ統合します。
   • ローカルに一致する項目がない場合 — 信頼度を0.2下げて追加します（0.9 → 0.7）。0.7を超える信頼度でインポートしてはいけません。source: imported from [project]と記録します。
   • 一致する本能がある場合 — 信頼度の高い方を維持し、強化済みとして記録します。
   • 矛盾する本能がある場合 — 解決のため、両方をユーザーに提示します。ローカルの根拠で自動的に上書きしてはいけません。
3. 統合した結果を書き込み、インポート、統合、競合について報告します。インポートしたパターンは、すべてのプロジェクトでローカルに確認する必要があります。

アンチパターン

性急すぎるパターン認識

# BAD — first observation treated as a rule
*Reads one handler* "This project always uses internal sealed class."
*Generates 5 handlers that contradict 8 of 9 existing ones*

# GOOD — hypothesis at 0.3, then active confirmation
"Noticed internal sealed in CreateOrderHandler. Instinct at 0.3.
 Checking 3 more handlers..." *All public* → "Disconfirmed. Discarding."

修正しても記録しない

# BAD — correction applied, lesson lost
User: "No, we use HybridCache here"
Claude: "Fixed." *Next session: same mistake*

# GOOD — fix AND capture
Claude: "Fixed. Added to Memory > Data Access:
         Always use HybridCache over IMemoryCache."

すべてを記録する

# BAD — noise entry
## 2026-06-12 | Pattern Found | Used Primary Constructors

# GOOD — only the non-obvious earns an entry
## 2026-06-12 | Gotcha | Primary Constructor Params Captured as Fields
Declaring an explicit field with the same name warns but compiles —
and the two can silently diverge.

書き込み専用ストア

# BAD — 40 instincts at 0.3 from 3 months ago; MEMORY.md at 200 lines
  with duplicates; 500-line log nobody reads
# GOOD — periodic audit: remove instincts below 0.2 or stale 10+
  sessions; merge/prune MEMORY.md past 50 rules; every ~20 log entries,
  promote recurring findings and archive the stale. Keep instincts
  under 50 active entries.

判断ガイド

シナリオ	対応
パターンを初めて確認した	信頼度0.3の本能として記録し、関連ファイルを2～3個確認する
パターンを3回以上確認し、矛盾がない	信頼度を0.7に上げ、デフォルトで従う
パターンと矛盾する事例があった	信頼度を半分にし、例外を記録する
ユーザーが「いつもXをします」と言った	信頼度0.8の本能として記録する（ユーザーによる確認）
ユーザーがコードを修正した	一般化して、ただちにMEMORY.mdに記録し、一致する本能があれば削除する
ユーザーが「これを覚えておいて」／「必ず／絶対に～しないで」と言った	内容どおりに一般化してMEMORY.mdに記録する
同じ修正を2回受けた	優先度を高くする — ルールが記録されていないか、見直されていない
一度きりのタスクに関する修正	保存しない — 再利用可能なパターンのみを保存する
ユーザーがルールを忘れるよう求めた	ただちにMEMORY.mdから削除する
すぐには分かりにくいバグ、落とし穴、回避策、性能上の予想外の問題	カテゴリとファイルを付けてlearning-logに記録する
同じ落とし穴が3回以上記録された	予防ルールとしてMEMORY.mdに昇格させる
本能の信頼度が0.9	根拠を提示し、MEMORY.mdへの昇格を提案する
ユーザーが一部のみ確認した（「コマンドに限る」など）	適用範囲を狭め、信頼度を0.5に戻し、再確認する
別のプロジェクトとパターンを共有する	信頼度0.7以上でエクスポートし、信頼度を0.2下げてインポートする
インポート時に競合が発生した	両方をユーザーに提示する。自動的に上書きしてはいけない
いずれかのストアが肥大化した（項目／ルールが50件以上）	見直しを行う。不要な項目を削除し、重複を統合し、成熟した項目を昇格させる
セッションを開始する	MEMORY.md、本能（信頼度0.7以上）、最近のログ項目を読み込む

関連項目

• convention-learner — コードベースの規約をまとめて検出し、その検出結果を本能として取り込みます
• wrap-up — セッション終了時の手順です。セッションでの学びをこのシステムの適切な階層に振り分けます