Jan 7, 2026

打造 AI 友善的專案文檔：CLAUDE.md 完整指南（下）

系列文章：本文是 CLAUDE.md 完整指南系列的最終篇，深入探討進階技巧、實戰演練與成功案例。

📖 第一篇：基礎概念與核心章節 📖 第二篇：複雜架構的文檔化

🎯 前言

經過前兩篇文章的學習，你已經掌握了：

✅ CLAUDE.md 的基礎架構（7 個核心章節）
✅ 複雜系統的文檔化技巧（多租戶、Docker、測試）

但是，當你真正要動手撰寫時，可能會遇到：

🤔 「團隊有 10 個人，CLAUDE.md 要怎麼協作維護？」
🤔 「我要從哪裡開始寫？感覺無從下手…」
🤔 「如何讓文檔更易讀、更容易維護？」

本篇文章將回答這些問題，並提供：

🎨 進階技巧：視覺設計、多人協作最佳實踐
🚀 實戰演練：從零開始的完整流程
🌟 成功案例：不同類型專案的實際範例
📈 ROI 分析：量化 CLAUDE.md 帶來的效益

🎨 進階技巧

📐 視覺設計：讓文檔更易讀

CLAUDE.md 不僅是給 AI 看的，也是給團隊成員看的。良好的視覺設計可以大幅提升可讀性。

✨ Emoji 的策略性使用

原則：用 Emoji 建立視覺層級，但不要濫用。

## 好的範例：有系統的 Emoji 使用

### 📋 核心功能
- ✅ 功能 A：已完成
- 🚧 功能 B：開發中
- ⏳ 功能 C：規劃中
- ❌ 功能 D：已廢棄

### ⚠️ 重要限制
- 🔴 **不可升級** PHP 版本
- 🟡 **謹慎修改** 資料庫 schema
- 🟢 **可自由調整** 前端樣式

### 🎯 快速索引
- 📦 架構：見「程式架構」章節
- 🐳 環境：見「開發環境」章節
- 🧪 測試：見「測試流程」章節

## 不好的範例：Emoji 濫用

### 🎉🎊✨ 超級重要的核心功能 🚀🔥💯
- 😀 功能 A 👍
- 😎 功能 B 🎯
- 🤩 功能 C 💪

建議的 Emoji 規範：

類型	Emoji	用途
章節標示	📋 📦 🏗️ 🐳 🧪	標示主要章節
狀態	✅ 🚧 ⏳ ❌	標示完成狀態
警示級別	🔴 🟡 🟢	標示重要程度
動作	⚡ 🚀 🔧 🔍	標示操作類型
提示	💡 ⚠️ 📌 ℹ️	標示提示資訊

📊 表格的有效使用

表格是呈現結構化資訊的最佳工具，但要注意可讀性。

好的表格設計：

## 環境變數配置

| 變數名稱 | 必填 | 預設值 | 說明 | 範例 |
|:---------|:----:|:-------|:-----|:-----|
| `DB_HOST` | ✅ | - | 資料庫主機 | `localhost` |
| `DB_PORT` | ⬜ | `3306` | 資料庫埠號 | `3306` |
| `DB_NAME` | ✅ | - | 資料庫名稱 | `myapp_db` |
| `REDIS_URL` | ⬜ | - | Redis 連接字串 | `redis://localhost:6379` |

表格設計原則：

對齊方式：數字右對齊，文字左對齊，狀態置中
欄位數量：不超過 6 欄（避免橫向捲動）
必要資訊：每個欄位都要有存在的必要性
範例值：提供實際可用的範例

🎨 程式碼區塊的格式化

使用語法高亮：

## ✅ 好的寫法

