project-registry 是做什麼的？

EN — 一套 Claude Code 技能，用於管理個人專案登錄檔 (~/projects/PROJECTS.json) 以及每個專案的 AI 可讀開發日誌 (CLAUDE.md)：從一個選單即可進行列出、創建、刪除、儲存、工作階段恢復、決策歸因、健康檢查與版本回退。UI 文字以中文優先，但觸發詞同時支援中文與英文，且所有功能無論語言皆可完整運作（AI 理解兩種語言）。安裝指令：npx skills add SUNQSHENG/project-registry 或 /plugin marketplace add SUNQSHENG/project-registry。

概述

管理 ~/projects/PROJECTS.json 所註冊的專案清單，提供專案的增刪改查與統計功能。專案以 <key>/ 子目錄形式存放在 ~/projects/ 下，每個專案包含 README.md 記錄背景與範疇。

操作專案時會自動 cd 到對應的專案目錄。

資料來源

~/projects/
  PROJECTS.json    # 專案註冊清單（唯一權威來源）
  <key>/           # 專案目錄
    README.md      # 專案背景與範疇說明（面向人類）
    CLAUDE.md      # 專案開發記錄（面向 AI，每次對話自動載入）

所有專案必須存放在 ~/projects/ 目錄下。

區別： README.md 給開發者/協作者查看專案概況；CLAUDE.md 給 AI 看，記錄開發過程中的決策、狀態、上下文，確保長期專案不遺失資訊。

PROJECTS.json 結構

{
  "description": "專案清單 — 所有專案在此登記",
  "updated": "2026-03-01",
  "nextSeq": 3,
  "projects": [
    {
      "seq": 1,
      "key": "pet_hospital_crm_20260301",
      "name": "寵物醫院CRM",
      "status": "已完成",
      "created": "2026-03-01"
    }
  ]
}

操作入口

每次進入技能時，請先 cd ~ 回到使用者根目錄，然後讀取 PROJECTS.json 並顯示清單與精簡選單（不做目錄層級檢測）：

📋 目前專案清單（共 N 個）
┌─────┬──────────────────────────────┬─────────────────┬──────────────────────┬──────────┬────────────┐
│ 序號 │ key                          │ 名稱             │ 狀態                 │ 建立日期   │
├─────┼──────────────────────────────┼─────────────────┼──────────────────────┼──────────┼────────────┤
│ 1   │ pet_hospital_crm_20260301    │ 寵物醫院CRM      │ ✅ 已完成            │ 2026-03-01 │
│ 2   │ gym_members_app_20260315     │ 健身房會員App    │ 🔄 進行中            │ 2026-03-15 │
└─────┴──────────────────────────────┴─────────────────┴──────────────────────┴──────────┴────────────┘

> 初始顯示不做目錄檢測，僅讀 JSON。目錄狀態在 MD檢查 時批次檢測。

請選擇操作（或直接說需求）：
 - 輸入專案**序號**（1-99）→ 開啟對應專案（如 12）
 - 🆕 N. 新建專案
 - 🗑️ D. 刪除專案
 - 🔍 C. MD檢查（批次檢測所有專案）

> 其他需求（修改/搜尋/統計/更新記錄/儲存/退出/**檢查專案**/**為什麼 XX**）直接在對話中說即可
> ⚠️ **儲存/退出時會自動更新 CLAUDE.md**（強制規則）

⚙️ 首次配置引導（API Key 可選）

第一次進入技能時：

檢查環境變數 PR_API_BASE_URL / PR_API_KEY / PR_API_MODEL 是否已設定（printenv）
未設定 → AskUserQuestion 卡片詢問：「是否設定 API Key 以啟用自動摘要儲存？」
- 設定（推薦） → 引導設定三個環境變數（README 中有各提供者範例：DeepSeek / OpenAI / 通義 / Ollama 本地）
- 跳過 → 寫入 <skill 目錄>/config.json（記錄「已跳過」，後續不再詢問）
- 了解更多 → 顯示功能對比表
設定後立即生效（無需重啟對話）

功能對比：

