vima-tech/Innate

レイヤーの役割

Innateは補助的です — 決してメインタスクをブロックしてはいけません。すべてのInnate操作はベストエフォートです。ツールエラーが発生した場合: 修正した呼び出しで1回再試行し、それでも失敗したら諦めて続行します。

いつ呼び出すか

タスクの開始時にのみ、以下の場合に呼び出します:

• 既知の繰り返しパターンがあるドメイン（例：特定のコードベース、フレームワーク、プロトコル）
• 以前に遭遇した可能性のある問題のデバッグや修正
• アーキテクチャ/設計 — 過去の判断が重要

呼び出しをスキップする場合: 簡単なワンライナー、明確な答えがある質問、ユーザーが事前知識のないまったく新しい領域と定義したタスク。

クエリの作成

正規化された意図（canonical intent） を使用し、ユーザーの言葉をそのまま使わないでください。セッション間でクエリを一貫させてください — 同じクラスの問題には常に同じ正規化形式を使用します。なぜなら、Innateはクエリパターンごとにコンテキスト統計を蓄積するからです。

ユーザーの発言	良いクエリ	悪いクエリ
"なぜ起動時にクラッシュするのか？"	startup crash sqlite init	なぜ起動時にクラッシュするのか
"認証フローをリファクタリングして"	auth flow session token handling	認証フローをリファクタリング
"APIにレート制限を追加して"	rate limiting middleware pattern	レート制限を追加
"不安定なテストをデバッグして"	flaky test race condition timing	不安定なテストをデバッグ

呼び出し: innate_recall(query=<正規化された意図>, budget=4000, source="mcp")

呼び出されたチャンクを作業コンテキストに注入します。関連する事前知識が見つかった場合（見つからなかった場合も）、その旨をユーザーに1文で伝えてください。

自動呼び出しフック

Innateがフックとともにインストールされている場合、UserPromptSubmitフックが自動的に<innate-recall>ブロックを会話に注入することがあります — これはプロンプトに対して関連性ゲートを通過した呼び出しを既に実行しており、trace_idを持っています。このブロックを確認した場合:

• そのtrace_idを後続のinnate_recordで再利用してください — 同じタスクに対して再度innate_recallを呼び出さないでください（重複した孤立トレースが作成されます）。
• そのチャンクを、自分で呼び出した場合とまったく同じように扱います: 役立つものを適用し、その後チャンクごとの評決（後述）で閉じます。
• ブロックがなく、タスクがそれを正当化する場合は、上記の手順で手動で呼び出します。

フックは関連性ゲートを通過するため、その沈黙は「高いスコアのものは何もなかった」という意味であり、「知識が存在しない」という意味ではありません。ゲートが見逃した可能性のある関連する事前知識を疑う場合は、手動で呼び出してください。

いつ記録するか

実際の成果（成功または失敗）を生み出したタスクの後に記録します。以下の場合は記録をスキップします:

• 決定的な結果のない探索的なやり取り
• ユーザーが完了前に中断したタスク
• 純粋な情報検索（ユーザーが質問しただけで、何も構築または変更されなかった）

結果ルール

状況	outcome
タスク完了、ユーザーが結果を確認または承認	ok
タスク失敗、アプローチが間違っていた、ユーザーが軌道修正する必要があった	fail
セッションが中断され、結果が不明	unknown

チャンクごとの評決 — 必須

これはInnateにおける最も重要な契約です。信頼性ランキングは、ここで報告する内容の精度にのみ依存します。チャンクを表面化したすべての呼び出し（手動またはフック注入）は、チャンクごとの評決で閉じる必要があります。 目の前に提示された各チャンクは、正確に3つのバケットのいずれかに分類されます:

評決	意味	格納先
使用して役立った	適用して時間を節約/ミスを防いだ	used=[id] かつ feedback_up=[id]
使用して誤った	適用したが、間違っていたり誤った方向に導いた	used=[id] かつ feedback_down=[id]
未使用	呼び出されたが適用しなかった	完全に省略（usedにリストしない）