\`\`\`php
// 檔案：DBPDO.php
class DBPDO {
    private static $instance = null;
    private $pdo;

    public static function getInstance() {
        if (self::$instance === null) {
            self::$instance = new self();
        }
        return self::$instance;
    }
}
\`\`\`

## ❌ 不好的寫法

\`\`\`
class DBPDO {
    private static $instance = null;
    // ...（沒有語法高亮，沒有檔案路徑）
}
\`\`\`

加入檔案路徑註解：

\`\`\`javascript
// 檔案：src/utils/api.js
export async function fetchData(endpoint) {
    const response = await fetch(`/api/${endpoint}`);
    return response.json();
}
\`\`\`

使用行號標註重點：

\`\`\`python
# 檔案：app.py
def process_data(data):
    result = []
    for item in data:
        if item.status == 'active':  # ← 重點：只處理 active 狀態
            result.append(transform(item))
    return result
\`\`\`

📱 層級結構的規劃

使用清晰的標題層級：

# CLAUDE.md ← 檔案標題（通常不用）

## 快速開始 ← H2：主章節
### 環境安裝 ← H3：子章節
#### Windows 環境 ← H4：細節說明
##### 注意事項 ← H5：極少使用

## 專案概述 ← H2：另一個主章節

層級規則：

H2：主章節（最多 7-10 個）
H3：子章節（每個 H2 下最多 5 個）
H4：細節說明（謹慎使用）
H5/H6：幾乎不用（考慮拆分章節）

👥 多人協作的最佳實踐

當團隊有多人維護 CLAUDE.md 時，需要建立協作機制。

📝 責任分工

策略 1：章節負責人制度

## 📋 文檔維護責任表

| 章節 | 負責人 | 最後更新 | 狀態 |
|:-----|:-------|:---------|:-----|
| 快速開始 | @張三 | 2026-01-05 | ✅ 最新 |
| 專案概述 | @李四 | 2025-12-20 | 🟡 待更新 |
| 開發環境 | @王五 | 2026-01-07 | ✅ 最新 |
| 程式架構 | @趙六 | 2025-11-15 | 🔴 過期 |
| 測試流程 | @張三 | 2026-01-03 | ✅ 最新 |

### 更新流程

1. **修改內容**：負責人直接修改對應章節
2. **PR Review**：至少 1 人審核（非負責人）
3. **更新標記**：在章節頂部標記更新日期
4. **通知團隊**：在 Slack 發布更新公告

策略 2：模組化文檔

將大型 CLAUDE.md 拆分成多個檔案：

docs/
├── CLAUDE.md                    # 主文檔（索引）
├── CLAUDE-quickstart.md         # 快速開始
├── CLAUDE-architecture.md       # 程式架構
├── CLAUDE-development.md        # 開發環境
├── CLAUDE-testing.md            # 測試流程
└── CLAUDE-deployment.md         # 部署流程

主文檔 (CLAUDE.md) 範例：

# CLAUDE.md

> 📅 最後更新：2026-01-07
> 👥 維護團隊：前端團隊 + 後端團隊

## 📚 完整文檔導覽

本專案的 CLAUDE.md 已模組化，請根據需求閱讀對應文檔：

### 🚀 新人必讀
- [**快速開始**](./CLAUDE-quickstart.md) - 30 秒啟動專案
- [**專案概述**](./CLAUDE-architecture.md#專案概述) - 了解整體架構

### 💻 開發相關
- [**開發環境**](./CLAUDE-development.md) - Docker、IDE 設定
- [**程式架構**](./CLAUDE-architecture.md) - 目錄結構、設計模式
- [**API 文檔**](./CLAUDE-architecture.md#api-設計) - API 端點說明

### 🧪 測試與部署
- [**測試流程**](./CLAUDE-testing.md) - 單元測試、整合測試
- [**部署流程**](./CLAUDE-deployment.md) - CI/CD、環境設定

### 📋 參考資料
- [**開發規範**](./CLAUDE-development.md#開發規範) - Coding Style
- [**故障排除**](./CLAUDE-troubleshooting.md) - 常見問題

## 🔄 文檔更新流程

見 [貢獻指南](./CONTRIBUTING.md)

優點：

✅ 每個檔案專注單一主題
✅ 減少 merge conflict
✅ 更容易分工維護
✅ 可以針對特定章節做版本控制

🔄 版本控制策略

策略 1：使用 Git Tag 標記重大更新

# 重大架構變更時打 tag
git tag -a claude-md-v2.0 -m "重構多租戶架構說明"
git push origin claude-md-v2.0

在 CLAUDE.md 中記錄版本：

## 📜 版本歷史

### v3.0 (2026-01-07)
**重大更新：新增 Microservices 架構說明**
- ✨ 新增：微服務架構章節
- 🔄 更新：API 閘道設定
- 📝 改進：服務間通訊說明
- 👤 負責人：@趙六

### v2.5 (2025-12-15)
**改進：Docker 環境文檔**
- 🐳 新增：M1/M2 Mac 設定指南
- 🔧 修正：XDebug 設定錯誤
- 📊 新增：效能監控工具說明
- 👤 負責人：@王五

### v2.0 (2025-11-01)
**重大更新：多租戶架構重構**
- 🏗️ 重構：多租戶架構完整改寫
- 🔒 新增：權限系統詳細說明
- 🧪 新增：自動化測試流程
- 👤 負責人：@李四

策略 2：Change Log 自動化

使用 Git hooks 自動更新變更記錄：

# .git/hooks/pre-commit
#!/bin/bash

# 檢查是否修改了 CLAUDE*.md
if git diff --cached --name-only | grep -q "CLAUDE.*\.md"; then
    echo "⚠️  檢測到 CLAUDE.md 變更"
    echo ""
    echo "請確認："
    echo "1. 已更新版本號（如有重大變更）"
    echo "2. 已更新「最後更新日期」"
    echo "3. 已在版本歷史中記錄變更"
    echo ""
    read -p "是否繼續提交？(y/n) " -n 1 -r
    echo
    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
        exit 1
    fi
fi

📢 團隊溝通機制

策略 1：變更通知

在 Slack/Teams 建立專屬頻道：

## Slack 通知範例

**#docs-updates 頻道**

---
📝 **CLAUDE.md 更新通知**

**變更者**：@張三
**時間**：2026-01-07 14:30
**類型**：🔧 修正

**變更內容**：
- 修正 Docker XDebug 設定（Linux 環境）
- 新增常見問題：Port 9003 被佔用

**影響範圍**：使用 Linux 開發的同事

**連結**：[查看 Commit](https://github.com/org/repo/commit/abc123)

---

策略 2：Review 清單

PR 中加入 CLAUDE.md 專用的 review checklist：

## CLAUDE.md 更新 PR Checklist

### 內容檢查
- [ ] 所有程式碼範例都可執行
- [ ] 檔案路徑正確無誤
- [ ] 程式碼範例清晰易懂

### 格式檢查
- [ ] Markdown 格式正確（無語法錯誤）
- [ ] 標題層級符合規範（H2 → H3 → H4）
- [ ] 表格對齊正確
- [ ] 程式碼區塊有語法高亮

### 版本管理
- [ ] 已更新「最後更新日期」
- [ ] 如有重大變更，已更新版本號
- [ ] 已在版本歷史記錄變更
- [ ] 已更新章節負責人（如適用）

### 測試驗證
- [ ] 已測試文檔中的指令（至少抽查 3 個）
- [ ] 已請至少 1 位團隊成員審閱
- [ ] 已在 #docs-updates 發布通知

🎓 新人 Onboarding

利用 CLAUDE.md 加速新人上手：

## 🎓 新人入職指南

### 第一天：環境建置（2 小時）

**目標**：成功啟動專案，能在本機運行

**步驟**：
1. 閱讀 [快速開始](./CLAUDE-quickstart.md)（10 分鐘）
2. 安裝開發環境（30 分鐘）
   - Docker Desktop
   - VS Code + 必要插件
3. Clone 專案並啟動（20 分鐘）
   \`\`\`bash
   git clone <repo-url>
   cd project
   docker-compose up -d
   \`\`\`
4. 驗證環境（10 分鐘）
   - 訪問 http://localhost
   - 執行測試腳本
5. 與 Mentor 確認（30 分鐘）

**完成指標**：✅ 能在本機看到登入頁面

---

### 第二天：理解架構（4 小時）

**目標**：了解專案整體架構和核心概念

**步驟**：
1. 閱讀 [專案概述](./CLAUDE-architecture.md#專案概述)（30 分鐘）
2. 閱讀 [程式架構](./CLAUDE-architecture.md)（1 小時）
3. 與 Claude 互動學習（1 小時）
   - 問 Claude：「這個專案的目錄結構是什麼？」
   - 問 Claude：「多租戶架構是如何運作的？」
   - 問 Claude：「我想新增一個 API 端點，應該怎麼做？」
4. 閱讀 2-3 個核心檔案的原始碼（1 小時）
   - `DBPDO.php` - 資料庫連接
   - `checkPermission.php` - 權限檢查
   - `module_a/export/batch.php` - 批次輸出範例
5. 與 Mentor 討論（30 分鐘）

**完成指標**：✅ 能向 Mentor 說明多租戶架構的運作方式

---

### 第三天：實作小任務（6 小時）

**目標**：完成第一個功能開發

**任務範例**：新增「匯出 CSV」功能
1. 使用 Claude 協助理解現有匯出功能（30 分鐘）
2. 撰寫新功能（2 小時）
3. 撰寫測試（1 小時）
4. 使用 curl 測試（30 分鐘）
5. 提交 PR（30 分鐘）
6. Code Review 與修正（1.5 小時）

**完成指標**：✅ PR 被 merge

---

### 第一週結束：文檔貢獻

**目標**：回饋新人視角，改善文檔

**任務**：
- 記錄遇到的困難
- 發現文檔中不清楚的地方
- 提交至少 1 個 CLAUDE.md 改進 PR

**範例改進**：
- 補充 Windows 環境的特殊設定
- 新增常見錯誤訊息的解決方法
- 改善不清楚的說明文字

為什麼這樣設計：

✅ 結構化的學習路徑
✅ 明確的完成指標
✅ 鼓勵新人貢獻文檔（新人視角最寶貴）

🚀 實戰演練

現在讓我們實際演練如何從零開始撰寫 CLAUDE.md。

📝 從零開始：30 分鐘快速建立

假設你有一個 Node.js + Express + MongoDB 的專案，完全沒有 CLAUDE.md。

⏱️ 階段 1：基礎骨架（10 分鐘）

步驟 1：建立檔案

touch CLAUDE.md

步驟 2：複製基礎模板

# CLAUDE.md

> 📅 最後更新：2026-01-07
> 👤 維護者：你的名字

## ⚡ 快速開始

\`\`\`bash
# 1. 安裝依賴
npm install

# 2. 設定環境變數
cp .env.example .env

# 3. 啟動資料庫
docker-compose up -d mongodb

# 4. 啟動開發伺服器
npm run dev
\`\`\`

訪問：http://localhost:3000

---

## 📋 專案概述

### 專案名稱
[你的專案名稱]

### 技術棧
- **後端**：Node.js 18.x + Express 4.x
- **資料庫**：MongoDB 6.x
- **前端**：React 18.x
- **部署**：Docker

### 核心功能
- [ ] 使用者認證
- [ ] RESTful API
- [ ] 資料 CRUD
- [ ] 檔案上傳

---

## 🛠️ 開發環境

### 必要工具
- Node.js 18+
- Docker Desktop
- VS Code

### 環境變數
見 `.env.example`

---

## 🏗️ 程式架構

### 目錄結構
\`\`\`
project/
├── src/
│   ├── routes/      # API 路由
│   ├── models/      # 資料模型
│   ├── controllers/ # 控制器
│   └── utils/       # 工具函數
├── tests/           # 測試
└── docs/            # 文檔
\`\`\`

---

## 🧪 測試流程

\`\`\`bash
# 單元測試
npm test

# 整合測試
npm run test:integration
\`\`\`

---

## 📝 開發規範

### Git Commit 格式
\`\`\`
feat: 新增功能
fix: 修正 bug
docs: 文檔更新
\`\`\`

---

## 🚀 部署流程

\`\`\`bash
# 建置
npm run build

# 部署
docker-compose up -d
\`\`\`

完成：基礎骨架建立完成！

⏱️ 階段 2：補充關鍵資訊（10 分鐘）

現在開始填入專案特定的資訊。

優先補充的內容：

快速開始的實際指令

## ⚡ 快速開始

\`\`\`bash
# 1. 安裝依賴（約 2 分鐘）
npm install

# 2. 啟動 MongoDB
docker-compose up -d mongodb
# 等待訊息：MongoDB started successfully

# 3. 資料庫初始化
npm run db:seed
# 會建立測試帳號：admin / Admin@123

# 4. 啟動開發伺服器
npm run dev
# 應該看到：Server running on http://localhost:3000
\`\`\`

**驗證**：
\`\`\`bash
curl http://localhost:3000/api/health
# 預期回應：{"status":"ok"}
\`\`\`

專案的獨特之處

## 📋 專案概述

### 專案特點

- 🔐 **JWT 認證**：使用 Access Token + Refresh Token 機制
- 📁 **檔案上傳**：支援圖片上傳至 AWS S3
- 🔍 **全文搜尋**：使用 MongoDB Atlas Search
- 📊 **資料匯出**：支援 CSV / Excel / PDF

### 與其他專案的差異

- ⚠️ 不使用 TypeScript（歷史原因）
- ⚠️ 使用自訂的 ORM 而非 Mongoose
- ⚠️ 前端使用 Class Component 而非 Hooks

常見的開發任務

## 🏗️ 程式架構

### 如何新增 API 端點

**範例**：新增「取得使用者清單」API

1. **建立路由**（`src/routes/users.js`）
   \`\`\`javascript
   router.get('/users', authMiddleware, userController.getUsers);
   \`\`\`

2. **建立控制器**（`src/controllers/userController.js`）
   \`\`\`javascript
   exports.getUsers = async (req, res) => {
       const users = await User.find({ active: true });
       res.json({ success: true, data: users });
   };
   \`\`\`

3. **新增測試**（`tests/users.test.js`）
   \`\`\`javascript
   test('GET /users should return user list', async () => {
       const res = await request(app).get('/api/users');
       expect(res.status).toBe(200);
       expect(res.body.success).toBe(true);
   });
   \`\`\`

⏱️ 階段 3：加入實戰經驗（10 分鐘）

補充「只有你知道」的隱性知識。

補充內容：

常見錯誤與解決方法

## 🛠️ 開發環境

### 常見問題

#### 問題 1：MongoDB 連接失敗

**錯誤訊息**：
\`\`\`
MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017
\`\`\`

**原因**：MongoDB 容器未啟動或未就緒

**解決方法**：
\`\`\`bash
# 檢查容器狀態
docker-compose ps

# 查看日誌
docker-compose logs mongodb

# 重啟容器
docker-compose restart mongodb

# 等待 30 秒後再試
\`\`\`

---

#### 問題 2：Port 3000 被佔用

**錯誤訊息**：
\`\`\`
Error: listen EADDRINUSE: address already in use :::3000
\`\`\`

**解決方法**：
\`\`\`bash
# macOS/Linux: 找出佔用的 process
lsof -ti:3000 | xargs kill -9

# Windows: 找出佔用的 process
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# 或修改 port
PORT=3001 npm run dev
\`\`\`

陷阱與注意事項

## ⚠️ 開發注意事項

### 資料庫操作

**陷阱 1：忘記 await**

\`\`\`javascript
// ❌ 錯誤：沒有 await，拿到 Promise
const user = User.findById(id);
console.log(user.name); // undefined

// ✅ 正確
const user = await User.findById(id);
console.log(user.name); // 正常顯示
\`\`\`

**陷阱 2：未處理錯誤**

\`\`\`javascript
// ❌ 危險：錯誤會導致伺服器崩潰
app.get('/users/:id', async (req, res) => {
    const user = await User.findById(req.params.id);
    res.json(user);
});

// ✅ 正確：使用 try-catch
app.get('/users/:id', async (req, res) => {
    try {
        const user = await User.findById(req.params.id);
        if (!user) {
            return res.status(404).json({ error: 'User not found' });
        }
        res.json(user);
    } catch (error) {
        console.error(error);
        res.status(500).json({ error: 'Internal server error' });
    }
});
\`\`\`

效能最佳化建議

## 📊 效能最佳化

### 資料庫查詢

**使用 select 限制欄位**
\`\`\`javascript
// ❌ 不好：撈取所有欄位（包含大型欄位）
const users = await User.find();

// ✅ 好：只撈取需要的欄位
const users = await User.find().select('name email role');
\`\`\`

**使用 lean() 提升效能**
\`\`\`javascript
// ❌ 較慢：返回 Mongoose Document（有很多方法）
const users = await User.find();

// ✅ 較快：返回純 JavaScript 物件
const users = await User.find().lean();
\`\`\`

完成：30 分鐘的基礎 CLAUDE.md 完成！

🔄 現有專案的文檔化策略

如果你的專案已經運行多年，該如何建立 CLAUDE.md？

📋 評估與規劃（1 小時）

步驟 1：現狀評估

問自己這些問題：

## 專案現狀評估

### 基本資訊
- [ ] 專案啟動時間：____年
- [ ] 程式碼行數：約____行
- [ ] 開發團隊人數：____人
- [ ] 主要技術棧：________

### 文檔現狀
- [ ] 是否有 README.md？
- [ ] 是否有 Wiki 或其他文檔？
- [ ] 新人入職需要多久上手？____天
- [ ] 最常被問的問題是什麼？
  1. ________________
  2. ________________
  3. ________________

### 痛點識別
- [ ] 最複雜的部分是什麼？
- [ ] 最容易出錯的地方在哪？
- [ ] 哪些知識只有資深同事知道？

步驟 2：優先順序排定

根據評估結果，決定撰寫順序：

## CLAUDE.md 撰寫優先順序

### P0（最高優先）- 第一週完成
- [ ] 快速開始（環境建置）
- [ ] 專案概述（基本介紹）
- [ ] 最常見問題 FAQ

**目標**：新人能在 1 小時內啟動專案

---

### P1（高優先）- 第二週完成
- [ ] 程式架構（目錄結構、設計模式）
- [ ] 開發環境（Docker、IDE 設定）
- [ ] 常見開發任務（新增功能的步驟）

**目標**：新人能開始貢獻程式碼

---

### P2（中優先）- 第三週完成
- [ ] 測試流程
- [ ] 部署流程
- [ ] 開發規範

**目標**：新人能獨立完成完整的開發週期

---

### P3（低優先）- 持續補充
- [ ] 進階主題
- [ ] 效能最佳化
- [ ] 疑難排解

🎯 漸進式建立（3 週計畫）

第一週：建立骨架 + 快速開始

## 第一週任務清單

### Day 1-2：建立骨架（2 小時）
- [ ] 建立 CLAUDE.md 檔案
- [ ] 複製基礎模板（7 個核心章節）
- [ ] 提交第一版 PR

### Day 3-4：撰寫快速開始（4 小時）
- [ ] 記錄環境安裝步驟
- [ ] 撰寫啟動指令
- [ ] 提供測試帳號
- [ ] 撰寫驗證方法
- [ ] 請新人測試（最重要！）

### Day 5：撰寫常見問題（2 小時）
- [ ] 收集 Slack 中最常被問的問題
- [ ] 整理成 FAQ 格式
- [ ] 請團隊補充

**本週目標**：✅ 新人能在 1 小時內啟動專案

第二週：核心架構文檔

## 第二週任務清單

### Day 1-2：程式架構（4 小時）
- [ ] 繪製目錄結構樹
- [ ] 說明每個目錄的用途
- [ ] 標註重要檔案
- [ ] 提供範例

### Day 3：設計模式（2 小時）
- [ ] 記錄專案使用的設計模式
- [ ] 說明為什麼這樣設計
- [ ] 提供反模式警告

### Day 4-5：開發環境（4 小時）
- [ ] Docker 設定說明
- [ ] IDE 推薦插件
- [ ] Debug 設定
- [ ] 環境變數說明

**本週目標**：✅ 新人理解專案架構，能開始開發

第三週：測試與部署

## 第三週任務清單

### Day 1-2：測試流程（4 小時）
- [ ] 測試指令說明
- [ ] 如何撰寫測試
- [ ] 測試涵蓋率要求
- [ ] CI/CD 整合

### Day 3-4：部署流程（4 小時）
- [ ] 部署步驟
- [ ] 環境差異說明
- [ ] Rollback 流程
- [ ] 監控與告警

### Day 5：開發規範（2 小時）
- [ ] Coding Style
- [ ] Git 工作流程
- [ ] Code Review 標準
- [ ] PR Template

**本週目標**：✅ 新人能獨立完成開發到部署的完整流程

🤝 團隊協作撰寫

策略 1：每人認領一章節

## CLAUDE.md 撰寫分工

| 章節 | 認領人 | 預計完成 | 狀態 |
|:-----|:-------|:---------|:-----|
| 快速開始 | @張三 | Week 1 | ✅ 完成 |
| 專案概述 | @李四 | Week 1 | 🚧 進行中 |
| 開發環境 | @王五 | Week 2 | ⏳ 待開始 |
| 程式架構 | @趙六 | Week 2 | ⏳ 待開始 |
| 測試流程 | @張三 | Week 3 | ⏳ 待開始 |
| 部署流程 | @錢七 | Week 3 | ⏳ 待開始 |
| 開發規範 | @李四 | Week 3 | ⏳ 待開始 |

策略 2：Pair Writing

兩人一組協作撰寫：

資深 + 新人：資深提供知識，新人撰寫（確保新人視角）
前端 + 後端：跨領域協作，確保完整性

## Pair Writing 流程

### 會議時間：1 小時

**角色分工**：
- **Driver（撰寫者）**：實際打字撰寫文檔
- **Navigator（導航者）**：提供內容、審閱

**流程**：
1. Navigator 口述內容（10 分鐘）
2. Driver 撰寫並提問（30 分鐘）
3. 共同審閱修改（15 分鐘）
4. 提交 PR（5 分鐘）

**優點**：
- ✅ 知識轉移
- ✅ 確保可讀性（新人視角）
- ✅ 即時 Review

🔧 持續改進與版本管理

CLAUDE.md 不是一次性任務，需要持續維護。

📅 定期維護機制

每週維護（15 分鐘）

## 每週五例行檢查

### 檢查項目
- [ ] 檢視本週的 PR，是否有架構變更需要更新文檔
- [ ] 檢視 Slack #questions 頻道，是否有重複的問題
- [ ] 更新「最後更新日期」

### 快速更新
\`\`\`bash
# 自動檢查是否有程式碼變更但文檔未更新
git diff --name-only HEAD~7..HEAD | grep -E "\.js$|\.py$|\.php$"
\`\`\`

如果有重要檔案變更，檢查 CLAUDE.md 是否需要更新

每月回顧（1 小時）

## 每月文檔回顧會議

### 會議議程

1. **文檔使用情況分析**（15 分鐘）
   - 新人回饋：哪些章節最有幫助？
   - 常見誤解：哪些說明不夠清楚？
   - 遺漏內容：哪些資訊找不到？

2. **內容更新審查**（20 分鐘）
   - 過時內容標記
   - 新功能補充
   - 錯誤修正

3. **改進計畫**（15 分鐘）
   - 下個月的重點更新
   - 分工安排

4. **經驗分享**（10 分鐘）
   - 最佳實踐
   - 撰寫技巧

### 會議產出
- [ ] 更新任務清單
- [ ] 建立 GitHub Issues
- [ ] 排定負責人

🏷️ 語意化版本管理

使用 Semantic Versioning 管理 CLAUDE.md：

## CLAUDE.md 版本管理

### 版本號格式：v主版號.次版號.修訂號

### 版本號規則

**主版號 (Major)**：架構重大變更
- 範例：從 Monolithic 改為 Microservices
- 範例：資料庫從 MySQL 改為 PostgreSQL
- 範例：重構整個專案結構

**次版號 (Minor)**：新增重要章節
- 範例：新增「效能監控」章節
- 範例：新增「安全性指南」章節
- 範例：補充「Docker Compose 進階設定」

**修訂號 (Patch)**：小幅修正
- 範例：修正錯字
- 範例：更新指令範例
- 範例：補充說明

### 範例

\`\`\`
v1.0.0 (2025-01-01) - 初版發布
v1.1.0 (2025-02-15) - 新增測試流程章節
v1.1.1 (2025-02-20) - 修正 Docker 指令錯誤
v1.2.0 (2025-03-10) - 新增部署流程章節
v2.0.0 (2025-06-01) - 架構重構（Microservices）
\`\`\`

📊 文檔品質指標

追蹤 CLAUDE.md 的效果：

## CLAUDE.md 效果追蹤

### 量化指標

**新人 Onboarding 時間**
- 📊 Before CLAUDE.md：平均 5 天才能開始開發
- 📊 After CLAUDE.md：平均 1.5 天開始開發
- 📈 改善：70% ↓

**重複問題數量**
- 📊 Before：Slack #questions 每週 50+ 則重複問題
- 📊 After：每週 15 則重複問題
- 📈 改善：70% ↓

**文檔搜尋次數**
- 📊 CLAUDE.md 搜尋次數：每週 120 次
- 📊 內部 Wiki 搜尋次數：每週 30 次
- 📈 CLAUDE.md 成為主要文檔來源

### 質化指標

**新人回饋**（5 分量表）
- 🌟 文檔清晰度：4.6 / 5.0
- 🌟 範例實用性：4.8 / 5.0
- 🌟 問題解決率：4.5 / 5.0

**團隊回饋**
- ✅ 「終於不用重複回答相同問題了」- @資深工程師
- ✅ 「用 Claude 輔助開發超順暢」- @新人工程師
- ✅ 「Code Review 時可以直接引用 CLAUDE.md」- @Tech Lead

🌟 成功案例分享

讓我們看看不同類型專案的 CLAUDE.md 實作。

📱 案例 1：React Native App

專案背景：

📱 iOS + Android 雙平台 App
👥 團隊：5 人（3 前端 + 2 後端）
⏱️ 開發時程：6 個月

CLAUDE.md 重點：

## React Native 專案 CLAUDE.md 範例

### 專案特殊性

#### 跨平台差異處理

\`\`\`markdown
## 📱 平台差異處理

### iOS vs Android 差異

| 功能 | iOS | Android | 處理方式 |
|:-----|:----|:--------|:---------|
| 狀態列高度 | 需處理 notch | 固定高度 | 使用 `SafeAreaView` |
| 字體 | San Francisco | Roboto | 使用系統預設 |
| 導航動畫 | 右滑返回 | 按鈕返回 | React Navigation 自動處理 |
| 推播 | APNs | FCM | 使用 `@react-native-firebase/messaging` |

### 平台特定程式碼

\`\`\`javascript
// 使用 Platform.select
const styles = StyleSheet.create({
  container: {
    paddingTop: Platform.select({
      ios: 20,
      android: 0,
    }),
  },
});

// 使用平台特定檔案
// Button.ios.js
// Button.android.js
\`\`\`
\`\`\`

Claude 互動案例：

### Claude 如何協助開發

**案例 1：調整 iOS 狀態列**

\`\`\`
開發者：iOS 上狀態列被遮住了，怎麼修正？

Claude：根據 CLAUDE.md 的「平台差異處理」章節，
iOS 需要處理 notch 區域。建議使用 SafeAreaView：

\`\`\`javascript
import { SafeAreaView } from 'react-native';

function App() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      {/* 你的內容 */}
    </SafeAreaView>
  );
}
\`\`\`

這會自動處理 iOS 的 notch、狀態列和底部指示器。
\`\`\`

成效：

✅ 新人從 3 天縮短到 1 天上手
✅ 平台特定問題減少 80%
✅ Claude 能正確建議平台適配方案

🤖 案例 2：Machine Learning Pipeline

專案背景：

🧠 Python + TensorFlow + Kubernetes
👥 團隊：8 人（5 ML 工程師 + 3 DevOps）
📊 處理：每日 10TB 資料

CLAUDE.md 重點：

## ML Pipeline 專案 CLAUDE.md 範例

### 資料流程圖

\`\`\`markdown
## 🔄 資料處理 Pipeline

### 整體流程

\`\`\`
原始資料 (S3)
    ↓
[Data Ingestion] (Airflow)
    ↓
[Data Validation] (Great Expectations)
    ↓
[Feature Engineering] (Spark)
    ↓
[Model Training] (TensorFlow)
    ↓
[Model Evaluation] (MLflow)
    ↓
[Model Deployment] (Kubernetes)
    ↓
[Inference API] (FastAPI)
\`\`\`

### 各階段詳細說明

#### 1. Data Ingestion
- **工具**：Apache Airflow
- **頻率**：每小時
- **輸入**：S3 Bucket `raw-data/`
- **輸出**：S3 Bucket `processed-data/`
- **關鍵檔案**：`dags/data_ingestion.py`

\`\`\`python
# dags/data_ingestion.py
@dag(schedule_interval='@hourly')
def data_ingestion_dag():
    extract = extract_from_s3()
    transform = transform_data(extract)
    load = load_to_warehouse(transform)
\`\`\`
\`\`\`

模型訓練文檔：

### 如何訓練新模型

#### 步驟 1：準備資料集

\`\`\`bash
# 從 S3 下載最新資料
python scripts/download_dataset.py \
  --date 2026-01-07 \
  --output ./data/train/

# 驗證資料完整性
python scripts/validate_dataset.py \
  --path ./data/train/
\`\`\`

#### 步驟 2：設定訓練參數

\`\`\`yaml
# config/training_config.yaml
model:
  type: "transformer"
  layers: 12
  hidden_size: 768

training:
  batch_size: 32
  learning_rate: 0.0001
  epochs: 10

data:
  train_split: 0.8
  val_split: 0.1
  test_split: 0.1
\`\`\`

#### 步驟 3：啟動訓練

\`\`\`bash
# 本地訓練（測試用）
python train.py \
  --config config/training_config.yaml \
  --output ./models/experiment_001/

# Kubernetes 訓練（正式）
kubectl apply -f k8s/training-job.yaml
\`\`\`

#### 步驟 4：監控訓練進度

\`\`\`bash
# 查看訓練日誌
kubectl logs -f training-job-xxxxx

# 查看 TensorBoard
kubectl port-forward svc/tensorboard 6006:6006
# 訪問 http://localhost:6006
\`\`\`

#### 步驟 5：評估模型

\`\`\`bash
# 執行評估
python evaluate.py \
  --model ./models/experiment_001/ \
  --test_data ./data/test/

# 與 baseline 比較
python scripts/compare_models.py \
  --model_a ./models/baseline/ \
  --model_b ./models/experiment_001/
\`\`\`

Claude 互動案例：

### Claude 協助訓練流程

**案例：訓練新的 Sentiment 模型**

\`\`\`
開發者：我要訓練一個新的情緒分析模型，步驟是什麼？

Claude：根據 CLAUDE.md 的「模型訓練」章節，
完整流程如下：

1. 準備資料集
   \`\`\`bash
   python scripts/download_dataset.py --date 2026-01-07
   \`\`\`

2. 設定訓練參數（複製 config/training_config.yaml）
   - 調整 model.type 為適合的架構
   - 設定 batch_size（建議 32）

3. 啟動訓練
   - 本地測試：`python train.py --config config/training_config.yaml`
   - 正式訓練：`kubectl apply -f k8s/training-job.yaml`

4. 監控進度
   - TensorBoard: `kubectl port-forward svc/tensorboard 6006:6006`

5. 評估結果
   - 執行 `python evaluate.py --model ./models/xxx/`

需要我協助撰寫訓練腳本或設定檔嗎？
\`\`\`

成效：

✅ 訓練流程標準化
✅ 新 ML 工程師 2 天內能訓練第一個模型
✅ Claude 能正確指導模型訓練步驟

🎮 案例 3：遊戲後端 (Node.js + Redis + MongoDB)

專案背景：

🎮 即時多人遊戲後端
👥 團隊：6 人（4 後端 + 2 DevOps）
⚡ 需求：低延遲（<50ms）、高併發（10K CCU）

CLAUDE.md 重點：

## 遊戲後端 CLAUDE.md 範例

### 效能要求與最佳化

\`\`\`markdown
## ⚡ 效能最佳化指南

### 效能需求

| 指標 | 目標值 | 告警閾值 | 關鍵等級 |
|:-----|:-------|:---------|:---------|
| API 回應時間 | <50ms | >100ms | 🔴 P0 |
| WebSocket 延遲 | <20ms | >50ms | 🔴 P0 |
| 資料庫查詢 | <10ms | >30ms | 🟡 P1 |
| Redis 操作 | <5ms | >10ms | 🟡 P1 |
| 記憶體使用 | <1GB | >2GB | 🟢 P2 |

### Redis 快取策略

#### 玩家資料快取

\`\`\`javascript
// ✅ 好的實作：使用 Redis 快取
async function getPlayer(playerId) {
    // 1. 先查 Redis
    let player = await redis.get(`player:${playerId}`);

    if (player) {
        return JSON.parse(player);
    }

    // 2. Redis miss，查詢資料庫
    player = await Player.findById(playerId);

    // 3. 寫入 Redis（TTL 5 分鐘）
    await redis.setex(
        `player:${playerId}`,
        300,
        JSON.stringify(player)
    );

    return player;
}
\`\`\`

#### 排行榜快取

\`\`\`javascript
// 使用 Redis Sorted Set 實作排行榜
async function updateLeaderboard(playerId, score) {
    await redis.zadd('leaderboard:global', score, playerId);
}

async function getTopPlayers(limit = 10) {
    return await redis.zrevrange('leaderboard:global', 0, limit - 1);
}
\`\`\`

### 資料庫查詢最佳化

#### 使用索引

\`\`\`javascript
// 📊 重要索引（定義在 models/Player.js）
PlayerSchema.index({ userId: 1 });              // 單一索引
PlayerSchema.index({ level: -1, exp: -1 });     // 複合索引
PlayerSchema.index({ lastLogin: 1 }, {
    expireAfterSeconds: 7776000  // 90 天後自動刪除
});
\`\`\`

#### 避免 N+1 查詢

\`\`\`javascript
// ❌ 不好：N+1 查詢
async function getPlayersWithItems(playerIds) {
    const players = await Player.find({ _id: { $in: playerIds } });

    // 這裡會執行 N 次查詢！
    for (let player of players) {
        player.items = await Item.find({ playerId: player._id });
    }

    return players;
}

// ✅ 好：使用 aggregate
async function getPlayersWithItems(playerIds) {
    return await Player.aggregate([
        { $match: { _id: { $in: playerIds } } },
        {
            $lookup: {
                from: 'items',
                localField: '_id',
                foreignField: 'playerId',
                as: 'items'
            }
        }
    ]);
}
\`\`\`
\`\`\`

即時通訊架構：

### WebSocket 架構

\`\`\`markdown
## 🔌 WebSocket 通訊

### 連線流程

\`\`\`
Client → Load Balancer → WebSocket Server (Socket.io) → Redis Pub/Sub
                              ↓
                          MongoDB (持久化)
\`\`\`

### 訊息格式

\`\`\`typescript
// 統一的訊息格式
interface GameMessage {
    type: 'move' | 'attack' | 'chat' | 'event';
    playerId: string;
    timestamp: number;
    data: any;
}
\`\`\`

### 實作範例

\`\`\`javascript
// server.js
io.on('connection', (socket) => {
    // 玩家連線
    socket.on('player:join', async (data) => {
        const player = await getPlayer(data.playerId);
        socket.join(`room:${player.roomId}`);

        // 廣播給房間內其他玩家
        socket.to(`room:${player.roomId}`).emit('player:joined', {
            playerId: player.id,
            name: player.name
        });
    });

    // 玩家移動
    socket.on('player:move', async (data) => {
        // 驗證移動合法性
        if (!isValidMove(data)) {
            return socket.emit('error', { message: 'Invalid move' });
        }

        // 更新 Redis（不等待資料庫）
        await redis.hset(`player:${data.playerId}`, 'position', JSON.stringify(data.position));

        // 廣播給房間
        io.to(`room:${data.roomId}`).emit('player:moved', data);

        // 非同步寫入資料庫
        updatePlayerPosition(data.playerId, data.position).catch(console.error);
    });
});
\`\`\`

### 效能最佳化

**1. 減少廣播次數**

\`\`\`javascript
// ❌ 不好：每次移動都廣播
socket.on('player:move', (data) => {
    io.to(`room:${data.roomId}`).emit('player:moved', data);
});

// ✅ 好：節流（Throttle），每 50ms 最多廣播一次
const throttledBroadcast = _.throttle((roomId, data) => {
    io.to(`room:${roomId}`).emit('player:moved', data);
}, 50);

socket.on('player:move', (data) => {
    throttledBroadcast(data.roomId, data);
});
\`\`\`

**2. 使用 Binary Protocol**

\`\`\`javascript
// 對於高頻訊息，使用 MessagePack 而非 JSON
const msgpack = require('msgpack-lite');

socket.on('player:move', (data) => {
    const packed = msgpack.encode(data);
    socket.broadcast.emit('player:moved', packed);
});
\`\`\`
\`\`\`

Claude 互動案例：

### Claude 協助效能最佳化

**案例：排行榜效能問題**

\`\`\`
開發者：排行榜 API 很慢，經常超過 200ms，怎麼優化？

Claude：根據 CLAUDE.md 的「效能最佳化」章節，
排行榜應該使用 Redis Sorted Set。讓我檢查目前的實作...

[檢查程式碼後]

發現問題：目前使用 MongoDB 排序，每次都要全表掃描。

建議改用 Redis：

\`\`\`javascript
// 更新分數時寫入 Redis
async function updatePlayerScore(playerId, score) {
    // 1. 更新 MongoDB（非同步）
    Player.updateOne({ _id: playerId }, { score }).exec();

    // 2. 更新 Redis Sorted Set（同步）
    await redis.zadd('leaderboard:global', score, playerId);
}

// 取得排行榜（從 Redis 讀取，極快）
async function getLeaderboard(limit = 100) {
    const playerIds = await redis.zrevrange('leaderboard:global', 0, limit - 1, 'WITHSCORES');
    // 回應時間 < 5ms
    return playerIds;
}
\`\`\`

預期改善：
- Before: 200ms+
- After: <5ms（改善 97.5%）
\`\`\`

成效：

✅ API 回應時間從 150ms → 30ms
✅ 支援 10K 同時線上玩家
✅ Claude 能正確建議效能最佳化方案

📊 ROI 量化分析

CLAUDE.md 的投資報酬率計算。

## 💰 CLAUDE.md 投資報酬率

### 投入成本

**初次建立**（3 週）
- 第一週：2 小時/人 × 5 人 = 10 小時
- 第二週：4 小時/人 × 5 人 = 20 小時
- 第三週：4 小時/人 × 5 人 = 20 小時
- **小計：50 小時**

**持續維護**（每月）
- 每週檢查：15 分鐘/週 × 4 週 = 1 小時
- 每月回顧：1 小時
- 內容更新：2 小時
- **小計：4 小時/月**

**年度總成本**
- 初次建立：50 小時
- 維護（12 個月）：48 小時
- **總計：98 小時/年**

---

### 節省成本

**新人 Onboarding**
- Before：5 天 × 8 小時 = 40 小時/人
- After：1.5 天 × 8 小時 = 12 小時/人
- **節省：28 小時/人**

假設每年 4 位新人：28 × 4 = **112 小時/年**

**減少重複問題**
- Before：每週 50 則 × 5 分鐘 = 250 分鐘/週
- After：每週 15 則 × 5 分鐘 = 75 分鐘/週
- **節省：175 分鐘/週 = 152 小時/年**

**減少 Code Review 時間**
- 引用 CLAUDE.md 標準，減少來回溝通
- **節省：約 50 小時/年**

**提升開發效率**
- 使用 Claude 輔助開發，提升 20% 效率
- 假設團隊 6 人，每人每週工作 40 小時
- 6 × 40 × 0.2 × 52 = **2,496 小時/年**

---

### ROI 計算

**總節省時間**
- 112（新人）+ 152（問題）+ 50（Review）+ 2,496（效率）
- = **2,810 小時/年**

**ROI**
- (2,810 - 98) / 98 × 100%
- = **2,767%**

**回本時間**
- 98 小時 ÷ (2,810 / 12 個月)
- = **0.42 個月（約 12.6 天）**

### 非量化效益

- 🎯 **知識保存**：資深同事離職不再帶走知識
- 🚀 **決策品質**：Claude 基於完整資訊給建議
- 😊 **工作滿意度**：減少挫折感，提升開發體驗
- 🤝 **團隊協作**：統一的資訊來源，減少誤解

🎓 總結與行動建議

✅ 核心要點回顧

經過三篇系列文章，你已經掌握了：

第一篇：基礎概念與核心章節

✅ CLAUDE.md 的本質與價值
✅ 7 個核心章節的架構
✅ 如何讓 AI 理解專案

第二篇：複雜架構的文檔化

✅ 多租戶架構的說明技巧
✅ Docker 環境的完整文檔
✅ 測試自動化的實作方法

第三篇：進階技巧與實戰

✅ 視覺設計與文檔優化
✅ 團隊協作的最佳實踐
✅ 從零開始的實戰演練
✅ 不同類型專案的案例

🚀 立即行動清單

如果你現在就想開始，按照這個順序進行：

Week 1：快速啟動

### Day 1（30 分鐘）
- [ ] 在專案根目錄建立 CLAUDE.md
- [ ] 複製基礎模板（7 個核心章節）
- [ ] 提交第一版 commit

### Day 2-3（2 小時）
- [ ] 撰寫「快速開始」章節
- [ ] 記錄啟動指令
- [ ] 提供測試帳號
- [ ] 請新人實測

### Day 4-5（2 小時）
- [ ] 撰寫「專案概述」
- [ ] 列出技術棧
- [ ] 標註重要特性
- [ ] 說明與其他專案的差異

**Week 1 目標**：✅ 新人能在 1 小時內啟動專案

Week 2：核心文檔

### Day 1-2（4 小時）
- [ ] 撰寫「程式架構」
- [ ] 繪製目錄結構
- [ ] 說明設計模式
- [ ] 提供開發範例

### Day 3（2 小時）
- [ ] 撰寫「開發環境」
- [ ] Docker 設定
- [ ] IDE 推薦
- [ ] 環境變數說明

### Day 4-5（2 小時）
- [ ] 收集常見問題
- [ ] 撰寫 FAQ
- [ ] 補充疑難排解

**Week 2 目標**：✅ 新人理解架構，能開始開發

Week 3：測試與優化

### Day 1-2（2 小時）
- [ ] 撰寫「測試流程」
- [ ] 提供測試腳本
- [ ] 說明 CI/CD

### Day 3-4（2 小時）
- [ ] 撰寫「部署流程」
- [ ] 環境差異說明
- [ ] Rollback 步驟

### Day 5（1 小時）
- [ ] 整體審閱
- [ ] 修正錯誤
- [ ] 請團隊 Review

**Week 3 目標**：✅ 完整的 CLAUDE.md 上線

📚 延伸資源

官方文檔

社群資源

Awesome CLAUDE.md - 精選範例集
CLAUDE.md Template - 各種專案模板

本系列文章

💬 持續交流

問題與建議

📧 Email：你的 Email
💬 Discord：你的 Discord
🐦 Twitter：你的 Twitter

分享你的 CLAUDE.md

如果你建立了優秀的 CLAUDE.md，歡迎分享！
我會在未來的文章中引用（經你同意後）

🎉 結語

恭喜你完成了整個系列！

CLAUDE.md 不只是一份文檔，它是：

🧠 團隊知識庫：保存集體智慧
🤖 AI 溝通橋樑：讓 AI 真正理解你的專案
🚀 效率倍增器：減少重複勞動
🎓 最佳教材：新人學習的第一手資料

記住：

✅ 從小處開始，持續改進
✅ 注重實用性，而非完美性
✅ 鼓勵團隊貢獻
✅ 定期維護更新

現在，開始撰寫屬於你專案的 CLAUDE.md 吧！

如果這個系列對你有幫助，歡迎分享給更多的開發者 🙌

📎 相關連結：

祝你與 AI 的協作愉快！✨