# workspace 範本包 — 給 AI 的導讀

這一包是一位作者在自己的 Linux 主機上，用 Claude Code 長期管理多個專案所累積的規則文件，整理成**通用、去個資**的範本。
你（AI）拿到的使用者剛把一台機器裝好、在 `~/projects` 跑起 Claude Code；請你讀完這包，用白話解釋給他聽，再**從最小版本開始**帶他建自己的 `~/projects`。

## 先講三件事

1. **不要一次把整套搬過去。** 這套是作者用了一段時間、踩過坑才長成的，對新手太重。照下面「建議導入順序」走，使用者真的有需要再加下一層。
2. **分清「作者的做法」與「你建議的調整」。** 文件裡標 `（作者的做法）` 的是作者的取捨，不是唯一正解；使用者的語言、工具、專案性質可能都不同。
3. **每條規則後面的「為什麼」比規則本身重要。** 規則會被忘記，理由才讓下一個 session（和使用者自己）判斷什麼時候可以破例。帶使用者寫規則時，也請他每條寫一句為什麼。

核心概念一句話：**專案是「狀態」，對話（session）是來處理狀態的。** 狀態寫在專案裡的檔案（跟 git 走），不靠 AI 的記憶；任何新對話讀完那幾份文件就能接手，離開前把狀態寫回。

## 包裡有什麼

| 檔案 | 是什麼 | 什麼時候用 |
|---|---|---|
| `README.md` | 本檔 | 先讀 |
| `AGENTS.md` | root 規則範本：使用者是誰、操作原則、意圖判斷、進出專案協定、（進階）總機與幫手、專案索引 | **第一步就要**，但只填最小的幾段 |
| `DESIGN.md` | workspace 設計標準：核心概念、目錄結構、每個專案的文件標準、STATUS 規則、新專案範本、指令檔載入注意事項 | 第一步讀懂概念；第二步開專案時照 §5 |
| `project-template/` | 新專案的空白 `DESIGN.md`、`STATUS.md`、`.gitignore` | 每開一個專案複製一份 |
| `temp_workspace/AGENTS.md`、`DESIGN.md` | 一次性雜事的抽屜：一件工作一個子目錄、狀態在各自 README | 開始有雜事時 |
| `INFRA.md` | 基礎設施說明書範本（情境式）：反向代理、通知、秘密放哪、外部 API 憑證、備份分工、公開靜態網站、remote-control 常駐、排程 | 開始需要網頁／通知／排程／備份時；**剛起步不用** |
| `scripts/busy.sh` | 值班表：同一專案同時只准一個 session 在改 | 開始同時開多個對話時 |
| `examples/` | 四個真實專案的去個資版本（活動蒐集器、健康資料、財務管線、筆記庫配套），各自帶 README 說明示範什麼 | 想看「規則實際用起來長什麼樣」時；不是要照抄 |

## 建議導入順序

1. **先寫根目錄的規則檔**（`~/projects/CLAUDE.md` 或 `AGENTS.md`），第一版十幾行就好：使用者是誰、偏好怎麼溝通、「刪除前先問」、「秘密不進 git」、「每個專案有 DESIGN 和 STATUS」、「一次性雜事放 temp_workspace」，加一個空的專案索引。範本 `AGENTS.md` 裡把用不到的段落（總機與幫手、記憶與 to-do、值班表）整段刪掉。
2. **跟使用者一起開第一個專案**：挑一件他真的想做的事。建資料夾、從 `project-template/` 複製短短的 DESIGN 和 STATUS、`git init`，在專案索引加一行。
3. **養成收尾習慣**：每次做完一段，更新 STATUS 並 commit。這是整套方法最重要的一個動作。
4. 之後按需要再加：專案的 `AGENTS.md`（開始有固定操作和坑時）、`temp_workspace/`（開始有雜事時）、`infra/` 與 `INFRA.md`（開始需要網頁、通知、排程、備份時）、值班表與「總機與幫手」（開始同時開多個對話時）、筆記庫／to-do／工作日誌（開始想要跨專案的記憶時）。
5. 每次加規則，順便寫一句「為什麼」。

## 檔名注意：CLAUDE.md 還是 AGENTS.md

作者用 `AGENTS.md`（因為以後可能換別的 AI 工具）。但 **Claude Code 只在工作目錄與所有上層目錄都沒有 `CLAUDE.md` 時才讀 `AGENTS.md`**。使用者只打算用 Claude 的話，直接用 `CLAUDE.md` 最單純；要用 `AGENTS.md` 的話，請先實際驗證它有被載入（在裡面放一句只有它有的句子，開新對話問問看）。細節在 `DESIGN.md` §6。

## 這包怎麼做出來的、去個資範圍

從作者的 workspace 文件改寫而成。拿掉的：姓名、帳號、email、主機名、VPN 網域、IP、通知 topic 名、雲端資料夾名、居住地、金融機構與帳號金額、醫療數值與藥名、雇主與客戶名。只跟作者環境有關的段落（特定網路設備、別台機器、DNS 排查）整段拿掉或只留一句通用教訓。

去個資掃描：改完後用 grep 掃一遍你自己的姓名、帳號、主機名、VPN 網域、IP、email、機構名、藥名等關鍵字，應該零命中（`127.0.0.1`、`localhost` 與明顯的範例值不算）。**這份關鍵字清單本身就是個資，只在本機跑、不要寫進會公開的檔案。**

## 回報給使用者時

- 先講結論與他要做的事，再講細節。
- 他看不到你讀了什麼，講架構先給比喻或具體例子再對應到術語。
- 不確定他的意思時，問一個具體問題，不列一長串。