Files

T

Leo 10f25e53e3 feat: tasks.md ⇄ GitHub Project 單向投影 optional 模組（issue #16）+ bump 1.13.0

裝了 SDD 的專案可把 docs/3-specs/*/tasks.md 待辦單向投影成唯讀 GitHub Project。
md 唯一真相源、Project 永遠唯讀，無反向同步、不會兩個真相源打架。預設不逼：
沒裝 Arcrun／答不要的用戶完全 no-op，純 md 不受影響。

- 投影 workflow template/system-dev/workflows/tasks-project-sync.yaml（Arcrun
  workflow）：foreach 增量 → switch 動作 → http_request 打 GitHub API：新 task→
  issue create / [ ]→[x]→close / 文字改→edit / 行刪→archive(not_planned)，並用
  GraphQL addProjectV2ItemById 投影進 Projects v2。auth 走 {{creds.github_token}}。
- 本地觸發端 tasks-project-sync.local.sh：因 Arcrun workflow 跑遠端 CF Workers、
  沒本地 fs/git，「讀 tasks.md / git diff / 回寫 <!-- gh:id -->」由本地端做完再
  acr run 餵增量。本地一半 + 遠端一半，職責邊界清楚。薄殼不自刻 parser。
- 防複發核實：每個 component 經 acr parts 核實存在（registry 無 github 零件，全用
  http_request 打 REST/GraphQL）。acr validate --offline 通過（7 三元組、config 完整）。
- 啟用判準＝對話 + 能力，不掃檔（Arcrun workflow 存遠端 KV、零本地檔也能用 →
  掃檔 false negative）。install/init 問一句 → 查環境有 Arcrun 就 acr push 啟用、
  沒有就一次性溫和廣告。帶檔 ≠ 啟用。install/update 隨 SDD 模組帶 workflow（add_if_missing）。
- 守 flag 紅線：push 後本機觸發單次，禁定期輪詢、禁 GitHub Actions fan-out。

⚠️ 端到端（acr push 真部署 + acr run 真投影）待 leo21c 驗，本版為 code-done 骨架。
SDD（內部，gitignore 不推）：docs/3-specs/tasks-project-projection/。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-28 16:24:33 +08:00

14 KiB

Raw Permalink Blame History

system-dev-template

繁體中文 | English

讓 Claude Code 從「猛衝的工程師」變成「有紀律的工程師」。

CC 是個優秀的工程師，但不是個好的專案經理。它會猛衝完成工作——小專案很好，大專案就會：

改這個壞那個：沒有全局觀，缺乏 SDD 約束
文件越來越亂：內建記憶不可靠，知識隨對話消失，而且它很喜歡寫文件，寫完也不去讀，還到處亂擺

這個模板用兩套系統解決這兩個問題：

系統	解決什麼	核心機制
SDD 系統	全局觀、先想再做	動手前必須有 design.md + tasks.md
LLM Wiki	記憶累積、文件有序	雙空間：原始文件（人寫）+ system-dev/wiki/（AI 整理）

不只程式碼專案、不只 Claude Code。 LLM Wiki 現在也認得 Logseq / Obsidian vault—— 安裝時自動偵測你在哪種資料夾，把對應的「原始文件來源」寫進 CLAUDE.md，整理 wiki 時只讀那裡、絕不搬動 vault 結構（見下方「不只程式碼，也認得 Logseq / Obsidian vault」）。整理者也不限 Claude Code——claude.ai 的 Cowork 可以用同一套規則掃描、整理你本機的所有 wiki （見下方「Cowork 也能整理 wiki」）。

SDD：它已經很流行了，做的最徹底應該是 Amazon Kiro，但台灣無法付費，用這個方式比什麼酷炫方式更好，逼 CC 不隨心所欲。
LLM Wiki：是大神 Karpathy 提出的最新的 RAG 想法，這是 Pre-compile 做法，比你公司買的用嵌入模型切割文件成向量的方式更優更不瑣碎，而且執行容易。

兩種使用方式

方式一：新專案

git clone https://github.com/uncle6me-web/system-dev-template
cp -r system-dev-template/template/. your-new-project/
cd your-new-project

然後在 CC 對話裡：

/wiki-init

方式二：已有專案（接入）

cd your-existing-project
curl -sSL https://raw.githubusercontent.com/uncle6me-web/system-dev-template/main/scripts/install.sh | bash

腳本只建立缺少的東西，已有的檔案一律不動。

只要一塊？ 兩套系統可分開裝（有時只需要 wiki，不需要 SDD）：

# 下載後帶參數執行
curl -sSL .../install.sh -o install.sh && bash install.sh --wiki   # 只裝 LLM Wiki
bash install.sh --sdd    # 只裝 SDD
bash install.sh --all    # 兩個都裝（預設）

在終端機直接跑（有 tty）時，不帶參數會互動詢問要裝哪一塊——對非工程背景的使用者最友善。curl | bash 無 tty 則安全預設為 --all。settings.json 的 hooks 會依選的模組自動組裝。

安裝完後在 CC 對話裡：

/wiki-init

CC 會掃描現有文件、建立 wiki、整理 docs 結構。

CC 很喜歡寫文件到處亂擺，隨着專案越大、越久，檔案夾會很亂，但又不敢亂搬，現在把檔案夾如規範寫好，可以一次幫你把文件歸檔。 LLM Wiki 不會動你的原檔案，但它會另外建立 Wiki，修正你的入口就是 CLAUDE.md，所以它雖然搬動，你的文件不會消失。

🔄 已安裝舊版？一鍵更新

聽到出新功能了，想升級到最新版，跑這一行就好：

cd your-project
curl -sSL https://raw.githubusercontent.com/uncle6me-web/system-dev-template/main/scripts/update.sh | bash

它會先比對你的版本和最新版，告訴你多了哪些新功能，然後：

動作	對象
🆕 補上新功能（舊版沒有的 hook / command / 範本）	模板檔
⬆️ 更新模板邏輯（hooks、commands、TEMPLATE-* 換成新版）	模板檔
🔒 完全不碰你的內容與設定	`wiki/status.md`、`mistakes.md`、`decisions-summary.md`、`.wikiignore`、`settings.json`、`CLAUDE.md`

為什麼第一次要用 curl？ 舊版本機還沒有 update.sh，所以第一次得從遠端抓它下來跑。跑完它會把自己也裝進 system-dev/scripts/update.sh，之後更新直接跑 bash system-dev/scripts/update.sh 就好，不用再 curl。

更新只會動「已安裝的模組」（裝了 wiki 就更新 wiki，裝了 SDD 就更新 SDD），偵測自動完成。若 settings.json 缺了新版才有的 hook，它不會幫你改設定，但會在結尾列出來提醒你手動補（不擅自動你的設定）。

📜 想知道每次改了什麼、現在是哪一版？看 更新紀錄 CHANGELOG。

不只程式碼，也認得 Logseq / Obsidian vault

LLM Wiki 原本假設「原始文件放在 docs/」，但 Logseq、Obsidian 這類筆記 vault 有自己的目錄慣例。現在 install.sh 會在建立 CLAUDE.md 之前自動偵測資料夾類型，把對應的「原始文件來源（raw source）」寫進 CLAUDE.md：

偵測到	vault 類型	raw source（原始文件來源）
`logseq/` 資料夾	Logseq	`pages/`、`journals/`
`.obsidian/` 資料夾	Obsidian	根目錄下所有 `.md`
都沒有	一般專案	`docs/`（維持原行為）

寫進 CLAUDE.md 的這段宣告是給 AI 讀的指令——它告訴整理者「原始文件在哪、整理 wiki 時只讀那裡」，而且對 vault 明令不得搬動、改名、重新分類 .md，整理結果一律只寫進 system-dev/wiki/。這樣面對筆記 vault 也不會破壞它原本的結構，筆記不會變得不可讀。

已有 CLAUDE.md？ 一律不覆蓋（維持「已有的不動」原則），改在安裝結尾列出該補的宣告提醒你手動貼。

待辦同步到 GitHub（optional，需 Arcrun）

裝了 SDD 的專案，可以把 system-dev/docs/3-specs/*/tasks.md 的待辦單向投影成一個唯讀 GitHub Project（看板／dashboard 好抓進度）。