能力	不配 Key	配 Key
資料安全（秒級備份 + 對話結束自動提交）	✅	✅
全部核心功能（登錄表/對話恢復/歸因/回滾/檢查）	✅	✅
自動摘要（對話自動提煉 → CLAUDE.md 即時更新）	❌	✅

隨時說「設定 API」即可重新引導。

🔍 自動識別目前專案

每次進入技能時已自動 cd ~。需要定位專案的操作（檢測/修改/儲存/更新記錄等）會自動識別目前目錄：

1. pwd 檢查是否匹配 ~/projects/<key>/
2. 匹配 → 自動選定該專案
3. 不匹配 → 手動選擇（按序號或 key）

🧭 對話開始流程（上下文恢復）

僅對「進入專案工作」類操作觸發：開啟專案 / 檢測 / 修改 / 更新記錄 / 儲存 / 退出。查看詳情、搜尋、統計等輕量操作不觸發。

進入專案後、執行操作前，先回顧上下文再接續（防止長期專案資訊遺失、中斷後重新進入不知從何開始）：

讀取該專案的 CLAUDE.md（若存在）
摘要上次進度：引用「目前狀態 / 最新進展」，必要時結合 git log 最近提交
列出「下一步行動」（按優先級 1. 2. 3. …）
詢問使用者從哪項繼續（用 AskUserQuestion 卡片呈現下一步行動選項），確認後再操作

範例話術（卡片下方附註）：

📌 上次進度摘要：專案初始化完成，登錄表已建立
➡️ 下一步行動（按優先級）：
  1. 完成需求文件
  2. 補充待辦清單
從哪項繼續？

新專案（CLAUDE.md 剛建立）可跳過回顧，直接進入操作。

📂 開啟專案

按序號或 key 定位專案 → 驗證 ~/projects/<key>/ 目錄存在
cd 到專案目錄
觸發「🧭 對話開始流程」（回顧上次進度 → 確認續接）
使用者在專案內開始工作後，按需操作（修改/更新記錄/儲存/退出）

操作詳情

📌 互動規則（強制）：所有需要使用者「是/否」或「多選一」的詢問，必須使用 AskUserQuestion 工具以選項卡片呈現（兩個及以上選項按鈕），禁止用純文字提問。適用場景：是否引入 grill-with-docs、是否建立文件骨架、專案類型確認、key/背景確認（按建議 or 修改）、刪除確認、對話續接選擇（從哪項繼續）等。

🆕 新建專案

詢問專案名稱 + 背景說明，生成 key：<英文縮寫>_<YYYYMMDD>
備份 PROJECTS.json → 建立目錄 → 寫入 README.md + CLAUDE.md + .gitignore（含 PROJECTS.json、backups/、*.bak、.memory/）
註冊到 PROJECTS.json（seq = nextSeq，之後 nextSeq +1）
cd 到專案目錄，執行 git init
必須詢問是否引入 grill-with-docs 技能（AskUserQuestion 卡片：引入 / 不引入）：
- 同意 → 落實三個動作（非口頭「已引入」）： ① CLAUDE.md「依賴關係」表記錄：| grill-with-docs | 引入 | 設計拷問流程（需使用者手動呼叫 /grill-with-docs）| ② 初始待辦頂部加一條提醒（標註「手動」，非可執行任務）： - [ ] 📌 提醒（手動）：設計/規劃時輸入 /grill-with-docs 啟動拷問（該 skill 僅限使用者手動呼叫，AI 無法代為啟動） ③ 明確告知使用者呼叫方式：「首次設計/規劃時手動輸入 /grill-with-docs」
- 拒絕 → 不記錄、不加入待辦，正常繼續
程式碼/工程類專案：詢問是否建立可選文件骨架（AskUserQuestion 卡片：建立 / 跳過；見「📁 可選文件骨架」）；業務/文件類專案跳過

CLAUDE.md 初始範本請見底部。

🗑️ 刪除專案

定位專案 → 列出 JSON 條目 + 目錄檔案清單 → 標註不可逆風險
使用者確認後：備份 PROJECTS.json → 刪除 JSON 條目 → 刪除專案目錄 → 剩餘專案從 1 連續重新編號 → nextSeq = max(seq) + 1

