Communitygithub.com

scchearn/loam

AI 編碼代理的工作流程技能:規劃、執行,並在會話間維持持久知識庫。

loam 是什麼?

loam 是一個路由/元技能,用於管理工作流程和記憶,專為 AI 編碼代理(如 Claude Code、Cursor 或 Codex)設計。它不直接執行任務,而是將意圖映射到特定的子技能(例如 `loam::planning`、`loam::adding-to-memory` 或 `loam::checkpointing`),並強制執行三項不可協商原則:在記憶操作前始終調用相關技能;將「記憶」置於「wiki」之上,只有當區分記憶的不同子層(wiki、guidance、checkpoints)時才使用「wiki」;以及代理擁有的記憶寫入,無需事先批准。該技能包含一個記憶模型,具有三個子層:持久化 markdown 筆記的 wiki、行為準則的 guidance(`AGENTS.md`),以及工作狀態的快照。嚴格的錄取標準(可重複使用、與專案相關、重建成本高且可重新驗證)和排除條件(短暫或重複)控制哪些內容屬於持久化 wiki,而其餘內容則路由到 guidance、checkpoints、任務註釋或捨棄。loam 還提供了自我修正、人工標記觸發、新鮮度驗證規則、衝突解決優先級以及用於選擇正確技能的決策樹,確保記憶在會話間保持一致、可恢復且對 AI 代理有用。

相容平台✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add scchearn/loam

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

使用 loam

這是 loam 技能命名空間的路由器。它本身不執行工作。它告訴你要為特定意圖調用哪個 loam 技能,以及適用於所有這些技能的規則。

這是一個路由/元技能。 當你識別出匹配的技能時,通過主機 harness 的 skill loader 調用它。不要在這裡執行工作。

不可協商原則

三條規則讓 loam 的工作與記憶模型保持一致。

  1. 在任何 loam 操作之前調用相關技能。 不僅是工具調用。在規劃、研究、開始、恢復、建立檢查點、辯論或達成共識、修改計劃、添加到記憶、查詢記憶、修改記憶、lint 記憶、標準化記憶、審查記憶、捕獲學習成果、審計準則、搭建 wiki 或初始化倉庫之前:調用匹配的技能。本文檔是一個路由器。技能主體包含實際規則。其他所有操作的責任在你身上。寧可多調用,不要少調用。
  2. 記憶優先,子層其次。 首先談論「記憶」。僅在區分 markdown 子層與準則或檢查點子層時使用「wiki」。永遠不要用「wiki」來表示「記憶」——wiki 只是記憶的一個子層,並非全部。
  3. 代理擁有的記憶寫入。 代理在無需事先批准的情況下編寫、修正、路由和歸檔記憶。人類可以標記過時或錯誤的內容,這會觸發與代理發現矛盾時相同的修正流程。

記憶模型

記憶 是 loam 捕獲的所有內容的總稱概念。存在三個子層:

子層它是什麼誰維護它
wiki位於 wiki/ 下的持久化、兼容 Obsidian 的 markdown 筆記。主題、實體、概念、分析頁面。loam-memory 群組(大多數技能)
guidanceAGENTS.md 是規範的準則文件。CLAUDE.md 是一個輕量導入 shim(僅 @AGENTS.md)。.claude.local.md 用於個人覆蓋。loam-memory 群組(auditing-guidance、learning-from-session 的 guidance 路徑)
checkpoints位於 wiki/checkpoints/ 下的臨時工作狀態。恢復筆記,非持久化知識。loam-work 群組(checkpointing 寫入,resuming 讀取)

wiki 子層是 qmd 索引的內容。guidance 子層是 harness 作為提示上下文加載的內容。檢查點是工作狀態,而非知識——它們拒絕觸碰 index.md 或 log.md,並且不應成為持久化聲明。

首先談論「記憶」。僅當子層區別重要時才使用「wiki」。 一個操作 markdown 筆記的技能是在記憶的 wiki 子層上工作。一個編輯 AGENTS.md 的技能是在記憶的 guidance 子層上工作。兩者都是記憶。

