前言

「下禮拜有個新功能要上線，要麻煩你幫忙看一下有沒有問題？」

收到這個任務之後，你的同事通常會先問一串問題，畢竟同事不會通靈，如果通靈可以的話，是不是觀落陰要變成每個測試人員的技能：

• 功能相關的文件放在哪裡？
• 有沒有開發相關文件或測試計畫？
• 已經有手動測試案例了嗎？
• 目前有沒有自動化測試？
• 迴歸測試有包含這個功能嗎？
• 測試完之後，測試報告要放在哪裡？

我的這位新同事也是一樣，如果每次開始工作前都要重新講一次專案結構、測試流程和相關操作限制，我會把時間全部花在重複交接上，不如我把這些工作須知，都寫進 CLAUDE.md 裡面。

它就是發給新同事的員工手冊：不會包含所有知識，但會告訴他開始工作前該知道什麼，以及需要更多資訊的時候該去哪裡找。

CLAUDE.md 是什麼

一份給 Claude Code 的專案指示，專案層級通常放這兩個位置之一：

./CLAUDE.md
./.claude/CLAUDE.md

每次新對話開始的時候，Claude Code 會把範圍內的 CLAUDE.md 載入自己的腦袋。除了專案底下這份，它也支援使用者層級、組織層級與子資料夾的 CLAUDE.md；子資料夾那份只有在 Claude 開始進入該資料夾的時候才會讀。

官方建議每一份都盡量精簡，控制在 200 行以內。因為這些內容會占用新同事的記憶體，而文件內容愈多，不只是成本變高，它遵守所有指示的穩定性也會跟著下降。

概念就這樣，剩下的今天不展開。這一天真正要回答的是另一個問題：一位 SDET 的員工手冊，跟一般專案的差在哪。

為什麼手冊要短

官方建議 200 行以內，理由是「內容愈多，遵守指示的穩定性愈低」。這句話值得多想一層，因為它跟直覺相反：你多寫一條規矩，不是多守一條，是每一條都守得比原來鬆一點。

原因在於手冊是常駐的。它不像 Skill 那樣用到才載入，是每一次新對話都整份進 context，然後跟這次任務真正要處理的東西擠同一塊空間。一份寫滿五百行的手冊，等於每一輪工作開始前先塞給它一堆跟今天無關的規定，而它得自己判斷哪幾條現在適用。

所以取捨的問題不是「這條重不重要」，是**「它每次開工都需要知道嗎」**。重要但只有特定任務用得到的東西，該去 Skill；重要但只有特定資料夾適用的，該去 .claude/rules/；重要到不能靠它自律的，該去權限設定，那已經不是文字的事了。

這個 repo 的 CLAUDE.md 現在是 40 行、2,608 個字元。它不是刻意寫短的，是因為每一條寫進去之前都被問過那一句：新同事每次開始工作，都需要知道這件事嗎？

哪些寫、哪些不寫

判斷一條規則要不要放進來，先問一句：

新同事每次開始工作，都需要知道這件事嗎？

答案是「需要」的，通常是這幾類：

• 常用的建置、測試與檢查指令
• 專案目錄和主要檔案的位置
• 必須遵守的命名或設計慣例
• 開始實作前必須完成的確認
• 測試產物與報告的存放位置
• 任務完成前必須執行的驗證
• 什麼情況要讀哪一份 Skill 或文件

以下這些則不適合直接寫進員工手冊：

• 只在特定任務用得到的多步驟流程
• 大量產品背景與歷史資訊
• 只有特定資料夾或檔案類型需要遵守的規則
• 權限白名單、黑名單或其他需要強制執行的限制
• 很長的範例、教學或問題排除手冊

這些各有各的去處：Skills、.claude/rules/、docs/，或是 Claude Code 的設定檔。

一般專案的手冊，跟 SDET 的手冊差在哪

一份放在根目錄的 CLAUDE.md，不管什麼專案大概都會有這三類：

• 工作流程 —— 動手前要先讀什麼、完成前要跑什麼、怎麼回報
• 檔案位置 —— 原始碼、文件、產物各自放哪
• 安全與授權 —— 什麼不能碰、什麼要先問

差別不在有沒有這三類，在每一類裡面填什麼。一份做測試的手冊，要在這三類上各多長一塊出來。

