# 07 — 怎麼在自己的專案採用

上一層：[06 日常循環](06-daily-loop.md)　回：[README](README.md)　模板：[templates/](templates/)

---

## 先講一句最重要的

> 🚨 **不要照抄這整套。**

這套系統長成現在這樣，是因為那個專案踩了 17 次特定的坑。
**你的坑不一樣**，所以你的 hook 和守衛也應該不一樣。

可以直接拿走的是**三個結構**：

1. 三層記憶的分工（規則／記憶／任務）
2. 四層成本結構（貴的是正文，不是守衛）
3. 教訓迴圈（一次痛 → 一條永久攔截）

其餘的（我的 17 條 hook、我的守衛）請當作**範例**，不是清單。

---

## 第 1 天 — 30 分鐘

### ① 建規則檔（10 分鐘）

複製 [templates/CLAUDE.md](templates/CLAUDE.md)，填三個地方：

```
專案概觀      三到五行：技術棧、進入點、「開工前先讀哪兩份」
Commands      你每天真的會打的那幾行指令
Conventions   編碼、命名、你已經知道自己會忘的那兩三件事
```

**這個階段不要寫規則。** 你還不知道自己會踩什麼坑，現在寫的規則有九成會是猜的。

### ② 建任務檔（10 分鐘）

```
task/work.txt       ← 還要花多少時間（一列一行）
task/journal.txt    ← 那天發生什麼（append-only）
task/evidence.txt   ← 做完了嗎、怎麼證明（每列要有實測數字）
POSTMORTEMS.md      ← 事故記錄（先空著，它會自己長出來）
```

把**現在手上的工作**寫進 `work.txt`，一列一行。這是唯一需要立刻填的檔。

### ③ 裝第一個 hook（10 分鐘）

裝一個就好，而且要挑**你這週已經犯過的那個錯**。

沒有頭緒的話，這一條幾乎對每個人都成立：

```
提交前掃機密（.env、金鑰、token、內部 IP）
```

用 [templates/hook_pre_bash.py](templates/hook_pre_bash.py) 改。
⚠️ 記得**同時**掛在 git 原生的 `.git/hooks/pre-commit`（見 [05](05-guards.md)），
因為 agent 的 hook 只在 AI 下指令時跑。

---

## 第 1 週 — 讓循環開始轉

### 每次動手前

用 [prompts/03-plan-not-code.md](prompts/03-plan-not-code.md)：**要計畫，不要 code。**

這一個習慣的投報率遠高於其他所有東西，而且今天就能用。

### 每次踩坑後

用 [prompts/04-postmortem-to-guard.md](prompts/04-postmortem-to-guard.md)：

```
1. 寫進 POSTMORTEMS.md：症狀 / 結構性根因 / 現在誰接住它
2. 問「機器接得住嗎」→ hook / 守衛 / 規則正文
3. 如果答案是「規則正文」，先停一下再問一次 ——
   有九成的東西其實接得住，只是需要多想十分鐘
```

### 每次交付後

用 [prompts/05-delivery-registration.md](prompts/05-delivery-registration.md)：三個檔一起更新，**同一個工作階段內**。

---

## 第 1 個月 — 開始有複利

### 第 2 週：寫第一支守衛

挑一件**「做完了也不會知道出錯」**的事。典型候選：

| 如果你的專案有 | 寫一支守衛去數 |
|---|---|
| 文件宣稱的數字（表數、端點數、模組數） | 宣稱值 vs code 現算 |
| 「這種東西一律要走某個函式」的規則 | 有幾個呼叫點、幾個走了、幾個沒走 |
| 一份索引 / 目錄 / 對照表 | 從 code 端反查它有沒有說謊 |
| 兩份必須一致的東西（前後端常數、兩個平台） | 逐值比對 |

用 [templates/guard_example.py](templates/guard_example.py)。
**它必須印覆蓋率數字** —— 沒有數字的 PASS 只是「沒去看」的同義詞。

### 第 3 週：寫第一支演練

用 [templates/guard_drill_example.py](templates/guard_drill_example.py)，
對你的守衛注入一次假故障，確認它會紅。

**很有可能第一次就會發現它根本沒在驗。** 那正是這一層存在的理由。

⚠️ 記得加**反向案例**。

### 第 4 週：第一次瘦身

打開規則檔，逐段問：

```
這一段每次對話都要付它的行數 —— 它值得嗎？
  ├ 這是敘事嗎？        → 搬去事故記錄
  ├ 這是進度嗎？        → 搬去排程表
  ├ 這是操作步驟嗎？    → 搬去操作手冊
  ├ 機器接得住嗎？      → 變成 hook 或守衛
  └ 以上皆非            → 留下，但壓縮成「判準句 + 一行指標」
```

用 [prompts/06-rules-file-diet.md](prompts/06-rules-file-diet.md)。

---

## 常見問題

### Q：我的專案很小，需要這麼多層嗎？

不需要。**最小可用版本是三個東西**：

```
1. 一份規則檔（就算只有 20 行）
2. 「要計畫、不要 code」這個習慣
3. 一份事故記錄
```

第 3 項會自己告訴你下一層該加什麼。**不要預先設計防線，讓事故來指定它們。**

### Q：規則檔應該多長？

那個專案的上限是 **500 行**，而且**這個上限本身由守衛檢查**
（`spec_check` 會印「CLAUDE.md 403 行／上限 500（最肥的三節是哪幾節）」）。

設一個上限，並且讓機器提醒你 —— 否則它一定會長回去。那個專案的規則檔就長回去過一次。

### Q：AI 不照規則做怎麼辦？

**這是正常的，不是 AI 的問題。** 一條規則躺在 400 行裡，注意力份額趨近於零
（我自己也會忘 —— 同一條規則我違反過三次）。

正確的反應**不是**把規則寫得更醒目，而是問：

> **機器怎麼接住它？**

如果真的接不住，第二好的辦法是**要求一個可觀測的產出**
（例如「在回覆開頭印出查詢結果」）—— 把不可觀測的內部行為變成一眼能驗收的東西。

### Q：這套東西花了多少時間建？

分散在數個月，而且**從來沒有「建置期」** —— 每一格都是踩到之後花 20–60 分鐘補的。

如果你想一次建完，你會建出一堆猜出來的規則，然後在三週內把它們全部關掉。

### Q：多人團隊適用嗎？

**部分適用。**

| 適用 | 要換掉 |
|---|---|
| 三層記憶的分工 | 純文字任務檔（併發編輯會炸）→ 換成真的專案管理工具 |
| 四層防線 | 個人化的記憶層 → 換成共用的 ADR（架構決策紀錄） |
| 教訓迴圈 | 「我裁示」→ 換成 review 流程 |

**作廢紀錄那一格在團隊裡價值更高**，因為重議的成本乘以人數。

---

## 最後

這套系統的價值不在於它有多完整，而在於一件很簡單的事：

> **同一型錯誤只會花你一次。**

如果你做到這一點，其餘的形狀你會自己長出來 —— 而且會比抄來的更合身。