💾 儲存專案

備份 CLAUDE.md（到 <skill 目錄>/backups/，即 ~/.claude/skills/project-registry/backups/）
回顧本次對話，將以下內容追加或更新到 CLAUDE.md：
- 最新進展與完成事項
- 新增的架構決策（日常決策按「📜 決策記錄紀律」格式補錄，原因不可省略）
- 更新待辦清單（已完成項目標記 ✅，新增項目添加）
- 更新已知問題
- ⚠️ 「下一步行動」必須按優先級列出（1. 2. 3.），不可省略（下次對話從此處續接）
提交 CLAUDE.md 變更到 git
建議下一步工具：根據專案內容與待辦，提示可能用到的技能（如 ppt-master / docx / xlsx / pdf 等），供使用者決定
儲存後不退出，留在目前目錄

⚠️ CLAUDE.md 自動更新是強制規則，不可跳過。

🚪 退出專案

同儲存操作，但最後一步退回 ~：

備份 CLAUDE.md
回顧本次對話更新 CLAUDE.md（含「下一步行動」按優先級）
提交變更到 git
建議下一步工具（同儲存流程）
退出後直接退回 ~

🔍 MD檢查（批次檢測所有專案 CLAUDE.md 狀態）

對所有已註冊專案批次檢查 CLAUDE.md 是否有效（無需手動選擇）：

遍歷所有專案目錄，檢查以下 3 項：
- 目錄是否存在
- CLAUDE.md 是否存在
- .git 是否存在（CLAUDE.md 生效前提：必須與 .git 同級）
輸出彙總表格：

🔍 MD 健康檢查（共 N 個專案）
┌─────┬─────────────────────────────┬─────────────────┬──────────┬──────────┬──────────┬──────────┐
│ 序號 │ key                         │ 專案名稱         │ 目錄存在  │ CLAUDE.md│ .git     │ 有效?   │
├─────┼─────────────────────────────┼─────────────────┼──────────┼──────────┼──────────┼──────────┤
│ 1   │ pet_hospital_crm_20260301   │ 寵物醫院CRM      │ ✅       │ ✅       │ ✅       │ ✅      │
│ 2   │ gym_members_app_20260315    │ 健身房會員App    │ ✅       │ ✅       │ ✅       │ ✅      │
│ ... │ ...                         │ ...              │ ...      │ ...      │ ...      │ ...      │
└─────┴─────────────────────────────┴─────────────────┴──────────┴──────────┴──────────┴──────────┘

針對「有效?」為 ❌ 的專案，逐個定位問題：
- 目錄不存在 → 檢查 JSON 註冊是否有殘留
- CLAUDE.md 缺失 → 用範本補建立
- .git 缺失 → 執行 git init
自動 cd 到使用者根目錄（不進入具體專案）

📁 可選文件骨架（程式碼/工程類專案）

新建程式碼類專案時詢問是否建立（業務/文件類專案跳過）。建立後與 CLAUDE.md 分工：CLAUDE.md 記錄狀態與決策，骨架文件記錄設計細節：

<專案目錄>/
├── CLAUDE.md              # 開發記錄（狀態/決策/待辦）
└── docs/
    ├── ARCHITECTURE.md    # 整體架構說明（可選）
    ├── adr/               # 架構決策記錄（可選，與 grill-with-docs/domain-modeling 的 ADR 輸出銜接）
    └── dev/
        ├── README.md      # 功能索引
        └── <feature>/
            ├── SPEC.md    # 功能規格
            └── DESIGN.md  # 實現設計

輕量原則：僅在使用者確認時建立，不強制、不預設。 與 grill-with-docs 銜接：grill-with-docs（拷問+術語+ADR）是設計流程，骨架是落盤結構——先拷問清楚，再按骨架儲存。分工：輕決策記入 CLAUDE.md「架構決策記錄」（一行式）；難逆轉、有真實權衡的決策落 docs/adr/；術語表 CONTEXT.md 由 domain-modeling 專屬維護，骨架不重複建立。