持久化記憶錄取標準

在創建 wiki 頁面之前使用此標準。創建頁面的技能應引用此部分,而不是複製它。

一個聲明只有通過以下所有三項才能獲得 wiki 頁面:

  • R1 可重複使用 — 未來處理不同任務的會話很可能需要它。
  • R2 關於專案/領域 — 程式碼庫、架構、決策、慣例、外部依賴或持久化外部事實;而不是對話、代理或臨時用戶狀態。
  • R3 重建成本高且可重新驗證 — 從實時來源(程式碼、配置、日曆、任務列表)重新推導該聲明的成本將高於維護該頁面的成本。如果一條命令或一次文件讀取就能恢復它,則不應獲得頁面。如果存在外部來源,頁面應命名該來源,以便可以重新驗證新鮮度。純粹的決策和理由是其自身來源,並通過陳述其推理來滿足此條件。

排除條件會覆蓋標準:

  • D1 短暫 — 構建狀態、當前分支、「今天我運行了 X」 -> 操作報告。
  • D2 重複 — 現有頁面已涵蓋 -> 修改現有頁面,而不是創建另一個。

打破平局:如果無法從實時來源重建,則錄取;如果可以重建,則丟棄。wiki/.archive/ 僅用於曾經持久化但現在已被取代的內容。從未持久化的材料不會寫入 wiki,也從不歸檔。

路由矩陣

材料目的地技能路徑
可重複使用的專案/領域事實,通過標準持久化 wiki 頁面loam::adding-to-memory,自我修正
代理行為慣例/命令/注意事項AGENTS.md / CLAUDE.mdloam::learning-from-session 的 guidance 路徑
用於恢復/交接的會話狀態wiki/checkpoints/<slug>.mdloam::checkpointing
附加到工作單元的任務上下文任務註釋 / 計劃文件loam::planning,loam::starting
構建輸出、分支狀態、一次性、無法驗證或標準失敗丟棄,可選添加 log.md 審計行無

自我修正和人類標記觸發

  • 自我修正: 當代理讀取記憶並發現與當前證據矛盾時,將被取代的持久化頁面移動到 wiki/.archive/ 並添加歸檔標頭,在實時位置寫入修正,將 self-correct 條目附加到 log.md,然後繼續原始任務。
  • 人類標記: 當人類說某個記憶頁面錯誤或過時時,將其視為修正觸發,而非批准請求。讀取被標記的頁面和當前證據,歸檔被取代的持久化頁面,寫入修正,記錄日誌,並報告更改了什麼。
  • 歸檔範圍: .archive/ 僅用於那些曾經持久化但後來變得錯誤、過時或被取代的頁面。從未持久化的材料被路由到其他地方或丟棄。

新鮮度驗證觸發

使用現有的 updated_at 加上 lint 時的證據;不要添加新鮮度前置元數據。

  • F1 自頁面 updated_at 以來,引用的文件路徑已更改。
  • F2 重構、重命名、刪除或遷移觸及了引用的路徑(loam::syncing-code-graph --touched)。
  • F3 頁面命名的固定版本、API 或外部文檔有更新的提及。
  • F4 updated_at 超過 90 天,且頁面引用了易變表面,如 API、配置、版本或程式碼路徑。Lint 標記此項以進行重新驗證,不會自動歸檔。
  • F5 讀取時發現矛盾,由自我修正處理。

驗證結果是以下之一:已確認(更新 updated_at)、已修正(歸檔 + 重寫 + 記錄日誌),或已降級(歸檔並附上原因「不再適用」)。

紅旗:意味著 STOP 並調用的想法

這些合理化會導致技能被跳過。如果你發現自己在想其中任何一個,請調用相關技能,即使你「已經在會話中較早時候讀過它」。