シグナルをクリーンに保つルール:

• usedには、実際に推論や出力で参照したチャンクのみをリストします — 通常は1〜3個です。単に呼び出されただけのチャンクで埋めてはいけません。
• 何も適用しなかった場合、それも現実の貴重なシグナルです: used=[]を明示的に設定します（既知のなし）。記録をスキップしないでください — 沈黙は「何も役立たなかった」と同じではありません。
• usedとしたチャンクには、ほとんどの場合、upまたはdownシグナルも付けるべきです。評決のない使用済みチャンクは、与えられる最も強力なランキング入力を無駄にします。
• feedback_downについては正直になってください。誤ったチャンクをダウンマークするとレビューされアーカイブされます。マークされていない誤ったチャンクは、将来のセッションを誤解させ続けます。

出力サマリー — 構造化フォーマット

将来のエージェントが冷えた状態で行動できる自己完結型の1文を書いてください。次の構造を使用します:

<行われたこと/学んだこと> — <主要な制約/方法> — <これが適用される時>

良い例:

• Fixed SQLite WAL mode detection by checking PRAGMA journal_mode response rather than assuming WAL — triggers on any new db connection in multi-process setups
• Resolved flaky auth test by injecting a clock mock — real system time causes race in token expiry check
• Rate limiting must be applied before auth middleware, not after — otherwise unauthenticated requests bypass the limiter

悪い例（再利用には曖昧すぎる）:

• バグを修正しました
• 私はユーザーを認証で支援しました
• 問題はタイミングでした

output_summaryは再利用可能な知識チャンクになります。物語のように読める場合は、原則として書き直してください。一般的で転用可能な形式を優先します — リポジトリ/ファイル/関数名や1回限りの識別子を取り除き、次のプロジェクトでも再利用できるように教訓を言い換えます。プロジェクト固有の詳細は、教訓が一般化すると意味を失う場合にのみ保持します。 有用なサマリーを書けない場合は、output="unknown"に設定し、記録をスキップします。

呼び出し: innate_record(trace_id=<id>, outcome=<ok|fail|unknown>, used=[<chunk_ids>], output_summary=<文>)

明示的なフィードバック — その重要性

評決テーブルからのfeedback_up / feedback_downリストは、知識品質の最速のシグナルであり、ランキングとライフサイクルを直接駆動します: 同じチャンクに対する2つのダウンシグナルはガバナンスレビューをトリガーし、5つは自動アーカイブをトリガーします。逆に、繰り返されるused + feedback_upは、pendingチャンクをactiveに昇格させます。フィードバックを差し控えると知識ベースは凍結します。フィードバックを与えることで、良い知識が浮上し、悪い知識が排除されます。

ノミネーション — 稀、明示的

nominationフィールドは、真に一般化可能な教訓にのみ使用します — この種の問題が次に現れたときに大幅な時間節約になるパターン。希少です。すべてのタスクに使用するものではありません。

ノミネーションのフォーマット（自己完結型の原則）:

<原則> — <それが適用される時> — <避けるべきこと>

例:

innate_record(..., nomination="SQLite UNIQUE index on partial WHERE clause requires exact WHERE match in ON CONFLICT — applies to all upsert patterns; bare ON CONFLICT without WHERE will silently skip the upsert")

MCPツールリファレンス

ツール	用途	注意事項
innate_recall	タスク開始時（関連する場合）	正規化されたクエリ形式を使用 — 一貫した言い回しでコンテキスト統計を蓄積
innate_record	タスク終了時（実際の結果がある場合）	構造化されたoutput_summary + 正確な使用済みID
innate_add	確認された洞察をキャプチャ	常にsource="mcp"、pending状態になり、レビューを待つ
innate_spark	後で使うクイックアイデア	簡潔な蒸留形式、レビュー不要
innate_evolve	セッション終了時	trigger="manual"、ログを蒸留し知識ベースをキュレート
innate_inspect	ヘルスチェック	チャンク数、負債比率、再構築キュー
innate_appraise	リスクのあるステップ前の直感チェック	参照シグナルのみ — 直感であり、正確な答えではありません。1つの入力として考慮し、自身の分析を上書きさせないでください。abstained=trueは根拠がないことを意味します — それは正しく、失敗ではありません

