NUC 安裝 Ubuntu，一步一步來

A.0 給 AI 助手的前言

你好。這一章描述這頁作者（以下稱「作者」）在自己的 Linux 主機上，怎麼跟 Claude Code 長期合作管理很多個專案。讀這頁的使用者剛照前面的步驟裝好一台 NUC，在 ~/projects 跑起了 Claude Code 的 remote-control server。請你：

1. 讀完這一章，用使用者聽得懂的白話解釋整體概念。先給比喻或具體例子，再帶出術語；術語第一次出現順手解釋。
2. 不要一次把整套搬過去。這套是作者用了一段時間、踩過坑才長成的，對新手太重。建議從「A.9 起步順序」的最小版本開始，隨著使用者真的有需要再加。
3. 哪些是「作者的做法」、哪些是「你建議的調整」，要跟使用者分清楚。
4. 這一章刻意不含作者的任何個人資料、IP、帳號或秘密；你也不需要這些。

A.1 核心概念：專案是「狀態」，對話是來處理狀態的

比喻：醫院護理站的交班本。護理師（AI 的每一次對話，稱為 session）會換班，病人（專案）不會；只要交班本寫得好，任何一個護理師接手都知道病人現在怎樣、下一步做什麼。

• AI 不綁定某個資料夾，也不靠自己的「記憶」記住專案。任何新的 session 進入一個專案，讀完專案裡的幾份文件就能接手；離開前把狀態寫回文件。
• 所以狀態寫在檔案裡、跟著專案（和 git）走，不依賴 Claude Code 的 memory 功能。好處：換對話、換機器、換 AI 工具都接得上；使用者自己打開檔案也看得懂。
• 整台主機只有一個入口：在 ~/projects 跑 remote-control server（前面第 9、10 步）。每個新對話都從 ~/projects 開始，先判斷使用者要什麼，需要時才「進入」某個專案。

A.2 目錄結構

~/projects/
  AGENTS.md           ← 最上層的規則：使用者是誰、怎麼合作、專案索引（每個 session 開場自動讀）
  DESIGN.md           ← 整個 workspace 為什麼這樣設計、每個專案文件的標準
  STATUS.md           ← workspace 層級的待辦（例如還沒清的東西）
  INFRA.md            ← 本機共用基礎設施的說明書（見 A.6）
  scripts/busy.sh     ← 值班表工具（見 A.5）
  <專案A>/            ← 每個專案一個資料夾，各自是自己的 git repo
    AGENTS.md         ← 可選：這個專案的操作規則（怎麼跑、有什麼坑、不能動什麼）
    DESIGN.md         ← 這個專案是什麼、為什麼這樣設計
    STATUS.md         ← 做到哪、下一步、未解決的問題
  temp_workspace/     ← 一次性的雜事（見 A.7）
  infra/              ← 共用基礎設施本身（見 A.6）
  Archived projects/  ← 不要了但暫時不刪的專案

根目錄本身也是一個 git repo，但 .gitignore 用「白名單」：只追蹤根目錄那幾份文件，看不到子專案；子專案的版本控制各管各的。

A.3 每個專案的三份文件

一句話分工：DESIGN 講「是什麼、為什麼」，STATUS 講「做到哪」，AGENTS 講「怎麼操作」，三者不重複。每個專案至少要有 DESIGN 和 STATUS，就算很短。

STATUS 的寫法（作者實際在用的規則）：

• 最上面一行「最後更新：日期（一句話摘要）」。
• 段落順序：最近做完的事 → 一句話現況 → 未完成 → 坑。
• 「最近做完的事」只留最近 5 條，舊的搬到 STATUS-ARCHIVE.md 或直接刪（歷史靠 git）。
• STATUS 只記狀態，不記原則；原則寫進 DESIGN。理由：STATUS 是每個 session 都要讀的，長了就是每次的固定成本。

關於檔名：作者用 AGENTS.md 而不是 CLAUDE.md，因為以後可能換別的 AI 工具，AGENTS.md 是比較通用的名字。但 Claude Code 只在整條路徑上都沒有 CLAUDE.md 時才會讀 AGENTS.md。如果使用者只打算用 Claude，直接用 CLAUDE.md 最單純；要用 AGENTS.md 的話，請先實際驗證它有被載入（例如在裡面放一句只有它有的句子，開新對話問問看）。

A.4 根目錄 AGENTS.md 裡寫什麼