想法行動
「我就直接把它寫到 wiki 上」調用 loam-adding-to-memory。應用錄取標準,然後寫入或路由。
「我就規劃一下,這很簡單」調用 loam-writing-spec。在 loam-planning 之前需要規格。
「我就快速在代理之間進行一次辯論」調用 loam-configuring-agents。辯論需要批准才能開始;在批准之前不發送任何內容。
「我就直接編輯這個計劃」調用 loam-amending-plan。計劃更改會產生級聯效應;該技能會分析影響。
「我寫這個記憶頁面是因為它以後可能有用」首先應用錄取標準。如果失敗,則路由或丟棄。
「wiki 過時了,我直接內聯修復」歸檔被取代的持久化頁面,寫入修正,記錄日誌,然後繼續。
「我就把這個學習收穫記下來作為筆記」調用 loam-learning-from-session。它會路由到 wiki 或 guidance,而不是你。
「我就快速檢查一下 wiki」調用 loam-querying-memory。保持基於記憶,而不是過時的上下文。
「我就把這個命令添加到 AGENTS.md」調用 loam-learning-from-session(guidance 路徑)或 loam-auditing-guidance 進行完整審計。
「我就暫停一下,稍後再繼續」調用 loam-checkpointing。檢查點是一個可恢復的工件,而不是心理筆記。
「我從上次中斷的地方繼續」調用 loam-resuming。在行動前驗證實時狀態。
「我來設置 wiki」先調用 loam-scaffolding-wiki,然後調用 loam-initializing-vault 進行 Obsidian 配置。

loam 生命週期

對於任何 loam 任務:

  1. 定位。 從下面的決策圖中識別匹配的技能。如果兩個技能似乎相關,應用優先級規則。
  2. 選擇技能。 通過主機 harness 的 skill loader 調用它。
  3. 保持子層邊界。 不要將檢查點寫入持久化頁面。不要將 guidance 寫入 wiki 頁面。不要將 wiki 內容寫入 AGENTS.md。每個子層都有其技能。
  4. 在記憶寫入之前應用錄取和路由。 持久化 wiki 頁面必須通過標準;其他所有內容都路由到 guidance、檢查點、任務註釋或丟棄。
  5. 僅通過匹配的技能更新計劃/檢查點/guidance。 不要內聯編輯計劃——使用 loam-amending-plan。不要內聯寫入檢查點——使用 loam-checkpointing。不要內聯編輯 AGENTS.md——使用 loam-learning-from-session 或 loam-auditing-guidance。

衝突規則(當兩個技能似乎相關時)

  • 流程/當前工作技能優先於記憶維護技能。 如果你正在執行中並發現記憶問題,先完成當前工作步驟(或對其進行檢查點保存),然後再調用記憶技能。
  • 記憶寫入由代理擁有。 如果當前工作產生了學習收穫,通過矩陣路由;如果暴露了過時記憶,通過歸檔和記錄日誌進行內聯修正。
  • 檢查點是臨時的。 它們位於 wiki/checkpoints/ 下,但不是持久化聲明。它們拒絕更新 index.md 或 log.md。不要將檢查點提升為持久化筆記,除非通過 loam-adding-to-memory。
  • 修改 vs lint。 loam-amending-memory 修復特定的錯誤聲明。loam-linting-memory 健康檢查整個圖。如果你發現了特定錯誤,請修改。如果你想要一般性檢查,請 lint。
  • 查詢 vs 審查。 loam-querying-memory 回答一個問題。loam-reviewing-memory 找出空白。如果你想要答案,請查詢。如果你想知道哪些內容未解決,請審查。
  • 添加 vs 學習。 loam-adding-to-memory 攝取一個來源(文件、文章、作為筆記的對話)。loam-learning-from-session 捕獲會話衍生的見解,並將它們路由到 wiki 或 guidance。如果你有來源,請添加。如果會話產生了見解,請學習。

決策圖

