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 & 3：ML Pipeline 與遊戲後端

除了 App 專案，CLAUDE.md 同樣適用於其他類型專案，骨架一樣（專案概述 / 架構 / 規範），差別在「特殊章節」：

ML Pipeline 專案（每日處理 10TB 資料）：重點放在資料流程圖（raw → 清洗 → 特徵 → 訓練 → 部署每段的輸入輸出格式）、各階段 schema、以及 pipeline 失敗時的 retry / 回補策略——讓 AI 知道「資料長什麼樣、卡住怎麼辦」。
遊戲後端專案（低延遲 <50ms、高併發 10K CCU）：重點放在效能約束（哪些操作有延遲預算）、WebSocket 通訊協定格式、以及「哪些寫法會破壞效能」的禁區清單——讓 AI 寫程式時自動考慮效能。

共同原則：App 寫平台差異、ML 寫資料流程、遊戲寫效能約束——寫你的專案最容易出錯的那一塊就對了。

💰 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：快速啟動

```markdown
### 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 的協作愉快！✨