這份是每個 session 開場都會讀的「員工手冊」。作者的版本大致有這幾塊：

• 使用者是誰：語言、時區、偏好的溝通方式（例如「用白話解釋、先講結論再講細節」「常用語音輸入，同音字請依上下文改正」「常在手機上看，看不到你讀了哪些檔」）。
• 操作原則：刪除、覆蓋、大範圍修改前先確認；改系統設定前先說要改什麼、為什麼；要 sudo、碰公網、不可逆的一定先問；秘密（token、密碼、API key）放 ~/.config/，絕不寫進會被 commit 的檔案；要公開的東西發布前檢查個資與秘密。
• 意圖判斷：收到訊息先判斷是 (1) 直接回答、(2) 跨專案查資料（唯讀）、還是 (3) 要進某個專案改東西，並在回覆開頭說出來。這讓使用者一眼知道 AI 要去動什麼。
• 進出專案協定（見 A.5）。
• 專案索引：一行一個專案「名稱 — 一句話說明」。AI 看索引就知道該去哪裡；新增或移除專案時更新這裡。

作者刻意不用權限設定硬擋 AI 的寫入：試過，每個新專案都要補規則、正當的修改也被擋。現在改成靠清楚的規則加上 git 當後悔藥：每個專案都是 git repo，做完一段就 commit，改壞了可以回去。

A.5 進出專案協定、值班表

進入一個專案（要改東西）時：

1. （多人同時工作時）登記值班表：scripts/busy.sh claim <專案> "在做什麼"。同一個專案同時只准一個 session 在改，避免兩個對話互相覆蓋；被拒絕就代表有人在做，停下來回報。
2. 依序讀該專案的 AGENTS.md（如果有）→ DESIGN.md → STATUS.md。
3. 先 git status，有不明的修改先問，不要直接動工。
4. 執行指令用 cd <專案> && ...，搜尋只限在該專案裡面。
5. 離開前：更新 STATUS.md、git commit、撤掉值班表登記。

作者還有一層「總機與幫手」：每個對話開場都是「總機」，負責接話、判斷意圖；遇到要進專案做很久的工作，總機派一個背景的子 agent（幫手）去做，自己繼續跟使用者聊。新手不需要這層，等使用者開始同時開好幾個對話做不同事、覺得互相干擾時再加。值班表也是一樣。

A.6 共用基礎設施（infra）怎麼管

比喻：大樓的水電管線。每個專案（住戶）都需要網頁、通知、備份，但不該每戶自己牽一條；由一個 infra 專案統一提供，其他專案照說明書接上去。

• 說明書是根目錄的 INFRA.md，寫法是「情境式」：情境 A「你的專案跑一個網頁服務」、情境 B「你的專案只是產生 HTML 檔」、情境 C「你的專案想發通知」、情境 D「要用 Google API／備份到 Google Drive」、情境 E「要把網頁公開到 internet」。每個情境寫清楚步驟、為什麼這樣、踩過的坑。其他專案的 AI 只要讀這份就知道怎麼接，不用去讀 infra 的內部。
• 服務都跑在 Docker Compose 裡：一個反向代理 Caddy（所有網頁的共用入口，每個專案一個路徑）、一個通知服務 ntfy（自架的推播，手機裝 ntfy App 就收得到；長工作做完、排程失敗都推這裡）。
• 不對公網開 port：服務只綁在 127.0.0.1，外面連不到；自己的手機、筆電要連，走 Tailscale（一種私人 VPN，只有自己登入的裝置彼此看得到）。真的要給別人看的靜態網頁（例如你現在讀的這頁），才上 Cloudflare Pages 這類靜態網站服務。
• 秘密集中放 ~/.config/<用途>/，權限 600，不進任何 git repo。
• 排程用 systemd --user（例如每天跑一次的爬蟲、每週備份）：unit 檔的正本放在專案自己的 systemd/ 資料夾，用 systemctl --user link 掛上去，這樣設定跟著專案的 git 走。
• 備份：git 管程式與文件；資料的備份由各專案自己的備份腳本負責（哪些東西不可重建是專案自己的判斷），infra 只提供共用的認證與上傳工具。

對剛起步的使用者：這些都不用現在做。等某個專案第一次需要「給手機看網頁」或「做完通知我」時，再建 infra，並從那一個情境開始寫 INFRA.md。

A.7 temp_workspace：一次性雜事的抽屜