「我想要...」
├─ 開始新的事物
│  ├─ 研究一個問題 ──────────── /loam::writing-spec
│  ├─ 規劃已批准的工作 ────────── /loam::planning
│  └─ 辯論 / 達成共識 ─────── /loam::configuring-agents
├─ 執行工作
│  ├─ 開始一個計劃 ──────────────────── /loam::starting
│  ├─ 暫停 / 交接 ──────────────── /loam::checkpointing
│  ├─ 暫停後恢復 ────────────── /loam::resuming
│  └─ 更改進行中的計劃 ──────── /loam::amending-plan
├─ 處理記憶
│  ├─ 添加來源 ──────────────────── /loam::adding-to-memory
│  ├─ 攝取程式碼庫 ─────────────── /loam::ingesting-codebase
│  ├─ 同步程式碼圖漂移 ────────── /loam::syncing-code-graph
│  ├─ 提出問題 ─────────────────── /loam::querying-memory
│  ├─ 修正錯誤 ─────────────── /loam::amending-memory
│  ├─ 健康檢查 ──────────────────── /loam::linting-memory
│  ├─ 標準化混亂語料庫 ────────── /loam::normalizing-memory
│  ├─ 查看未解決項目 ─────────── /loam::reviewing-memory
│  ├─ 捕獲會話學習成果 ─────── /loam::learning-from-session
│  └─ 審計代理準則 ──────────── /loam::auditing-guidance
└─ 設置子層
   ├─ 搭建 wiki ─────────────── /loam::scaffolding-wiki
   └─ 初始化 Obsidian 倉庫 ───── /loam::initializing-vault

不明確情況下的優先級說明

如果一個意圖映射到兩個技能,上面的樹是主要路由器。當樹無法消除歧義時,應用生命週期部分中的衝突規則。如果仍然不確定:詢問用戶哪個意圖更接近。

精簡技能參考

每個技能一行。決策圖是主要路由器;此處用於快速查找。

  • loam-writing-spec — 研究一個問題,生成 specs/<slug>.md
  • loam-planning — 將已批准的規格編譯成可執行的計劃
  • loam-starting — 開始或恢復執行一個計劃
  • loam-resuming — 從檢查點筆記恢復
  • loam-checkpointing — 在暫停前寫入一個可恢復的檢查點
  • loam-configuring-agents — 在具有不同立場和共識交付物的代理之間運行需批准的結構化辯論或會議
  • loam-amending-plan — 在範圍變更後更新進行中的計劃
  • loam-adding-to-memory — 將一個來源攝取到記憶中(wiki 子層)
  • loam-ingesting-codebase — 將程式碼庫作為具有 wikilink 邊的實體頁面攝取
  • loam-syncing-code-graph — 在計劃門控或按需時將程式碼圖與存儲庫協調
  • loam-querying-memory — 從記憶中回答一個問題
  • loam-amending-memory — 修復特定錯誤或過時的記憶聲明
  • loam-linting-memory — 健康檢查記憶圖
  • loam-normalizing-memory — 將結構改造到混亂的記憶語料庫上
  • loam-reviewing-memory — 找出記憶中未解決的空白
  • loam-learning-from-session — 捕獲會話學習成果,路由到 wiki 或 guidance
  • loam-auditing-guidance — 審計並改進 AGENTS.md / CLAUDE.md / .claude.local.md
  • loam-scaffolding-wiki — 實例化一個新的 wiki 子層 scaffold
  • loam-initializing-vault — 使用配置設置 Obsidian 倉庫

安裝斜杠命令

如果用戶想要 /checkpoint 和 /resume 作為快捷命令(而不是輸入 /loam::checkpointing 和 /loam::resuming),你可以安裝它們。命令文件位於 loam 倉庫的 commands/ 目錄下。

閱讀 references/commands-install.md 以獲取完整協議。 它涵蓋了:

  • 你在哪個 harness 中運行(檢測信號)
  • 你的 harness 期望的命令格式(markdown 與 TOML)
  • 在哪裡安裝(全局與專案本地)
  • 複製前請求許可的協議

命令文件作為資產捆綁在 assets/commands/ 下

…

[為翻譯截斷]

相關技能