agentleFS
tygh89071388tygh89071388/teach-once/.agents/skills/project-capsule/SKILL.md

project-capsule

Skill0 starsChanged 35 days agoMITView on GitHub

為進行中的專案維護一張「專案交接卡」(`memory/long-term/專案/<專案名>/CAPSULE.md`), 記住這個案子目前做到哪、哪些是使用者交代過不能碰的規則、下一次不要重做什麼。當使用者說 「更新專案進度」「這個案子做到哪了」「幫我記一下這個專案」「建立專案卡」「專案交接」 「接手這個專案」「下次繼續這個專案」「我要換台電腦繼續做」「這個專案先停在這裡」時觸發; 或同一個專案跨多次對話進行、準備關掉對話重開、話題橫跨多個檔案與設定時,主動提議建卡。 核心職責:先讀既有卡再更新、只保留目前有效的狀態、把使用者明示過的規則寫進紅線段、 卡片過長時拆檔、更新完重建 qmd 索引。不適用:把日記整理成長期記憶(用 memory-organizer)、 一次性查詢、單檔小修、已結案且不會再碰的專案。不要把密碼、token、憑證寫進卡片。

The file

Files
SKILL.md

Project Capsule(專案交接卡)

解決的問題:新對話一問三不知。日記記得「那天發生什麼」,長期記憶記得「穩定的事實」, 但沒有人記得「這個案子現在做到哪、下一步是什麼、哪些坑已經踩過了」。這張卡就是補那一塊。

這張卡跟日記、長期記憶的分工

檔案誰寫什麼時候寫寫什麼
memory/daily/YYYY-MM-DD.mdhooks 自動每一輪對話結束流水帳:這輪做了什麼,不做判斷
memory/long-term/ 各分類memory-organizer 技能每天排程整理已經穩定下來的事實、教訓、決策
memory/long-term/專案/<專案名>/CAPSULE.md本技能專案有進展時,隨時只有「目前有效」的狀態:做到哪、紅線、下一步

三者不互相取代。日記是原始證據、長期記憶是沉澱結論、交接卡是熱資料——會一直被改寫,只留最新版本。

Step -1:找出記憶根目錄

  1. 若目前專案資料夾裡有 memory/README.md,就用目前專案的 memory/。
  2. 否則用 $HOME/.codex/ai-assistant/memory/。

交接卡一律放在 <記憶根目錄>/long-term/專案/<專案名>/CAPSULE.md。

放在 long-term/ 底下是刻意的:安裝時已經把整個 long-term/ 加進 qmd 的 memory-longterm 索引, 所以卡片寫完並重建索引後,下次開新對話問到相關話題,記憶召回 hook 會自動把這張卡帶回來。 放在別的地方(例如專案根目錄或 daily/)就不會被召回,等於白寫。

Step 0:判斷要不要建卡

該建卡(符合任一項):

  • 同一個專案在不同天、不同對話裡反覆處理
  • 使用者說「先停在這裡」「明天繼續」「換台電腦做」「交接給別人」
  • 這件事牽涉多個檔案、多個設定、或動到權限、資料庫、排程、要重開的服務
  • 下一次對話如果不知道現況,很可能會重做一遍、改錯地方、或漏掉某個必要步驟

不要建卡:

  • 一次性查詢、翻譯、閒聊
  • 只改一個檔案就結束、之後不會再碰
  • 已經結案而且沒有後續風險的事情

判斷不出來時,問使用者一句:「這件事之後還會再處理嗎?要不要我建一張專案卡?」不要自作主張建一堆卡。

Step 1:先讀,再決定新增還是更新

動筆前依序做完:

  1. 讀今天的 memory/daily/YYYY-MM-DD.md,確認這輪實際發生什麼——不要靠對話印象重建。
  2. 檢查 memory/long-term/專案/ 底下有沒有同一個專案的目錄。注意換過名字的情況: 目錄名不同不代表是兩個專案,先看內容講的是不是同一個 repo、同一個網站、同一件事。
  3. 已經有卡就最小更新——只改「目前狀態」那幾段,不要整張重寫。
  4. 沒有卡才建新的。

同一個專案永遠只留一張 CAPSULE.md。不要用日期、「新版」「最終版」另開第二張。

Step 2:卡片必備的段落(順序不能換)

第一次建卡、或不確定某一段該寫什麼時,先完整讀 references/專案卡完整範例.md—— 那裡有一張填好的卡、紅線的正反例,以及「什麼該進卡片、什麼該留日記」的對照表。 範例是虛構資料,只看格式,不要把內容抄進正式記憶。

召回 hook 帶回這張卡時,只會顯示開頭約 8 行、500 字以內的片段,AI 要靠這個片段 決定要不要讀完整份。所以最重要的資訊必須排在最前面,順序固定:

---
description: 一句話說清楚這是什麼專案、目前卡在哪(20-80 字,語意搜尋靠這句命中)
類型: 專案
狀態: 進行中 | 暫停 | 已完成
建立日期: YYYY-MM-DD
最後更新: YYYY-MM-DD
---

# <專案名>

## 一句話
這個專案是什麼、要達成什麼。

## 專案紅線(先讀)
- <使用者明確交代過、違反成本很高的規則,一條一句話>
- <踩過的坑:什麼情況下會出錯 + 該怎麼做>

## 目前定案
- <已經拍板、不要再重新討論的決定>

## 現在做到哪
- <最近 5-8 條進展,一條一句話>

## 重要路徑
- <這個專案會用到的資料夾、檔案、網址、帳號名稱(不寫密碼)>