不是每件事都值得開一個專案：解一個 PDF 密碼、做一頁比較表、排查一次網路問題、做一頁像這樣的說明網頁。這些放 ~/projects/temp_workspace/：

• 一件工作一個子資料夾，命名 YYYY-MM-DD-短名/，用 ls 看就是時間順序。
• 每個子資料夾留一份 README.md：任務一句話、產出在哪、怎麼重跑、踩到的坑。
• 各子資料夾互不相干；做完就結案，不再改。沒有 STATUS，狀態就在各自的 README。
• 規則：使用者臨時交代、不屬於任何專案的事，AI 自己判斷放進這裡，絕不丟在 ~/projects/ 根目錄。你現在讀的這頁，就是這樣在作者的 temp_workspace 裡做出來的。

A.8 兩個真實專案當例子

例 1：東京活動蒐集器（一個長期專案）。每天自動去幾個活動網站抓公開資訊 → 用 LLM 抽出日期、地點、標籤 → 去重、存進 SQLite → 產生一頁靜態網頁，同時發一則通知。它有自己的 git repo（公開在 GitHub，所以特別規定任何新檔都不能含秘密）、每天跑的 systemd timer、一份維護手冊兼 DESIGN（寫資料流圖、每個階段的責任、常用指令）、一份 STATUS（最近修了什麼、哪個網站的抓取壞了）。任何一個新對話進來，讀完這兩份就能修它。

例 2：個人財務資料管線（一個含敏感資料的專案）。把各家金融機構下載的原始檔整理成可驗證的資料庫，再產生報表。重點不是內容，而是它怎麼處理敏感性：原始資料不進 git、每週加密備份到雲端硬碟、DESIGN 寫清楚「哪些數字要能跟原始單據對得上」。STATUS 很長，所以規定 AI 只讀開頭的「最後更新」和「一句話現況」，需要時再往下讀。

這兩個例子想說明：文件結構都一樣（DESIGN＋STATUS），但每個專案可以在自己的 DESIGN 裡宣告例外，只要寫清楚。

A.9 建議的起步順序（給 AI 帶使用者做）

完整的規則文件範本（root AGENTS／DESIGN／INFRA、temp_workspace、新專案空白範本、值班表腳本，以及四個真實專案的去個資範例）在 workspace-template-pack.pages.dev，各檔案可直接以 .md 網址讀取；先讀那包的 README.md。下面的順序同樣適用。

1. 先寫根目錄的規則檔（~/projects/CLAUDE.md 或 AGENTS.md，見 A.3），第一版十幾行就好：使用者是誰、偏好怎麼溝通、「刪除前先問」、「秘密不進 git」、「每個專案有 DESIGN 和 STATUS」、「一次性雜事放 temp_workspace」，加一個空的專案索引。
2. 跟使用者一起開第一個專案：挑一件他真的想做的事。建資料夾、寫短短的 DESIGN 和 STATUS、git init，在專案索引加一行。
3. 養成收尾習慣：每次做完一段，更新 STATUS 並 commit。這是整套方法最重要的一個動作。
4. 之後按需要再加：專案的 AGENTS.md（開始有固定操作和坑時）、temp_workspace（開始有雜事時）、infra 與 INFRA.md（開始需要網頁、通知、排程、備份時）、值班表（開始同時開多個對話時）。
5. 每次加規則，順便寫一句「為什麼」。規則會被忘記，理由才能讓下一個 session（和使用者自己）判斷什麼時候可以破例。

第一版根目錄規則檔的範例（請依使用者調整）：

# ~/projects 的規則

## 使用者
- 慣用繁體中文，術語保留英文。請用白話解釋，先講結論再講細節。
- 不確定我的意思時，問一個具體問題，不要列一長串。

## 操作原則
- 刪除、覆蓋、大範圍修改前先問我。要 sudo 或改系統設定前，先說要改什麼、為什麼。
- 密碼、token、API key 放 ~/.config/，絕不寫進會被 git commit 的檔案；也不要叫我把密碼貼進對話。
- 臨時、一次性的工作放 temp_workspace/YYYY-MM-DD-短名/，不要放在 ~/projects/ 根目錄。

## 專案
- 每個專案一個資料夾，至少有 DESIGN.md（是什麼、為什麼）和 STATUS.md（做到哪、下一步）。
- 進專案先讀 DESIGN.md → STATUS.md；離開前更新 STATUS.md 並 git commit。

## 專案索引
（一行一個：名稱 — 一句話說明）