自動 cd + CLAUDE.md 自動更新

操作	cd	CLAUDE.md 自動更新
新建	進入專案目錄	✅ 自動建立初始範本
檢測/修改	進入專案目錄	❌ 不自動更新
更新記錄	進入專案目錄	✅ 手動觸發更新
儲存	進入專案目錄，儲存後不退出，留在目錄	✅ 自動更新
退出/返回	先更新 CLAUDE.md，再退回 `~`	✅ 自動更新

安全機制

PROJECTS.json 寫操作（新建、修改、刪除）必須先備份：

備份路徑：<skill 目錄>/backups/（即 ~/.claude/skills/<skill-name>/backups/）
備份檔案：PROJECTS.json.<YYYYMMDD_HHMMSS>.bak

CLAUDE.md 寫操作（更新記錄、儲存時自動更新）必須先備份：

備份路徑：<skill 目錄>/backups/
備份檔案：CLAUDE.md.<YYYYMMDD_HHMMSS>.bak

如果備份目錄不存在，自動建立。

備份自動輪轉：

每次新建備份後，按檔案類型清理舊備份，每種類型保留最近 10 份：

備份類型前綴：
  PROJECTS.json.*.bak    # 專案清單備份，保留 10 份
  CLAUDE.md.*.bak        # 開發記錄備份，保留 10 份
  SKILL.md.*.bak         # 本 skill 自身備份，保留 10 份

清理規則：按檔案名稱末尾的 YYYYMMDD_HHMMSS 提取時間戳排序（注意：CLAUDE.md.<專案名>.<時間戳>.bak 這類特殊命名的備份，時間戳在末尾，不能用整名字串排序），保留最晚的 10 份，其餘刪除。

🔁 自動儲存（hooks，靜默執行）

兩層機制，全部後台靜默、失敗靜默重試、只在 ~/projects/ 專案目錄生效。

層 1 機械快照（零依賴，預設開啟）

Hook	動作
Stop（每次回應後）	transcript 同步到 `<專案>/.memory/transcript-latest.jsonl`（秒級）
SessionEnd（對話結束）	CLAUDE.md 備份（10 份輪轉）+ git 提交（有變更才提交）

⚠️ 隱私：.memory/ 含對話原文——必須 gitignore 排除（新建專案自動產生 .gitignore 含 .memory/），絕不進倉庫
強制關閉終端時 SessionEnd 不觸發，但 Stop 的秒級同步仍在——資料不遺失

層 3 自動摘要（可選，設定 API 後啟用）

觸發：節流控制（≥10 條新訊息或 ≥10 分鐘）——不每次回應都呼叫 API
流程：讀 .memory/ 增量 → 呼叫 PR_API_BASE_URL（任意 OpenAI 相容供應商）→ 提取進展/決策/待辦/下一步 → 合併更新 CLAUDE.md（追加決策/更新進展/待辦/下一步）
設定（環境變數）：PR_API_BASE_URL / PR_API_KEY / PR_API_MODEL（不設定自動跳過）
隱私：對話只發送到使用者自己設定的端點；key 從環境變數讀取，永不硬編碼

與手動儲存的關係

自動摘要 = 即時保鮮（增量合併）；手動儲存 = 權威整理（全面回顧）——兩者相容互補。

📜 決策記錄紀律（查必有據）

所有決策必須可回溯：「為什麼這麼做」永遠可查，原因不可省略。

輕決策格式

- [狀態] YYYY-MM-DD — <決策>（原因：<理由>）（預期：<效果>）

狀態標記：✅已執行 / 🔄進行中 / ⛔被推翻 / ⏸️擱置
原因強制：無原因不上記錄
預期可選：記錄時已知預期效果則補上（歸因時用於驗證效果）

記錄時機（分層）

類型	時機
重大決策（影響方向 / 難逆轉 / 消耗資源）	對話中即時確認：Claude 主動詢問「這條記入決策記錄嗎？」
日常決策	儲存/退出時統一回顧補錄（強制）