ユーザーの明示的な要求なしに呼び出してはいけません: innate_approve、innate_archive、innate_invalidate、innate_restore、innate_mature_spark、innate_promote_spark、innate_drop_spark。

書き戻しの判断

長いセッションを終了する前に、静かにこのチェックリストを実行します:

1. 明白でない解決策が見つかりましたか？（回避策、隠れた制約、微妙なバグパターン）
2. 一般的で転用可能なスキル、方法、テクニックが表面化しましたか？（これらを優先 — プロジェクト固有の教訓を抽象化して再利用可能な形式にします。本当に一般化できない場合のみ、プロジェクト固有のルールを保持します）
3. ユーザーが、私が繰り返しそうな誤った前提を修正しましたか？
4. 複数回の失敗を経て、苦労して得た洞察に到達しましたか？
5. 呼び出されたチャンクが能動的に役立ちましたか？（feedback_upを記録）
6. 呼び出されたチャンクが誤解を招きましたか？（feedback_downを記録）

1〜4のいずれかが該当する場合 → ユーザーに提案:

「このセッションで[1行の説明]が明らかになりました。Innateに保存しますか？」

innate_sparkまたはinnate_addは、ユーザーが確認した後にのみ呼び出します。静かに書き込んではいけません。

逐語的禁止ルール

生の会話テキストを保存してはいけません。常に再利用可能な原則形式に蒸留します:

<原則> — <トリガーコンテキスト> — <避けるべきこと>

❌ 逐語	✅ 蒸留
「ユーザーがWALモードを使うように言って、私はプラグマを変更して修正しました」	「SQLite WAL mode must be verified via PRAGMA response, not assumed — triggers on any db open in write-heavy multi-process setups」
「時計のずれのため、認証のデバッグに2時間費やしました」	「JWT validation must account for clock skew tolerance (≥30s) — triggers on distributed auth between services with independent system clocks」

プロジェクト固有より一般を優先

Innateは一般的で転用可能なスキル、方法、テクニックに偏っています — 現在のコードベースだけでなく、プロジェクト間で効果を発揮する知識。教訓がプロジェクト固有の場合:

1. 抽象化を試みます — リポジトリ/ファイル/関数/パス名や1回限りの識別子を削除し、次のプロジェクトで再利用できる原則として言い換えます。
2. 抽象化された形式を保存します。教訓が一般化すると意味を失う場合にのみ、具体的なプロジェクト固有の詳細を保持します。

❌ プロジェクトに束縛	✅ 一般化
「このリポジトリでは、record()はBEGIN IMMEDIATE内で実行する必要があります」	「Multi-step state mutations that must be atomic belong in one exclusive transaction, not per-step commits — applies to any SQLite writer with concurrent processes」
「メタテーブルでrecall.budget=4000を設定します」	「Expose retrieval budget as a tunable parameter instead of hardcoding it — lets recall scale with the context window without code changes」

スパークとノートの違い

innate_sparkを使用する場合	innate_addを使用する場合
簡単なアイデア、半形成の直感	確認された再利用可能な原則
まだ検証されていない	このセッションで検証済み
ユーザーが「後でメモしておいて」と言う	ユーザーが「このルールを覚えておいて」と言う

CLIフォールバック（MCPが設定されていない場合）

# 呼び出し
innate recall "<正規化された意図>" --top 5 --format json --source cli