一、測試碼有自己的家，而且只有一個

一般專案的「檔案位置」寫到 src/ 和 docs/ 大概就夠了。做測試的專案不夠，因為跟測試有關的東西會從四面八方冒出來：測試檔、設定檔、共用的操作、還有你為了確認某個選擇器而隨手寫的探測腳本。

所以規則是全部收進 tests/，一個都不例外：

跟測試有關的檔案全部放 tests/ 底下，包含 playwright.config.ts（不放 repo 根）
與過程中寫的臨時探測腳本（放 tests/tools/，用完刪掉）。

playwright.config.ts 那一句是刻意的。多數專案習慣把它放根目錄，我把它收進 tests/，理由是**「跟測試有關」這條界線不能有例外**，一開例外就會有第二個。下一節會講這條規則是怎麼被逼出來的。

二、證據跟執行產物，要分「這一輪」和「跨輪」

這一條是整份手冊裡最 SDET 的一條，一般專案完全不會有。

它做的每一件事都會產出東西：截圖、console、network、trace、findings、判定結果、開單紀錄。規則的第一層很單純，除了 charters/ 和 tests/，全部寫進 output/，repo 根目錄不准留 findings/、evidence/、截圖或 JSON。

但真正重要的是第二層：

單輪產物進 output/sessions/<date>_<slug>/，
跨輪累積的登錄簿留 output/ 根，
證據走 output/evidence/<YYYYMMDD>-<slug>/。
切進單輪就失去去重與校準的能力。

最後那一句是理由。有些檔案天生屬於「這一輪」—— 這次探索走過哪些路、發現什麼、判定結果如何。但有些檔案必須跨輪累積，例如：

• 已經開過的單的指紋索引（不然同一個 bug 會被報十次）
• 已知誤報清單（不然被否決過的東西下週會再送一次）
• 它每次預測的信心分數與實際結果（不然你永遠不知道它的自評準不準）

這三份如果跟著單輪走，它每一輪都是失憶的。它會很勤奮地重新發現上禮拜就被你否決過的東西，而且態度非常誠懇。

一般專案的產物是給人看的報告，看完就可以丟。測試專案的產物有一半是下一輪的輸入，這是為什麼位置規則要寫得這麼囉嗦。

三、產品知識與專案設定是輸入，不是內嵌

手冊裡的原句：

產品知識與專案設定是「輸入」，skill 讀它、不內嵌，否則 reuse 就死了。

這條在管的是：一支 skill 裡面不准出現你們家的網址、你們家的業務規則、你們家的 issue tracker 在哪。那些東西放 knowledge/ 和 config/，skill 需要的時候去讀。

差別在換一個專案的時候。內嵌的話，你得逐支翻出來改；分開的話，換一份 knowledge/ 就好，能力那一半原封不動搬走。

還有一條配套：那兩個資料夾的真檔一律 gitignore，只 commit 範本。因為裡面很可能有內部規格、未公開的業務規則，甚至客戶名稱。

四、不准謊報執行結果

最後一條放在「工作流程」那一類。真人同事通常知道「沒跑過就不能說通過」，但語言模型可能把「讀過程式碼、推測應該會過」和「實際執行通過」混在一起，所以這裡要把界線寫明。

任務完成前，執行與修改範圍相符的測試並回報結果。
不宣稱未實際執行的測試已經通過。

第二句要寫得這麼白，是因為它真的會這樣做。它會告訴你「測試已通過」，而那句話的依據是它讀了一遍程式碼覺得應該會過。

這條規則跟第二條是同一件事的兩面：產物是不是真的被產出來了，跟它說不說得出口，是兩回事。第二週整週都在處理這個問題。

規則不是想出來的，是踩出來的

上面那幾條看起來很有條理，但沒有一條是我坐在那裡想出來的。舉一個最瑣碎的。

手冊裡有一節是關於測試碼要放哪：

## 測試碼（tests/）
- 跟測試有關的檔案全部放 tests/ 底下，一律 .ts，包含 playwright.config.ts
  （不放 repo 根）與過程中寫的臨時探測腳本（放 tests/tools/，用完刪掉）。
  repo 根目錄不准留 .mjs、probe*、一次性腳本。

細到有點瑣碎。它是這樣來的。

