introspect 是做什麼的?
將 AI 編碼線程中發生的事情,轉化為代理為你工作的方式——這樣你的設定就能持續累積,而不是每次會話都重置。
它是與代理無關的。它會讀取來自 Claude Code、OpenAI Codex 和 Cursor 的線程,找出值得改變的少數事項,並在經過你批准後,將其寫回實際引導未來會話的代理設定檔中。Claude Code 已經內建了 /insights,它會讀取你過去 30 天的記錄並向你顯示一份報告。那是「讀取」部分,且僅限 Claude。Introspect 是「寫入」部分,適用於你使用的每一個代理。Youssef 在產生這個想法的討論串中說得好:一次解決系統問題,這樣你就不必解決一千次輸出問題。
讓這個想法成立的關鍵:模式,而非戰術
「我哪裡可以做得更好?」的失敗模式在於,它只會浮現出戰術——某個命令更好的旗標、處理某個錯誤更聰明的方法。這些不會累積,明天就消失了。
真正能累積的是你一直反覆養成的習慣:你在三個不同線程中給出的同一個修正、你每週重複提出的同一個偏好、你的代理每次碰到測試設定時都會犯的同一個錯誤。因此,整個技能偏重於重複性:
只有當一個候選變更出現超過一次、尚未被寫在任何地方、並且合理推測會改變結果時,它才有資格被採納。除此之外都是雜訊——記錄下來就好,不要付諸行動。
這也是對討論串中人們提出的兩個擔憂的誠實回答:
- 「我擔心會累積錯誤的決策 / 讓我的工作流程變笨。」 → 沒有你親眼看到確切的 diff 並批准,什麼都不會寫入。每一個已套用的變更都會被記錄且可逆。當有疑慮時,寧可提出更少的項目。
- 「它是不是每天都會一直更新技能,永遠不會收斂?」 → 它應該會收斂。如果一條規則已經存在,你會強化或合併它,而不是新增一條。安靜的一天會產生空的變更集,這不是失敗,而是成功。
管線
收集 → 提取 → 與現有設定比對 → 提出變更集 → 批准 → 套用 + 記錄
(腳本) (你) (你, 讀取當前設定) (你, 附帶證據) (用戶) (你, 可逆)
1. 收集 — 執行腳本,不要手動重新解析任何東西
scripts/collect_threads.py 會讀取每個代理的線程儲存庫(Claude 的 JSONL、Codex 的 rollout 檔案、Cursor 的 SQLite),過濾時間範圍,遮罩機密資訊,並產生一個統一的摘要:每個會話會標記是哪個代理、人類輸入的提示、使用的工具、工具何處發生錯誤,以及輕量化的「摩擦」訊號(看起來像修正的提示、連續多次呼叫的工具)。
python3 scripts/collect_threads.py --days 1 # 今天,每個已安裝的代理(自動偵測)
python3 scripts/collect_threads.py --agent all --days 7 # 過去一週,強制掃描全部三個代理
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 # 一個專案
python3 scripts/collect_threads.py --selftest # 健全性檢查三個解析器
--agent 預設為 auto(自動偵測已安裝的代理)。當你自己閱讀時使用 --format md;要進行後續處理時使用 --format json。這個腳本永遠不會代替你做決定——它提供你乾淨、標準化的原始材料,讓你可以將判斷力花在重要的事情上,而不是解析三種不同格式的對話記錄。
2. 提取 — 閱讀摘要並篩選出三種項目
閱讀摘要時,想像你是用戶的幕僚長,正在回顧這一天在他所有工具中的工作情況。使用者的偏好優先——這個技能主要是學習他們喜歡如何工作,而不是糾正代理的基準行為。區分:
- 持久性偏好(主要項目) — 用戶糾正預設行為或重申他們喜歡的方式(例如「不,用 pnpm」、「停止添加註解」、「總是先從 development 分支出去」、「不要碰工作樹」)。一個同時出現在你的 Claude 和 Codex 線程中的偏好是特別強烈的訊號——這關乎你,而不是工具。
- 導致代理重複工作的設定缺口 — 代理在多次會話中重新推導或卡住,因為某些東西沒有被寫下來:重新學習建構指令、重新尋找總是放在同一個位置的檔案、遺失專案上下文。解決方法是將遺失的資訊寫入用戶的設定檔——而不是新增一條責備代理的規則。如果重複只是通用代理行為,沒有用戶特定的修正(例如「在編輯檔案前先讀取它」),那就不是規則,而是雜訊;請忽略它。
- 可重複的工作流程 — 用戶執行超過一次的多步驟流程,應該將其變成一個技能或指令,以便下次只需一步完成。
對於每個候選項目,寫下證據:是哪個代理、哪些會話、出現次數、簡短引用。沒有重複發生的證據 → 這是戰術,不是模式 → 丟棄它。
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 |
對於每個候選項目,問:這個已經涵蓋了嗎? 如果是 → 丟棄它,或者提出一個能強化現有規則的小修改。絕對不要新增一條意思幾乎相同的第二條規則。如果兩個候選項目重疊,請合併它們。優先編輯而非新增。
跨代理提示: AGENTS.md 會被 Codex 和 Cursor 讀取,而且許多人會將其符號連結到 CLAUDE.md。如果一個偏好確實是通用的,最好將其寫入所有代理都能看到的地方(一個 AGENTS.md,或一個 CLAUDE.md↔AGENTS.md 符號連結),而不是在三處重複。在寫入之前,總是先解析符號連結,這樣你才知道你真正在編輯的是哪個檔案。
4. 提出變更集 — 帶有證據的具體 diff,並設定上限
呈現一個變更集:一個有序、易於瀏覽的清單,其中每個項目包含目標代理 + 檔案、確切的編輯(diff 或清楚標記的之前/之後)、證據和信心指數。使用 references/changeset-format.md 中的格式。兩條規則使其保持合理:
- 設定上限。 每次運行最多顯示約 5 個變更,優先顯示信心指數最高的。其他項目放入「待辦」區段——記錄下來,但不套用。大量編輯是工作流程變笨的原因。
- 按重複次數 × 影響力排序。 一個被提及三次、每次會話都能省下一次修正的偏好,永遠比一個聰明的一次性技巧重要。
即使沒有套用任何項目,也要將變更集儲存為一份標記日期的報告,以便日後回顧(這回答了討論串中「你是否會將輸出儲存在任何地方,或者只是讀取後就繼續?」的問題)。將其寫入 ~/.introspect/reports/YYYY-MM-DD.md。
5. 批准 — 關卡
顯示變更集,讓用戶選擇要套用哪些項目:全部、部分或無。預設為提議並等待批准——在沒有得到明確同意之前,不要編輯任何代理的設定。當有多個項目時,使用 AskUserQuestion(多選)讓用戶挑選。如果用戶明確要求無人的/排程運行,請參閱下面的「無人運行」。
6. 套用 + 記錄 — 可逆
對於每個已批准的項目,寫入正確的位置(完整格式請參閱 references/routing.md):
- Claude — CLAUDE.md: 在適當的
##區段下附加,或就地編輯規則;保持內部風格(簡短、命令式、解釋原因)。 - Claude — 記憶: 建立/附加一個節點檔案,並在
MEMORY.md中新增一行索引;符合feedback_*/project_*/reference_*慣例和[[wikilink]]交叉連結。 - Claude — 技能/指令: 建立/編輯
~/.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 frontmatter 的規則檔案(
alwaysApply: true用於始終開啟的偏好,或description:+alwaysApply: false)。不要嘗試寫入 Cursor 的雲端「記憶」;使用規則檔案。不要在 Cursor 運行時寫入state.vscdb。
然後在分類帳 ~/.introspect/ledger.jsonl 中附加一行——每個套用的變更一個 JSON 物件:{date, agent, target_file, kind, summary, evidence, sessions, undo_hint}。這個分類帳讓你 (a) 顯示設定如何隨著時間累積,以及 (b) 稍後撤銷變更。在編輯現有檔案之前,請在 undo_hint 中記錄其先前狀態(或保留一份 .bak 備份)。
安全模型(請閱讀——這是為什麼可以安全地每日運行)
- 提議,而非強制。 批准關卡預設開啟。用戶會看到每個 diff。
- 重複性門檻。 不要從單一事件提出建議。要的是習慣,而不是戰術。
- 收斂,而非攪動。 強化/合併現有規則,而不是新增幾乎重複的規則。在安靜的日子裡,沒有變更的運行完全沒問題,也是預期的。
- 限制影響範圍。 每次運行最多約 5 個變更;其餘放入待辦。
- 規則是關於用戶,而不是關於代理。 捕捉用戶想要如何工作。不要製造只是重申代理基本能力的規則(例如「編輯前先讀取」)——那是膨脹。一個「代理卡住/重複自己」的訊號,只有在記錄用戶本身的設定能避免重複時,才有資格產生變更。
- 絕不儲存機密。 收集器會遮罩常見的金鑰/權杖格式,但請保持警覺:絕對不要將 API 金鑰、密碼、
.env值或權杖複製到規則或報告中。如果你看到一個,請忽略它,如果它看起來是活躍的,請向用戶標記。 - 可逆。 所有套用的內容都在分類帳中,並附有復原提示。
- 正確的位置,正確的範圍。 全域性偏好 → 該代理的全域檔案。專案特定事實 → 該專案的設定檔。不要將專案的瑣碎資訊放在全域檔案中。
觸發方式 — 三種運行方式
- 隨需執行。 「review my threads」、「run introspect」、「what did I keep repeating this week across Claude and Codex」、「turn today's corrections into rules」。預設時間範圍:今天。
- 每日 / 排程(原生於 harness)。 通過 harness 的原生排程器註冊運行——使用
schedule技能或CronCreate例行工具——而不是作業系統的 cron、launchd 或 shell 迴圈。原生排程會在 harness 內部使用相同的工具和權限運行例行任務,用戶可以透過/schedule管理它。一個好的預設值是每天傍晚運行一次,處理當天的時間範圍。 - 每 N 次會話 / 遇到摩擦時(可選)。 有些人(請參閱原始討論串中的 buildooor)更喜歡在出錯時或大約每 10 次會話時觸發此功能,而不是根據時鐘。將其掛載為一個
Stop鉤子,計算呼叫次數並在達到 N 次後提示。提供此選項;未經批准絕不安裝任何鉤子。
無人運行
如果由排程/例行任務在沒有人類在場的情況下呼叫,請不要默默地對任何代理的設定套用變更。相反地:執行管線,將包含提議變更集的日期報告寫入 ~/.introspect/reports/,並透過例行任務的通知顯示一個簡短摘要,以便用戶在下一次互動會話中批准。唯一可以在無人情況下安全自動套用的類別是一個不重複的新 Claude 記憶節點——即便如此,也要記錄它。將累積過程置於人類控制之下;這才是重點。
參考資料
references/routing.md— 每個代理的讀取來源 + 寫入位置 + 確切的磁碟格式(CLAUDE.md、記憶、AGENTS.md、.cursor/rules/*.mdc)以及收集器使用的對話記錄結構。references/changeset-format.md— 變更集 + 報告 + 分類帳範本。scripts/collect_threads.py— 多代理收集器(執行--selftest來驗證它)。
再次重複核心循環,因為這就是一切:從每個代理收集線程 → 找到重複出現的模式(而非一次性戰術)→ 檢查它們是否尚未被記錄 → 提出一個小型的、有上限的、附帶證據的變更集 → 僅將批准的項目套用到正確代理的設定檔 → 可逆地記錄。