## 驗證過什麼
- <已經實際測過、確認可用的部分,附上怎麼測的>

## 還沒做完
- <未完成的事,以及卡在哪>

## 下一次不要做什麼
- <已經試過失敗的方向、被否決的方案、不要重複踩的地雷>

## 來源
- daily/YYYY-MM-DD.md — HH:mm:ss [任務或對話] 標題

「專案紅線(先讀)」是這張卡最有價值的一段,位置固定在「一句話」之後、「目前定案」之前。 使用者說過「以後都要這樣」「這個不要再碰」「記住這個規則」的內容,當下就要寫進這一段, 不能只是口頭答應。紅線只放兩種東西:

  1. 使用者明示的長期規則
  2. 已經重複發生過、代價很高的錯誤

一次性的提醒、常識性的做法不要塞進紅線,會把真正重要的規則淹掉。

Step 3:只寫目前有效的狀態

  • 同一件事有新決定時,改寫舊的那一行,不要新舊並列。並列會讓下一次讀卡的人不知道該聽誰的。
  • 被推翻的方案最多留在「下一次不要做什麼」,寫清楚為什麼被推翻。
  • 卡片跟專案裡其他文件(README、規劃檔)講的不一樣時,以卡片為準;同時去那份舊文件開頭加一行 「部分內容已過期,最新狀態見 CAPSULE.md」,不要整份刪掉——歷史有它的價值。
  • 逐個檔案的修改細節、完整的測試輸出、當天的操作流水,不要寫進卡片,那些留在日記裡。

Step 4:卡片太長怎麼辦

卡片是索引,不是施工日誌。目標是能一次讀完——大約 180 行以內。超過的時候:

  1. 把完整的歷史紀錄搬到同目錄的 CHANGELOG.md
  2. 把長篇的操作步驟、事故經過搬到同目錄的 DETAILS.md
  3. 卡片裡只留一行指路:「完整歷程見 CHANGELOG.md」

搬完之後檢查一次:卡片裡還在的內容有沒有少掉關鍵資訊。搬移不是刪除,內容要能對得起來。

Step 5:更新搜尋索引

卡片寫完或改完,一定要重建索引,否則下次對話召回不到,這張卡等於沒寫:

$runtime = if (Test-Path ".\.ai-assistant\qmd") {
    (Resolve-Path ".\.ai-assistant\qmd").Path
} else {
    "$env:USERPROFILE\.codex\ai-assistant\qmd"
}
$env:XDG_CACHE_HOME = Join-Path $runtime "cache"
$env:XDG_CONFIG_HOME = Join-Path $runtime "config"
$env:QMD_CONFIG_DIR = Join-Path (Join-Path $runtime "config") "qmd"
$env:INDEX_PATH = Join-Path (Join-Path (Join-Path $runtime "cache") "qmd") "index.sqlite"
qmd update
if ($LASTEXITCODE -ne 0) { throw "qmd update failed" }
qmd embed -c memory-longterm
if ($LASTEXITCODE -ne 0) { throw "qmd embed failed" }

重建完做一次驗證:用「<專案名> 現在做到哪」這種問法執行

qmd query "<專案名> 目前進度" -c memory-longterm -n 5

命中自己這張卡才算成功。查不到通常是兩個原因:frontmatter 的 description 寫得太籠統, 或索引沒重建成功。

Step 6:跟「整理日記」技能的交接

兩個技能會碰到同一批內容,分工是這樣:

  • 專案還在進行 → 本技能負責,卡片隨時更新,內容可以被改寫
  • 專案告一段落 → 下次跑 memory-organizer(每天排程)時,把卡片裡已經穩定的結論 (最終決策、可重用的教訓、系統設定)萃取到 教訓/、規則/、系統/ 等分類
  • 萃取之後,卡片裡那幾行可以精簡成一行指路,不必兩邊各留一份全文

memory-organizer 不負責即時更新卡片;本技能也不負責週期性整理日記。不要互相代跑。

紅線清單

  • 密碼、token、憑證、私鑰永遠不進卡片——只寫「帳號名稱」「憑證放在哪個管理工具」
  • 不刪除、不改寫原始日記
  • 同一個專案只留一張 CAPSULE.md
  • 使用者說「以後都要這樣」時,當下就寫進紅線段,不能只口頭答應
  • 目錄名不同不代表是兩個專案;沒合併內容前不要刪掉任何一張舊卡

完成前逐項驗收

  • 已經讀過今天的日記與既有卡片,不是憑印象寫的
  • 卡片段落順序正確,「專案紅線(先讀)」在第二段
  • frontmatter 的 description 是一句具體的話,不是「某某專案的記錄」這種空話
  • 同一件事沒有新舊兩種說法並存
  • 卡片裡沒有密碼、token 或任何憑證明文
  • 每條重要進展都能在「來源」段找到對應的日記日期
  • 使用者這次交代過的規則已經寫進紅線段
  • 卡片在 180 行以內;超過的部分已經搬到 CHANGELOG.md 或 DETAILS.md
  • qmd update 與 qmd embed -c memory-longterm 都成功
  • 用「<專案名> 目前進度」查詢,確實命中這張卡

建議節奏

  • 專案有進展時:當下更新卡片,一次改幾行就好
  • 準備關掉對話前:花一分鐘把「現在做到哪」「下一步」補完整
  • 每天排程整理時:跑 memory-organizer 時順手檢查卡片,把已經穩定的結論搬去長期記憶
  • 專案結案:狀態改成「已完成」,把可重用的教訓萃取出去,卡片本身留著當歷史

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.