我要幫這個專案建 Playwright 測試，動手前得先知道頁面上有哪些 data-test 屬性。於是寫了一支小腳本去抓，抓完發現漏了東西，再寫一支。前後寫了五支，全部叫 probe.mjs、probe2.mjs、probe3.mjs⋯⋯全部丟在 repo 根目錄。playwright.config.ts 也順手放在根目錄，因為大家都這樣放。

然後被打斷了。

當時手冊裡已經有一條「不准在 repo 根目錄留 findings/、evidence/、截圖或 JSON」。看起來涵蓋得很好，但它列的是產物，沒有一個字提到腳本。所以規則沒被違反，垃圾照樣堆出來。

修正之後我把它寫進手冊。不是因為那五支腳本有多嚴重，是因為這次的糾正只存在於那一次對話裡。不寫下來，下一輪照樣重犯，而且會是完全一樣的犯法。

憑空想像寫出來的規則通常太籠統，擋不住實際會發生的事。你的手冊第一版一定很短，那是正常的，它會隨著你被雷到的次數長出來。

揭露性原則：需要時再展開

好的專案規則不會一開始就把所有資訊交出去，而是讓 Claude 逐步找到它需要的那部分：

CLAUDE.md
    ↓ 告訴 Claude 何時使用哪個 Skill
Skill
    ↓ 定義任務流程並讀取相關內容
knowledge / config / docs
    ↓ 提供這次任務需要的詳細資訊
tests / output

這就是漸進式揭露：CLAUDE.md 提供最小且必要的常駐規則，Claude 依任務選 Skill，Skill 再讀當下需要的知識與設定，不相關的資訊不必進入這一次的 context。

橫軸是時間，不是重要性。判準是「什麼時候需要」。

Anthropic 把 context 當成有限資源，建議保留最小但高訊號的內容，其餘透過檔案路徑、搜尋工具與 Skills 在執行期間取得。

這裡有個容易踩的細節。把路徑寫在反引號裡，是告訴 Claude「需要的時候去讀」。但如果你用 @path 匯入語法，那份文件的內容仍然會在啟動時展開並載入 context，一點也沒省到。要做漸進式揭露，就保留一般路徑或改用 Skill。

那 Skill 是什麼

一套可重複使用的任務說明。每個 Skill 以 SKILL.md 為入口，可以包含適用情境、執行步驟、檢查清單、輸入與輸出格式、要讀的知識或設定，以及輔助腳本與範本。專案 Skill 通常放在 .claude/skills/<skill-name>/SKILL.md。

CLAUDE.md 跟 Skill 最大的差別是載入時機：前者是每次工作的常駐 context，後者只有被直接呼叫、或 Claude 判斷跟這次任務相關時才載入。

那這位同事需要哪些 Skill？今天先不給清單 —— 名字現在對你沒有意義，它們會在該出場的那一週自己登場。今天只給分類：

maintain/ 和 infra/ 分開是刻意的：前者處理一支測試、一次失敗，後者處理整批 —— 早上進公司看到八十支紅燈。同名的能力在兩層各出現一次不是重複，是規模升級，而且處理順序完全不同（一批要先合併成少數根因群，不能逐筆跑）。第五、六週會分得很清楚。

比清單更該講的是怎麼決定要不要開一支新的。我的門檻只有一句：

手段不同才開新的，判準不同只加一張表。

留證分成畫面和端點兩支，因為手段完全不同 —— 一邊靠截圖和 snapshot，一邊靠請求和回應。但判斷「這是不是 bug」不分家，因為流程一模一樣，只是 API 情境多幾條判準，多加一張表就好。

硬合成一支，紀律會退化成「看情況適用」；為每一種判準都開一支，你會有三十支互相抄來抄去的 Skill。這句話你可以直接搬去用，它跟測試無關，任何要拆 agent 能力的人都會遇到。

CLAUDE.md 不是權限系統

最後一個技術邊界。在 CLAUDE.md 寫下：

執行外部操作前必須先取得確認。

這是一項行為指示，不是強制性的安全控制。

如果某些操作必須被禁止、必須詢問、或只能在特定條件下執行，要用 Claude Code 的 permission rules、settings、sandbox 或 hooks。權限規則由 Claude Code 端執行，不依賴模型有沒有正確理解那句文字。