重決策 → ADR

難逆轉、有真實權衡的決策落 docs/adr/，CLAUDE.md 留一行索引：

- 2026-08-08 — ADR-0001 <決策標題>（狀態：✅已執行）

ADR 結構：# ADR-000N <標題> + Status / Date / Context / Decision / Consequences。

CLAUDE.md 初始範本

# <專案名稱>

## 專案目標
<背景說明摘要>

## 技術棧
（待補充 — 語言/框架/資料庫/部署等）

## 目前狀態
state: active
- 階段：需求分析 / 開發中 / 已完成
- 最新進展：專案初始化

## 架構決策記錄
記錄所有重要決策，格式：
- [狀態] YYYY-MM-DD — <決策>（原因：<理由>）（預期：<效果>）
（狀態：✅已執行 / 🔄進行中 / ⛔被推翻 / ⏸️擱置；原因不可省略，預期可選）

## 專案範疇與功能
（核心功能清單，也可用表格呈現）

## 依賴關係
| 依賴專案 | 關係 | 說明 |
|:---|:---|:---|
| <專案名> | 依賴/被依賴 | <具體說明> |

## 待辦
- [ ] 待辦事項 1（細化到可執行的粒度）

## 已知問題
- （暫無 — 發現後補充，含影響範圍）

## 下一步行動
- 按優先級列出（1. 2. 3.），儲存/退出時強制更新

新建時至少填充：專案目標、技術棧、目前狀態、待辦前三項。其餘在開發過程中逐步豐富。

key 命名規則

<英文/拼音縮寫>_<YYYYMMDD>

範例:
  寵物醫院CRM      → pet_hospital_crm_20260301
  健身房會員App    → gym_members_app_20260315

英文優先，拼音備選
全小寫，底線分隔
尾部加日期

序號管理規則

操作	規則
新建	讀取 `nextSeq` 作為新專案的 seq，註冊後 `nextSeq` +1
刪除	刪除後剩餘專案從 1 開始連續重新編號，`nextSeq` 設為 `max(seq) + 1`
seq	始終連續，永不跳號

🧠 記憶管理（三層機制）

專案級記憶（skill 管理）

記憶載體	記什麼	管理機制
CLAUDE.md	狀態 / 決策及原因 / 待辦 / 已知問題 / 下一步行動	每次對話自動載入 + 儲存強制更新 + git 提交 + 備份輪轉
PROJECTS.json	專案註冊清單（seq/key/name/status/created）	寫操作前備份
git 歷史 + backups/	歷史版本快照	任意時刻可回溯（`git show` / 備份檔案）

記憶生命週期

寫入（儲存/退出強制更新）
  → 自動載入（每次對話 Claude Code 自動注入 CLAUDE.md）
  → 備份（10 份輪轉 + git 提交）
  → 檢索（讀 CLAUDE.md / 歸因調查「為什麼 X」/ git 歷史回溯）

記憶邊界

不記錄：詳細程式碼實現 | git 可回溯的變更 | 臨時性討論（對話原文不存檔——查「當時具體聊了什麼」用 Claude Code 自帶對話存檔 --resume，不在本 skill 職責內）

與全域記憶的分工

專案相關（進展/決策/為什麼這麼定）→ 本 skill 記憶（CLAUDE.md，跟著專案走）
使用者偏好/跨專案事實（如「PPT 優先使用 ppt-master」）→ Claude Code 全域記憶（~/.claude/.../memory/，由系統維護，skill 不寫）

CLAUDE.md 維護

CLAUDE.md 是 Claude 每次對話自動載入的專案上下文檔案，記錄決策與進展。

更新時機（強制規則）： 新建時自動生成 | 每次對話結束呼叫「更新記錄」 | 關鍵決策時追加 | 需求變更時同步 | ⚠️ 退出或儲存時自動執行更新（必須執行，不可跳過），且「下一步行動」按優先級寫出

不記錄： 詳細程式碼實現 | git 可回溯的變更 | 臨時性討論

生效條件： 必須和 .git 同級，檔名 CLAUDE.md（全大寫）