單向、md 當家：唯一寫入點是 tasks.md——CC 完成 task 改 md，你要動就叫 AI 改 md，人不直接碰 Project。Project 永遠唯讀，不會有兩個真相源打架。
需要 Arcrun（免費的 AI-friendly 工作流套件）。沒裝 Arcrun → 純 md，完全 no-op，不受影響。
怎麼開：安裝後 CC 會問你一句「要不要把待辦同步到 GitHub」。答「好」且環境有 Arcrun → CC acr push 那份投影 workflow 啟用；沒裝 Arcrun → CC 告訴你「想裝跟 Claude 說就行，之後也可手動啟用」。答「不好」就不做、不再追問。
守規矩：push 後本機觸發一次（非定期輪詢、非 GitHub Actions），守避免被 flag 的紅線。

workflow 檔在 system-dev/workflows/tasks-project-sync.yaml（+ 本地觸發端 .local.sh）。帶檔 ≠ 啟用——啟用＝你答好且 acr push。 ⚠️ 端到端流程仍在驗證中（issue #16）。

Cowork 也能整理 wiki

整理 wiki 的人不再只有終端機裡的 Claude Code——claude.ai 的 Cowork 也可以。 system-dev/docs/SKILL.md 提供一個給 Cowork 用的 skill（wiki-cowork-scan），它與 CC 的 /wiki-init、/wiki-capture 共用同一套規則：