所以我的禁令沒寫進手冊正文，拉出去一個檔案 config/governance.yaml，手冊只留一句指過去。那份檔案很有得談 —— 目前「不需要人點頭」那一層是空的 —— 但那是第四週的事，等它真的拿到權限再說。

整套分工長這樣：

判準是「什麼時候需要」，不是「多重要」。

一份精簡的 CLAUDE.md 範例

# SDET Project Rules

架構、bucket 分層與心智模型的完整說明在
`architecture/sdet-skills-architecture.md`。
本文件只記錄執行任務時必須遵守的規則。

## 工作流程

- 修改前先讀取相關程式碼、測試與文件。
- 需要產品知識或專案設定時，用對應的 Skill 讀取
  `knowledge/` 與 `config/`。
- 任務完成前，執行與修改範圍相符的測試並回報結果。
- 不宣稱未實際執行的測試已經通過。

## 檔案位置

- 跟測試有關的檔案全部放 `tests/`，包含設定檔與臨時探測腳本。
- 除 `tests/` 與 `charters/` 外，執行產物一律寫入 `output/`。
- 單輪產物進 `output/sessions/<date>_<slug>/`，跨輪累積的
  登錄簿留在 `output/` 根，證據走 `output/evidence/`。
- 不覆寫既有輸出，建立新的執行目錄。

## 安全與授權

- 執行外部或具副作用的動作前，依照
  `config/governance.yaml` 判斷授權等級。
- 不讀取、輸出或提交 secrets。

三十幾行。它沒有完整介紹產品，也沒有收錄任何測試流程，只提供開始工作時必須知道的規則，以及需要更多資訊時的入口。

小結

手冊只放每次開工都要知道的事，其餘四樣東西各有去處：任務流程進 Skill、路徑規則進 .claude/rules/、詳細知識進 knowledge/ 與 docs/、真正的禁令進權限設定。判準是「什麼時候需要」，不是「多重要」。而手冊本身不是想出來的，是被雷出來的：五支 probe.mjs 堆在 repo 根目錄那次之後，才多出「臨時腳本也要放 tests/」那一條。

                    CLAUDE.md（常駐，40 行）
                每次開工都要知道的事，只留入口
                              │
        ┌─────────────┬───────┴───────┬─────────────┐
        ▼             ▼               ▼             ▼
      Skill      .claude/rules/   knowledge/     Settings
    任務流程      路徑／檔案類型    docs/ config/  Permissions
                                                   Hooks
    用到才載入     進到該資料夾      Skill 執行時    ← 真正的強制力
                   才適用            才去讀          不靠模型理解
                              │
                              ▼
              判準：什麼時候需要，不是多重要
                              │
                              ▼
                  規則從哪裡來？被雷出來的
        五支 probe.mjs 堆在根目錄 → 手冊多一條
        （原本那條只寫「產物」，沒寫「腳本」）

手冊要短是因為它常駐：多寫一條不是多守一條，是每一條都守得鬆一點。CLAUDE.md 也不是權限系統，寫「執行前必須確認」只是行為指示，真的要擋就得用 permission rules、settings 或 hooks。而規則是踩出來的，你的第一版一定很短，那是正常的，它會隨著被雷的次數長出來。

下一步

發完員工手冊之後，新同事已經知道：文件在哪裡、產物放哪裡、哪些規則必須遵守、什麼情況需要確認、遇到特定任務該用哪個 Skill。

但他還不知道自己要測的東西長什麼樣：

• 產品有哪些功能？
• 使用者會怎麼操作？
• 哪些行為是合理的？
• 哪些狀況可能是缺陷？
• 這些需求怎麼轉換成可執行的測試？

CLAUDE.md 回答的是「新同事要如何在這個專案裡工作」；明天要建立的產品知識，回答的是「我們正在測試什麼」。

參考資料

1. Claude Code Docs — How Claude remembers your project - 位置階層、載入順序、200 行建議
2. Claude Code Docs — Best practices for Claude Code - "Write an effective CLAUDE.md" 有該寫與不該寫的對照
3. Claude Code Docs — Extend Claude with skills - SKILL.md 的結構與載入時機
4. Claude Code Docs — Configure permissions - CLAUDE.md 是指引、settings 才是強制
5. Anthropic Engineering — Effective context engineering for AI agents - context 是有限資源，所以「能刪的都刪」