# 構造化サマリーで記録
innate record <trace_id> --outcome ok \
  --used <id1>,<id2> \
  --output-summary "Fixed X by doing Y — applies when Z" \
  --feedback up  # または down

# 洞察をキャプチャ
innate add "<原則> — <トリガー> — <避けるべきこと>" \
  --trigger "<2〜5単語のコンテキスト>" \
  --source agent

# クイックスパーク
innate spark "<蒸留されたアイデアを1〜2文で>"

# セッション終了
innate evolve --trigger manual
innate inspect

コマンド

以下のスラッシュコマンドは、innate installによって~/.claude/commands/に自動インストールされ、innate installを再実行するたびに更新されます。各commandブロックは1つのコマンドを定義します: ---の前がメタデータ、後が本文（エージェントプロンプト）です。

name: innate-recall
description: 現在のタスクコンテキストに関する事前のinnate知識を呼び出します
---
現在のタスクコンテキストに対してinnate_recallを実行し、結果をこの会話に注入します。

ユーザーがコマンドの後にクエリを提供した場合、それをそのまま想起クエリとして使用します。
クエリが提供されなかった場合（$ARGUMENTSが空）、最新のユーザーメッセージまたは現在のタスクの意図からクエリを推測します — **正規化された意図**を使用します（例: `sqlite wal mode init`、`なぜこれがクラッシュするのか`などではありません）。将来同じクラスの問題をどのように表現するかと一貫性のあるクエリ形式を保ちます。

手順:
1. 正規化されたクエリ文字列を作成します（$ARGUMENTSまたは推測された意図から）。
2. `innate_recall`を`query=<query>`、`budget=4000`、`source="mcp"`で呼び出します。
3. 知識が返された場合: 見つかった内容を1文で要約し、関連するチャンクをコンテキストに注入します。
4. 空の場合: 「事前知識は見つかりませんでした: <query>」と言います — 捏造しないでください。
5. 後で`/innate-record`で使用するために`trace_id`を保存します。

name: innate-record
description: 現在のinnateトレースを結果と構造化サマリーで閉じます
---
現在のinnateトレースを結果とサマリーで閉じます。

$ARGUMENTSを解析:
- outcome: `ok`、`fail`、`unknown`のいずれか（指定がない場合のデフォルト: `ok`）
- 残りのテキストはoutput_summaryのオーバーライドになります

手順:
1. このセッションの最新の`innate_recall`呼び出しからアクティブなtrace_idを特定します。
   trace_idが利用できない場合、「アクティブなトレースがありません — 最初に/innate-recallを実行してください。」と言います。
2. 最終応答で**実際に使用された**呼び出しチャンクIDを決定します（候補として呼び出されただけのものではありません）。正確に — 使用されなかった呼び出しチャンクはリストしてはいけません。
3. 将来のエージェントが冷めた状態で読むための構造化されたoutput_summaryを記述します:
   フォーマット: `<行われたこと> — <主要な制約/方法> — <これが適用される時>`
   ユーザーが$ARGUMENTSでサマリーテキストを提供した場合は、それを使用します。
4. フィードバックを評価:
   - チャンクが直接役立った場合 → `feedback_up=[chunk_id]`を含める
   - チャンクが間違っていた/誤解を招いた場合 → `feedback_down=[chunk_id]`を含める
5. `innate_record`を`trace_id`、`outcome`、`used=[<chunk_ids>]`、`output_summary`、該当する場合はフィードバックとともに呼び出します。
6. 確認: 「トレース <trace_id> を <outcome> として記録しました。」

name: innate-save
description: 確認された洞察を保留中の知識チャンクとしてInnateに保存します
---
確認された洞察を保留中の知識チャンクとしてInnateに保存します。

$ARGUMENTSは保存する洞察テキストです（必須）。空の場合、「どの洞察を保存しますか？」と尋ねます。

手順:
1. $ARGUMENTSを洞察コンテンツとして解析します。
2. Di

…

[翻訳のため省略]