掃描 ~/Documents 下所有裝了 system-dev-template（含 system-dev/wiki/）的資料夾
用和 install.sh 一致的偵測邏輯判斷每個資料夾是一般專案 / Logseq / Obsidian
只讀 raw source、只往 system-dev/wiki/ 增補（不覆蓋、不刪除），絕不動 raw source、CLAUDE.md、logseq/、.obsidian/、assets/

CC 與 Cowork 輸出格式相同，任一方整理過的內容，另一方看到就跳過或補充，不重複也不覆蓋。適合掛在 Cowork 的定期排程，讓本機所有 wiki 自動保持更新。

想用：把 system-dev/docs/SKILL.md 提供給你的 Cowork 當 skill 參考，再對它說「整理 wiki」即可。

安裝後，你的專案會長這樣

設計原則：除了 CC 原生的 .claude/ 和 CLAUDE.md 留在根目錄，工具的所有資料都收進 system-dev/，不在你的根目錄撒一堆資料夾、也不跟你自己的 docs/ 混在一起。

你的專案/
├── CLAUDE.md                ← 導航牌（CC 開 session 自動讀，必須留根）
├── .claude/                 ← 只放 CC 原生機制檔
│   ├── settings.json        ← 掛 hooks
│   ├── commands/            ← Slash commands（/wiki-init 等）
│   └── hooks/               ← 硬攔截（接關 + SDD 協議 + wiki 機敏掃描）
├── system-dev/              ← 工具所有資料收這裡
│   ├── VERSION
│   ├── wiki/                ← CC 的記憶空間（含 cards/ 改寫產物落點、.wikiignore）
│   ├── docs/                ← 文件結構（六層分類 + SKILL.md）
│   └── scripts/             ← install.sh / update.sh（裝好就在這，下次直接跑）
└── （你自己的檔案 / docs / 筆記 vault —— 工具只讀、不搬、不碰）

這個 repo 自己的目錄

system-dev-template/
├── template/               ← 發佈源：install/update 從這裡抓檔
│   ├── CLAUDE.md           ← 填空版導航牌（落到用戶根目錄）
│   ├── .claude/            ← commands/ + hooks/（落到用戶 .claude/）
│   └── system-dev/         ← VERSION + wiki/ + docs/（落到用戶 system-dev/）
├── skills/
│   └── llm-wiki/           ← 複製到 Legacy-Workspace/.claude/skills/
├── scripts/
│   ├── install.sh          ← 已有專案接入腳本
│   └── update.sh           ← 舊版一鍵更新（含舊結構自動遷移）
└── docs/                   ← 這個 repo 自己的說明（why.md、wishlist.md…）

Slash Commands

安裝後在任何 CC 對話裡可用：

