introspect は何をしますか?
AI コーディングスレッドで起きたことを、エージェントの動作を変える変更に変えます。 これにより、セットアップが毎回リセットされるのではなく、複利的に構築されていきます。
エージェント非依存です。Claude Code、OpenAI Codex、Cursor のスレッドを読み取り、変更に値する少数の項目を見つけ、あなたの承認を得て、将来のセッションを実際に制御するエージェントの設定に書き戻します。Claude Code には既に /insights があり、過去 30 日間を読んでレポートを表示します。これが「読み取り」側(Claude のみ)です。Introspect は「書き込み」側であり、使用するすべてのエージェントに対応します。このアイデアを生んだスレッドで Youssef がうまく表現しています:「出力を何千回も修正する必要がないように、システムを一度修正せよ」。
これを機能させる 1 つのアイデア:戦術ではなくパターン
「何を改善できたか?」の失敗パターンは、戦術(コマンドのより良いフラグ、あるバグへのより賢いアプローチ)が表面化することです。これらは複利になりません。明日には消えています。
複利になるのは、あなたが繰り返し続けている習慣、つまり 3 つの異なるスレッドにわたる同じ修正、毎週言い直す同じ好み、テスト環境に触れるたびにエージェントが取る同じ誤った方向性です。そのため、このスキル全体は再発性に偏っています:
変更候補として価値があるのは、複数回出現し、既にどこかに記録されておらず、結果を変えていた可能性が高いものだけです。それ以外はすべてノイズです — ログに記録し、行動には移さないでください。
これは、そのスレッドで人々が挙げた 2 つの懸念に対する正直な答えでもあります:
- 「悪い決定が複利になることや、ワークフローが馬鹿になるのが心配です」 → あなたが正確な差分を見て承認するまでは、何も書き込まれません。適用された変更はすべてログに記録され、元に戻せます。迷ったら、提案する項目を減らしてください。
- 「毎日スキルを永遠に更新し続けるだけですか — 収束することはありますか?」 → 収束するはずです。ルールが既に存在する場合は、強化またはマージします。2 つ目を追加することはありません。静かな日は空の変更セットを生成しますが、それは成功であり、失敗ではありません。
パイプライン
収集 → 抽出 → 既存設定との差分比較 → 変更セットの提案 → 承認 → 適用 + ログ記録
(スクリプト) (あなた) (あなた、現在の設定を読む) (あなた、証拠と共に) (ユーザー) (あなた、元に戻せる形で)
1. 収集 — スクリプトを実行する。何も手動で再パースしない
scripts/collect_threads.py は各エージェントのスレッドストア(Claude の JSONL、Codex のロールアウトファイル、Cursor の SQLite)を読み取り、ウィンドウでフィルタリングし、秘密情報を編集し、1 つの共通ダイジェストを出力します。セッションごとに、どのエージェントか、人間が入力したプロンプト、使用されたツール、ツールがエラーになった場所、軽量な「フリクション」シグナル(修正のように読めるプロンプト、複数回連続して呼び出されたツール)をタグ付けします。
python3 scripts/collect_threads.py --days 1 # 今日、インストールされている全てのエージェント(自動)
python3 scripts/collect_threads.py --agent all --days 7 # 先週、3つ全てを強制
python3 scripts/collect_threads.py --agent codex --format md
python3 scripts/collect_threads.py --since 2026-07-01 --until 2026-07-05 --format json
python3 scripts/collect_threads.py --project ~/dev/myproject # 1つのプロジェクト
python3 scripts/collect_threads.py --selftest # 3つのパーサーを健全性チェック
--agent のデフォルトは auto(インストールされているエージェントを検出)。--format md は自分で読む場合に使用。--format json は後処理用。スクリプトは何も決定しません — クリーンで正規化された生の素材を提供するため、あなたは 3 つの異なるトランスクリプト形式をパースするのではなく、重要なことに判断力を費やせます。
2. 抽出 — ダイジェストを読み、3 種類のものを抽出する
あたかもユーザーの参謀長がすべてのツールにわたる一日をレビューするかのように、ダイジェストを読みます。ユーザーの好みが最優先です — このスキルは主に、ユーザーがどのように仕事をするのが好きかを学習することであり、エージェントのベースライン動作を監視することではありません。以下の 3 つに分類します:
- 永続的な好み(メインイベント) — ユーザーがデフォルトを訂正したり、自分の好みを言い直したりしている場合(「いいえ、pnpm を使って」「コメントを追加するのをやめて」「常に最初に開発からブランチを切って」「ワークツリーに触らないで」)。Claude と Codex の両方のスレッドに現れる好みは特に強いシグナルです — それはツールではなく、あなた自身に関するものです。
- エージェントに作業を繰り返させたセットアップのギャップ — 何かが文書化されていなかったために、エージェントが複数のセッションにわたって再導出したり行き詰まったりした場合:ビルドコマンドの再学習、常に同じ場所にあるファイルの再発見、プロジェクトコンテキストの欠落。修正方法は、不足している情報をユーザーの設定に書き込むことです — エージェントを叱るルールを追加することではありません。繰り返しが、ユーザー固有の修正がない単なる一般的なエージェント動作である場合(例:「ファイルを編集する前に読む」)、それはルールではなくノイズです。除外してください。
- 再利用可能なワークフロー — ユーザーが複数回実行した複数ステップの作業で、スキルまたはコマンドにして次回は 1 ステップにする価値があるもの。
各候補について、証拠を書き留めます:どのエージェント、どのセッション、何回、短い引用。再発の証拠がない → それは戦術であり、パターンではない → 破棄します。
3. 既存設定との差分比較 — ブロート防止 / 収束ステップ
何かを提案する前に、関連するエージェントに対して既に何があるかを読み、システムを肥大化させるのではなく強化します。references/routing.md に各エージェントの正確な読み取り/書き込み場所と形式があります。簡易版は以下の通り:
| エージェント | 読み取り(および後で書き込み)する既存の設定 |
|---|---|
| Claude | ~/.claude/CLAUDE.md(グローバル)、./CLAUDE.md、プロジェクト別メモリ ~/.claude/projects/<dir>/memory/、~/.claude/skills/、~/.claude/commands/ |
| Codex | ~/.codex/AGENTS.md(グローバル)、<repo>/AGENTS.md(プロジェクト)、~/.agents/skills/ のスキル |
| Cursor | .cursor/rules/*.mdc(プロジェクト)、レガシー .cursorrules、AGENTS.md |
各候補について問います:これは既にカバーされていますか? はいの場合 → 破棄するか、既存のルールを明確化する小さな編集を提案します。ほぼ同じことを言う 2 つ目のルールを決して追加しないでください。2 つの候補が重複する場合は、マージします。追加よりも編集を優先します。
クロスエージェントのヒント: AGENTS.md は Codex と Cursor によって読み取られ、多くの人はこれを CLAUDE.md にシンボリックリンクしています。好みが本当に普遍的なものであれば、すべてのエージェントが見る場所に書くことを優先します(1 つの AGENTS.md、または CLAUDE.md↔AGENTS.md のシンボリックリンク)。3 回重複させるよりも良いです。書き込む前に常にシンボリックリンクを解決し、実際にどのファイルを編集しているかを把握してください。
4. 変更セットの提案 — 証拠付きの具体的な差分、上限付き
変更セットを提示します:順序付けられ、スキャン可能なリストで、各項目にターゲットエージェント + ファイル、正確な編集(差分または明確にマークされた before/after)、証拠、および信頼度を含めます。references/changeset-format.md の形式を使用します。2 つのルールで健全性を保ちます:
- 上限を設ける。 実行ごとに最大約 5 つの変更を表面化させ、最も信頼度の高いものから順に。それ以外は「バックログ」セクションに移します — 記録するだけで、適用しません。編集の洪水はワークフローを愚かにする方法です。
- 再発性 × 影響でランク付けする。 3 回述べられ、毎セッションで修正を節約する好みは、賢い 1 回限りのものよりも常に優先されます。
何も適用されない場合でも、日付入りのレポートに変更セットを常に保存して、後で振り返るための記録を残します(これはスレッドの「出力をどこかに保存しますか、それとも読んで次に進むだけですか?」という質問に答えます)。~/.introspect/reports/YYYY-MM-DD.md に書き込みます。
5. 承認 — ゲート
変更セットを表示し、ユーザーに何を適用するか選択させます:すべて、一部、またはなし。デフォルトは 提案して承認 — 明示的な了承なしにエージェントの設定を編集しないでください。複数の項目がある場合は、AskUserQuestion(複数選択)を使用して選択させます。ユーザーが明示的に無人/スケジュール実行を要求した場合は、以下の「無人実行」を参照してください。
6. 適用 + ログ — 元に戻せる形で
承認された各項目について、適切な場所に書き込みます(完全な形式は references/routing.md にあります):
- Claude — CLAUDE.md: 適切な
##セクションの下に追加するか、ルールをその場で編集します。ハウススタイル(簡潔で、命令形で、理由を説明)を維持します。 - Claude — memory: ノードファイルを作成/追加し、
MEMORY.mdに 1 行のインデックスを追加します。feedback_*/project_*/reference_*の規則と[[wikilink]]クロスリンクに一致させます。 - Claude — skill/command:
~/.claude/skills/<name>/SKILL.mdまたは~/.claude/commands/<name>.mdを作成/編集します。複数のセッションが同じヘルパースクリプトを書き換えた場合は、バンドルします。 - Codex — AGENTS.md: 管理ブロック内(
<!-- introspect:begin --> … <!-- end -->)に追加して、再実行時に冪等にします。コンパクトに保ちます(Codex は AGENTS.md を約 32 KiB で切り詰めます)。プロジェクトルートのAGENTS.mdを優先します(デスクトップアプリはグローバルなものを確実に読み込まないため)。 - Cursor — .cursor/rules/*.mdc: YAML フロントマター付きのルールファイルを書き込みます(常時オン設定の場合は
alwaysApply: true、そうでない場合はdescription:+alwaysApply: false)。Cursor のクラウド「メモリー」には書き込もうとしないでください。ルールファイルを使用してください。Cursor 実行中はライブstate.vscdbに書き込まないでください。
次に、台帳 ~/.introspect/ledger.jsonl に 1 行を追加します — 適用された変更ごとに 1 つの JSON オブジェクト:{date, agent, target_file, kind, summary, evidence, sessions, undo_hint}。台帳により、(a) 設定が時間とともにどのように複利的に構築されたかを示し、(b) 後で変更を元に戻すことができます。既存のファイルを編集する前に、その以前の状態を undo_hint に記録するか(または .bak を保持します)。
安全性モデル(これを読んでください — これが毎日実行しても安全な理由のすべてです)
- 提案し、押し付けない。 承認ゲートはデフォルトでオン。ユーザーはすべての差分を確認します。
- 再発閾値。 単一の発生から提案しないでください。習慣であり、戦術ではありません。
- 収束し、攪乱しない。 ほぼ重複するものを追加する代わりに、既存のルールを強化/マージします。何も変更しない実行は問題なく、静かな日には予想通りです。
- 爆発半径を制限する。 実行ごとに最大約 5 つの変更。残りはバックログへ。
- ルールはユーザーに関するものであり、エージェントに関するものではない。 ユーザーがどのように仕事をしたいかを捉えます。エージェントのベースライン能力を単に言い換えるルール(「編集前に読む」など)を作成しないでください — それはブロートです。「エージェントが行き詰まった/繰り返した」というシグナルは、ユーザーのセットアップの一部を書き留めることで繰り返しを防げる場合にのみ、変更の価値があります。
- 秘密情報を決して保存しない。 コレクターは一般的なキー/トークンのパターンを編集しますが、警戒を怠らないでください:API キー、パスワード、
.envの値、トークンをルールやレポートにコピーしないでください。見つけた場合は除外し、(アクティブに見える場合は)ユーザーにフラグを立てます。 - 元に戻せる。 適用されたものはすべて、元に戻すヒントとともに台帳にあります。
- 適切な場所、適切なスコープ。 ユーザー全体の好み → そのエージェントのグローバルファイル。プロジェクト固有の事実 → そのプロジェクトの設定。プロジェクトの些細なことをグローバルファイルに入れないでください。
トリガー — 3 つの実行方法
- オンデマンド。 「スレッドをレビューして」「introspect を実行して」「今週、Claude と Codex で何を繰り返し言い続けた?」「今日の修正をルールにして」。デフォルトウィンドウ:今日。
- 毎日 / スケジュール(ハーネスネイティブ)。 ハーネスのネイティブスケジューラ(
scheduleスキルまたはCronCreateルーチンツール)を介して実行を登録します。OS の cron、launchd、シェルループは使用しないでください。ネイティブスケジューリングは、同じツールと権限でハーネス内でルーチンを実行し、ユーザーは/scheduleで管理します。良いデフォルトは、その日のウィンドウに対して 1 日 1 回夕方に実行することです。 - N セッションごと / フリクション時(オプション)。 一部の人は(ソーススレッドの buildooor を参照)、時計ベースではなく、何か問題が起きたときや約 10 セッションごとにこれをトリガーすることを好みます。呼び出しをカウントし、N 回後に促す
Stopフックとして配線します。提供します。承認なしにフックをインストールしないでください。
無人実行
人間が立ち会わないスケジュール/ルーチンによって呼び出された場合は、エージェントの設定に変更を黙って適用しないでください。代わりに、パイプラインを実行し、提案された変更セットを含む日付入りレポートを ~/.introspect/reports/ に書き込み、(ルーチンの通知を介して)短い概要を表面化させ、ユーザーが次のインタラクティブセッションで承認できるようにします。無人で自動適用しても安全な唯一のカテゴリは、重複しない新しい Claude メモリノードです — それでもログに記録します。複利を人間の制御下に置き続けてください。それがポイントです。
リファレンス
references/routing.md— エージェントごとの読み取りソース + 書き込み表面 + 正確なディスク上の形式(CLAUDE.md、memory、AGENTS.md、.cursor/rules/*.mdc)およびコレクターが使用するトランスクリプトスキーマ。references/changeset-format.md— 変更セット + レポート + 台帳テンプレート。scripts/collect_threads.py— マルチエージェントコレクター(--selftestを実行して確認)。
コアループをもう一度。これがすべてです:すべてのエージェントからスレッドを収集 → 再発性のあるパターン(単発の戦術ではない)を見つける → 既に書き留められていないか確認する → 小さく、上限があり、証拠に基づいた変更セットを提案する → 承認されたものだけを適切なエージェントの設定に適用する → 元に戻せる形でログに記録する。