新建專案時自動 git init。已有目錄無 .git 時，告知原因並詢問是否要 git init。

🔎 歸因調查（為什麼 X）

使用者說「為什麼 X / 這個決策的背景 / 當時為什麼這麼做 / 歸因 X」時觸發。

流程：

定位：確認調查對象（專案 + 主題/時間點）
取證：讀取該專案 CLAUDE.md「架構決策記錄」+ docs/adr/（若存在）+ git log 最近提交 + 進展/待辦
輸出歸因報告：
- 決策時間線：相關決策按時間排列
- 原因鏈：每個決策的理由 + 決策間關聯（哪個決策基於哪個）
- 狀態：✅已執行 / 🔄進行中 / ⛔被推翻 / ⏸️擱置
- 後續影響：結合最新進展判斷預期是否達成
結論：回答「當時為什麼這麼做」，必要時指出預期是否被驗證

輸出在對話內；要求存檔時落盤到倉庫外（~/project-audit-logs/）——檢查/歸因內容含專案隱私，禁止寫入專案倉庫。

📋 專案檢查（自然語言觸發，不佔選單）

使用者說「檢查專案 / 體檢 / audit」時觸發，選單不新增項目。

全部掃描（「檢查所有專案」）

結構檢查（同 MD檢查 C）+ 內容 5 項：

#	維度	檢查邏輯
1	狀態一致性	PROJECTS.json 的 status vs CLAUDE.md 最新進展/待辦是否矛盾
2	專案停滯	CLAUDE.md 最近更新（git log 時間）距今 > 14 天 → 「可能停滯」
3	待辦堆積	未完成待辦超 10 項或長期無進展
4	決策未落地	決策記錄標 ✅已執行但進展/待辦無體現
5	下一步缺失	無「下一步行動」章節（儲存流程偷懶）

異常項目自動帶歸因線索：回溯最近 N 條決策，指出哪些決策可能相關。

單專案深查（「檢查 XX 專案」）

內容 5 項，只查指定專案。

報告只在對話內輸出；要求落盤時存到 ~/project-audit-logs/（倉庫外）。

↩️ 版本回退

使用者說「回退 / 恢復版本 / 退回 / 撤銷儲存」時觸發。雙通道：git 歷史（專案檔案）+ 備份快照（登錄表/開發記錄）。

通用安全規則（所有回退必須遵守）：

先備份目前版本（回退本身可回退）
必須顯示差異摘要 + AskUserQuestion 卡片確認（回退 / 取消）後才動手
回退產生新提交，不改寫 git 歷史

① CLAUDE.md 回退（開發記錄誤改/誤刪）

定位：git log --oneline 列出最近提交（或 backups/CLAUDE.md.*.bak 檔案名稱時間戳）
對比：git show <commit>:CLAUDE.md 與當前版本的差異（重點：決策/待辦/下一步行動）
確認：顯示差異摘要 → 卡片確認
執行：備份當前版 → git checkout <commit> -- CLAUDE.md → 提交（記錄「回退到」）
彙報：回退內容摘要

② 專案檔案回退（README/docs/程式碼）

定位：git log 找目標版本
對比：git diff <commit> -- <檔案>
確認：差異摘要 → 卡片確認
執行：備份當前版 → git checkout <commit> -- <檔案> → 提交
彙報

③ 登錄表回退（PROJECTS.json 誤刪/誤改）

定位：backups/PROJECTS.json.<時間戳>.bak（最近 10 份，按末尾時間戳排序）
對比：當前 vs 備份 diff（列出專案增減）
確認：差異摘要 → 卡片確認
執行：備份當前版 → cp 備份 → PROJECTS.json → 驗證（專案數/seq 連續性）
彙報

提示：回退與「🔎 歸因調查」搭配——先查「為什麼變成這樣」，再決定回退到哪個版本。

常見問題

PROJECTS.json 不存在：用預設範本建立空白清單
目錄已存在：複用現有目錄，僅註冊 JSON
刪除時找不到專案：先列出清單讓使用者確認

在你喜歡的 AI 中提問

說明文件