Command	做什麼
`/wiki-init`	初始化 wiki（新專案或接入已有專案）
`/wiki-recall`	Session 開始，手動接關（hook 沒啟動時的 fallback）
`/wiki-capture`	把這次對話的結論存進 wiki
`/wiki-update`	Session 結束，更新 status.md
`/sdd-check`	確認當前任務有沒有對應 SDD
`/issue-handle`	處理 GitHub issue（讀回自己 repo / 跨 repo 發要先問 / 禁自動輪詢）

命名閉環：init(建) → update(存，session 末) ↔ recall(接，session 初) → capture(隨時存結論)。

Hooks（軟規範 → 硬攔截）

規範不再只是 CLAUDE.md 的軟提醒，加了底線機制：

Hook	角色
`session-start-recall.sh`	開 session 自動注入 status 重點，不靠 CC 自覺
`sdd-guard.sh`	動 code 檔但沒有任何 SDD → 攔（exit 2），對應 `/sdd-check` 的自動版
`wiki-secret-scan.sh`	機敏值要寫進 `system-dev/wiki/` → 攔（exit 2），密碼/金鑰/個資的機械底線
`pre-write-guard.sh`	專案自訂禁令範本骨架（預設停用，填 pattern 才生效）

Wiki 機敏防護（不想被編入的內容）

像 .gitignore 一樣，讓不想進 wiki 的內容（密碼、金鑰、個資）不被編入。三層：

層	機制	擋什麼	性質
L1	`system-dev/wiki/.wikiignore`（glob）	整個機敏檔不編入	協議（CC 遵守）
L2	行內標記 `<!-- wiki:ignore -->`…`<!-- wiki:end -->`	檔案內某段不編入	協議（CC 遵守）
L3	`wiki-secret-scan.sh` hook	機敏值真的寫進 wiki → exit 2 擋	硬攔截（機械偵測）

L1/L2 是你主動標記，L3 是自動兜底——萬一 CC 漏掉前兩層，寫進 wiki 的那一刻會被 regex 攔下（密碼賦值、PEM 私鑰、AWS/GitHub/Slack 金鑰、JWT、連線字串帳密、身分證、信用卡號）。

誠實限制：L1/L2 靠 CC 自律，L3 靠特徵比對（有偽陽/偽陰）。這是「減少意外外洩」的機制，不是保險箱——真正的密鑰本就不該進版控。誤判時：該行尾加 wiki-secret-ok 放行；整檔機敏則加進 .wikiignore。

誠實限制：hook 擋語法層明顯違規（直接寫檔），擋不了藏在 helper / bash 裡的繞道。價值是「想跳過會被抓到 + 留痕可審」，不是技術防偽——文檔（mindset）+ hook（底線）都不可省。

設計原則

疊加，不覆蓋：接入已有專案時，現有規範保留，wiki 系統疊上去
結構即協議：CC 和你共用同一個分類系統，不需要每次解釋
CLAUDE.md 不增長：超過 100 行就是架構出問題，不是加更多內容
對話結論當場 capture：討論完用 /wiki-capture，知識不再消失

致謝

這個模板站在巨人的肩膀上：

Andrej Karpathy — LLM Wiki 概念的提出者。本模板的雙空間記憶系統直接源自他 2026 年 4 月的構想：用 LLM 把知識「pre-compile」成互相連結的 markdown，而非每次查詢都重跑 embedding 檢索。他的一句話道盡精神："Obsidian is the IDE, the LLM is the programmer, the wiki is the codebase."
- 概念延伸閱讀：The Andrej Karpathy LLM Wiki Idea、Beyond RAG (Level Up Coding)
Amazon Kiro — 本模板的 SDD（Spec-Driven Development）做法學自 Kiro。它把「動手前先有結構化規格」這件事做到最徹底；台灣雖然付費不便，但它的方法論值得致敬與借鑑。
Claude（Claude Code / Anthropic） — 本模板的 hooks、機敏防護、模組化安裝與這份說明，都是與 Claude 結對開發完成的。模板本身就是為了讓 Claude Code「從猛衝的工程師變成有紀律的工程師」——它既是工具，也是共同作者。

14 KiB Raw Permalink Blame History Unescape Escape