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

系列文章：本文是 CLAUDE.md 完整指南系列的第一篇，專注於基礎概念與核心章節規劃。

🎯 前言：當 AI 遇上 Legacy 專案

你是否有過這樣的經驗？

向 Claude Code 求助時，它給出的建議總是偏離你的專案架構。你花了大把時間解釋「我們用的是 PHP 7.4」、「這是多租戶架構」、「請不要動這個舊的 DB 類別」…每次對話都像在重新教育一個新同事。

如果你正在維護一個 Legacy 專案，或是想讓 Claude Code 更深入理解你的複雜系統，那麼這篇文章就是為你準備的。

💡 問題場景：為什麼需要 CLAUDE.md？

場景一：重複解釋的困境

你：幫我優化這個資料庫查詢
Claude：建議使用 Eloquent ORM 和 Laravel 的查詢建構器...
你：😤 我們用的是原生 PHP 7.4 + PDO，沒有 Laravel！

場景二：架構不匹配

你：幫我新增一個表單列印功能
Claude：建議使用 React + Tailwind 建立現代化 UI...
你：😫 這是傳統 PHP 專案，用的是 Server-side rendering！

場景三：危險的建議

你：幫我修改這個 Session 變數
Claude：建議重構 Session 管理系統，使用 JWT...
你：😱 這會影響整個系統！我們有 50+ 個舊模組依賴這個 Session 結構！

核心問題：Claude Code 不了解你的專案脈絡。

📖 CLAUDE.md 是什麼？

CLAUDE.md 是一個專門為 Claude Code 設計的專案說明文件，放在專案根目錄。當你啟動 Claude Code 時，它會自動讀取這個檔案，理解你的專案架構、開發規範、技術限制等資訊。

📊 與一般文檔的差異

特性一般 READMECLAUDE.md
目標讀者人類開發者AI（Claude Code）
內容重點安裝步驟、功能介紹架構細節、技術限制、開發模式
更新頻率不定期隨專案演進持續更新
深度概述為主包含大量實戰細節
技術細節簡略詳盡（如路徑解析規則、變數作用域）

✨ 實際效果對比

❌ 沒有 CLAUDE.md 之前

  • 每次都要解釋技術棧
  • AI 建議常常不適用
  • 需要多次來回溝通才能完成任務

✅ 有了 CLAUDE.md 之後

  • Claude 自動理解專案架構
  • 建議符合現有技術棧
  • 主動避開已知的技術限制
  • 大幅減少溝通成本

🏗️ CLAUDE.md 的核心章節規劃

一份完整的 CLAUDE.md 應該包含以下 7 個核心章節：

1️⃣ 目錄（必備）

目的：讓 Claude 快速找到需要的資訊

## 📚 目錄

- [⚡ 快速開始](#-快速開始)
- [📋 專案概述](#-專案概述)
- [🛠️ 開發環境](#️-開發環境)
- [🧪 測試與自動化](#-測試與自動化)
- [🏗️ 程式架構](#️-程式架構)
- [📝 開發規範](#-開發規範)
- [🚀 進階主題](#-進階主題)

2️⃣ 快速開始（必備）

目的：提供最快速的啟動方式，讓 Claude 知道如何測試你的專案

## ⚡ 快速開始

### 1. 啟動 Docker 環境

\`\`\`bash
cd Docker
docker-compose up -d

# 檢查容器狀態
docker ps
\`\`\`

### 2. 測試帳號

| 項目 | 值 |
|------|-----|
| **URL** | http://localhost |
| **帳號** | demo |
| **密碼** | Demo@123 |
| **資料庫** | demo-org-2（包含測試資料）|

💡 為什麼重要：Claude 可以快速驗證修改是否正確，而不是猜測如何測試。

3️⃣ 專案概述（必備）

目的：用 3-5 個重點說明專案的核心特性

## 📋 專案概述

這是一個基於 **PHP 7.4** 的企業管理系統，使用 Docker 容器化部署，支援多機構資料庫架構。

### 核心特點

- 🏥 **多模組系統**: ModuleA、ModuleB、ModuleC 等業務功能
- 🗄️ **多租戶架構**: 每個機構使用獨立資料庫（`demo-org-{id}`）
- 🐳 **Docker 部署**: Nginx + PHP-FPM + MySQL 三層架構
- 📊 **批次輸出**: TypeA 表單、TypeB 表單、TypeC 資料批次輸出

🎯 關鍵訊息：

  • ✅ PHP 7.4（不是 8.x）
  • ✅ 多租戶架構（每個機構獨立資料庫）
  • ✅ 傳統三層架構（不是微服務）

4️⃣ 開發環境（必備）

目的：詳細說明如何建立開發環境

重點範例 - Docker 服務架構：

### Docker 環境設定

基於 `docker-compose.yml` 的三層架構：

**1. nginx (Web Server)**
- Image: `nginx:latest`
- Port: 80:80
- 設定檔: `Docker/nginx/default.conf`

**2. php7-fpm (PHP-FPM)**
- Image: `somosyampi/docker-php-fpm:7.4-xdebug`
- Port: 9000 (內部使用)
- PHP 設定:
  - `memory_limit = 128M`
  - `max_execution_time = 30`

**3. mysql (資料庫)**
- Image: `mysql:5.7`
- Port: 3306:3306
- 認證資訊:
  - Root 密碼: `rootpass`
  - 應用帳號: `dbuser` / `dbpass`

💡 為什麼詳細：當 Claude 建議修改設定時，它需要知道確切的檔案位置和現有配置。

5️⃣ 程式架構（必備）⭐

這是最關鍵的章節！ 說明你的程式碼組織方式、路由機制、資料庫架構等。

實戰範例 - PHP Include 路徑解析：

### PHP Include 路徑解析與變數作用域

#### ⚠️ Include 路徑解析規則

**重要**: PHP 的 `include` 語句使用相對路徑時，是相對於**當前執行檔案所在的目錄**解析。

**範例**:
\`\`\`
檔案位置: AppSystem/module_a/print/batch/formview.php
Include語句: include("form3.php")
實際解析: AppSystem/module_a/print/batch/form3.php  ← 同目錄
\`\`\`

**常見錯誤**:
- ❌ 認為 `include("form3.php")` 會搜尋整個專案
- ✅ 相對路徑從當前檔案目錄開始解析（同目錄優先）

💡 為什麼寫得這麼細：這是 Legacy PHP 專案常見的陷阱，Claude 需要明確知道路徑解析規則，才不會給出錯誤建議。

6️⃣ 開發規範（選用）

目的：包含 Git 提交格式、編碼規範、技術限制等

實戰範例 - 技術限制：

### 技術限制與相容性

#### MySQL 群組查詢相容性

系統設定 MySQL 為相容模式以支援舊版 GROUP BY 語法：
- `docker-compose.yml` 中設定：`command: --sql_mode=""`
- 解決 SQLSTATE[42000] 群組查詢錯誤
- 允許 SELECT 不在 GROUP BY 中的欄位（非標準 SQL）

#### PHP 版本

- 使用 PHP 7.4（`somosyampi/docker-php-fpm:7.4-xdebug`）
- 程式碼依賴 PHP 7.x 語法，升級需謹慎測試

💡 為什麼重要：明確告訴 Claude「不要建議升級 PHP 8」、「SQL 查詢不需要完全符合標準」。

7️⃣ 測試與自動化（選用但推薦）

目的：記錄自動化測試或特殊的測試流程

實戰範例 - 使用 curl 測試：

### 使用 curl 測試批次輸出

#### 完整模擬真實流程

\`\`\`bash
# 步驟 1: 建立 session（設定登入狀態）
curl -s -c /tmp/cookies.txt "http://localhost/_dev_login.php" > /dev/null

# 步驟 2: 測試批次輸出
curl -b /tmp/cookies.txt -X POST \
  -d "all_records=3" \
  -d "form_serNo[]=form_typeA_12a" \
  -d "start_date=2020/01/01" \
  -d "end_date=2025/12/31" \
  "http://localhost/module_a/export.php?mod=batch&func=formview&id=3&type=2"
\`\`\`

💡 為什麼有用：Claude 可以直接執行這些命令來驗證功能，而不需要你手動測試。

📚 實戰案例：Legacy PHP 專案的 CLAUDE.md

讓我分享一個真實案例：一個運行了 10 年的 PHP 7.4 企業系統。

🏢 專案背景

技術棧 PHP 7.4 + MySQL 5.7 + Docker
架構 多租戶（每個機構獨立資料庫）
規模 50+ 個模組，數百個 PHP 檔案
挑戰 • 無法升級 PHP 版本（相依性問題）
• 複雜的 Session 管理
• 舊版 MySQL 群組查詢語法
• 多層級的檔案 include 結構

❌ 撰寫前的困境

在撰寫 CLAUDE.md 之前，我每次請 Claude 幫忙都會遇到：

  1. 建議升級技術棧：「建議升級到 PHP 8.3…」
  2. 架構不匹配：「建議使用 Laravel 的 Eloquent ORM…」
  3. 危險的重構：「建議重寫 Session 管理系統…」
  4. 路徑錯誤：不理解相對路徑的解析規則

✍️ 撰寫 CLAUDE.md 的過程

我花了約 4 小時，撰寫了一份 760 行的 CLAUDE.md，包含：

📋 1. 快速開始（100 行）
  • Docker 啟動命令
  • 測試帳號
  • 開發登入工具說明
  • curl 測試範例
📋 2. 專案概述（50 行）
  • 核心特點（多模組、多租戶、批次輸出）
  • 技術棧明確說明（PHP 7.4、MySQL 5.7）
📋 3. 開發環境（200 行）
  • Docker 三層架構詳細說明
  • MySQL 自訂設定（關閉嚴格模式）
  • XDebug 配置（包含 host.docker.internal 設定）
  • 資料庫管理工具（下載、匯入、遷移）
📋 4. 程式架構（250 行）⭐
  • 目錄結構
  • 路由機制（?mod=xxx&func=yyy）
  • 關鍵：PHP Include 路徑解析規則
  • 關鍵：變數作用域繼承說明
  • 資料庫連接架構（DBPDO.php）
  • 權限系統架構（多層級表結構）
📋 5. 測試與自動化（100 行）
  • 批次輸出測試完整流程
  • curl 命令範例（可直接執行）
  • POST 參數說明
📋 6. 開發規範（60 行）
  • Git 提交格式範例
  • 關鍵：技術限制明確說明
    • MySQL 相容模式（--sql_mode=""）
    • PHP 7.4 不可升級
    • 不要使用 Laravel/Symfony

✅ 撰寫後的效果

有了完整的 CLAUDE.md 之後，Claude Code 的表現完全改變：

案例 1：新增表單輸出功能

我：幫我新增一個 TypeB-01 表單的批次輸出功能

Claude（自動理解）：
✅ 知道要在 `module_a/export/batch/` 目錄新增檔案
✅ 使用既有的 Session 變數（`$_SESSION['mcareDBno']`）
✅ 遵循現有的 POST 參數格式（`all_records`, `form_serNo[]`）
✅ 使用 DBPDO.php 而不是建議用 Eloquent
✅ 提供可直接執行的 curl 測試命令

案例 2：修改資料庫查詢

我：這個 SQL 查詢有問題，幫我看看

Claude（避開陷阱）：
✅ 不會建議「符合標準 SQL 的 GROUP BY 寫法」
✅ 知道系統設定為相容模式（`--sql_mode=""`）
✅ 保持現有的查詢風格

案例 3：除錯 XDebug 連接問題

我：XDebug 無法連接 VS Code

Claude（直接定位）：
✅ 檢查 `Docker/fpm-conf/docker-php-ext-xdebug.ini`
✅ 確認 `xdebug.client_host=host.docker.internal`
✅ 提供完整的 launch.json 配置
✅ 知道日誌位置在 `/tmp/xdebug.log`

💰 投資報酬率

  • 撰寫時間：4 小時
  • 節省時間：每次協作省下 10-15 分鐘的解釋時間
  • 頻率：平均每天使用 Claude Code 5-10 次
  • 回報週期：約 2-3 天就回本了

更重要的是：溝通品質大幅提升，不再需要反覆澄清基本概念。

🔄 效果展示：Before & After

Before（沒有 CLAUDE.md）

我：幫我優化這個批次輸出功能的載入速度

Claude：建議使用 React 實作前端分頁載入...

我：這是 Server-side rendering，沒有前端框架

Claude：那建議使用 Laravel 的 Eager Loading...

我：😤 我們沒有用 Laravel！是原生 PHP + PDO

Claude：理解了，建議重構資料庫查詢使用 JOIN...

我：查詢已經用 JOIN 了，問題是載入時間長

Claude：可以提供完整的程式碼嗎？

（來回 5 輪才進入正題）

After（有了 CLAUDE.md）

我：幫我優化這個批次輸出功能的載入速度

Claude：我看了你的 CLAUDE.md，這是多租戶架構的批次輸出功能。
根據程式架構章節，我知道：
1. 使用 DBPDO.php 連接資料庫
2. 批次輸出在 module_a/export/batch/ 目錄
3. 可以用 curl 測試（已知測試方法）

建議從以下方向優化：
1. 檢查 PDO 查詢是否使用了索引
2. 確認是否可以減少 SQL 查詢次數（目前每個表單一次查詢）
3. 考慮在 `my-custom.cnf` 增加查詢快取設定

需要我檢查具體的程式碼嗎？

（一次到位）

🎯 撰寫 CLAUDE.md 的最佳實踐

1. 從問題出發

不要一開始就想寫「完美」的文檔，而是記錄每次與 Claude 溝通時遇到的問題：

  • Claude 誤解了什麼？
  • 你反覆解釋了什麼？
  • 哪些技術細節需要明確說明？

💡 實戰技巧：準備一個「待補充清單」，每次遇到溝通問題就記下來。

2. 保持更新

CLAUDE.md 不是一次性文檔，應該隨專案演進持續更新：

  • 新增功能模組 → 更新目錄結構
  • 改變開發流程 → 更新測試章節
  • 發現新的技術陷阱 → 補充到架構章節

💡 實戰技巧：在 Git commit message 中提醒自己更新 CLAUDE.md。

3. 用 AI 理解的語言

記住，讀者是 AI，不是人類：

✅ 好的寫法

  • 明確的規則和限制
  • 具體的範例
  • 完整的指令
  • 可執行的程式碼

❌ 壞的寫法

  • 模糊的描述
  • 「盡量」、「通常」
  • 需要猜測的參數
  • 抽象的概念

4. 結構化與分層

使用清晰的 Markdown 標題層級：

## 🏗️ 程式架構         ← H2: 主要章節

### 核心目錄結構        ← H3: 子主題

#### 主要進入點         ← H4: 詳細說明

💡 為什麼重要：Claude 可以快速定位到需要的資訊。

5. 包含可執行的範例

不要只寫「使用 curl 測試」，而是提供完整可執行的命令：

# ✅ 好的範例（可直接複製執行）
curl -s -c /tmp/cookies.txt "http://localhost/_dev_login.php" > /dev/null
curl -b /tmp/cookies.txt -X POST \
  -d "all_records=3" \
  "http://localhost/module_a/export.php?mod=batch"

# ❌ 壞的範例（需要猜測參數）
使用 curl 發送 POST 請求到 export.php 端點

❓ 常見問題

Q1: CLAUDE.md 要寫多長？

答：沒有標準長度，取決於專案複雜度。我的經驗：

專案類型建議行數範例
簡單專案200-300 行Next.js SPA
中等專案400-500 行傳統 MVC 架構
複雜專案700-1000 行Legacy + 多租戶

Q2: 需要一次寫完嗎？

答：不需要！建議採用迭代式撰寫：

  1. 第一版（1 小時）：快速開始 + 專案概述 + 基本架構
  2. 第二版（隨需補充）：遇到問題就補充對應章節
  3. 第三版（定期整理）：每月整理一次，刪除過時內容

Q3: 會不會洩漏機密資訊？

答：如果是公司專案，建議使用「去識別化對照表」來管理敏感資訊的替換。

📋 使用 CLAUDE_ANONYMIZATION_MAP.md

建立一個不提交到版本控制的對照表文件：

# CLAUDE_ANONYMIZATION_MAP.md

## 資料庫相關
| 原始值 | 替換值 | 類型 |
|--------|--------|------|
| `realdb-12345` | `demo-org-1` | 資料庫名稱 |
| `realdb-67890` | `demo-org-2` | 資料庫名稱 |

## 帳號密碼
| 原始值 | 替換值 | 類型 |
|--------|--------|------|
| `admin_real` | `demo` | 測試帳號 |
| `RealP@ssw0rd!` | `Demo@123` | 測試密碼 |

## 專案名稱
| 原始值 | 替換值 | 類型 |
|--------|--------|------|
| `RealProjectName` | `AppSystem` | 專案名稱 |
| `real_module_name` | `module_a` | 模組名稱 |

## 客戶名稱
| 原始值 | 替換值 | 類型 |
|--------|--------|------|
| `客戶甲公司` | `OrganizationA` | 客戶名稱 |
| `客戶乙公司` | `OrganizationB` | 客戶名稱 |

加入 .gitignore：

# .gitignore
CLAUDE_ANONYMIZATION_MAP.md

✅ 去識別化原則

  • ✅ 替換識別性資訊：資料庫名、客戶名稱、真實帳號
  • ✅ 保留技術細節：Docker 設定、PHP 版本、程式架構
  • ✅ 使用有意義的代稱：demo-org-1 比 db1 更容易理解
  • ✅ 保持一致性：同一個原始值永遠使用同一個替換值

📂 完整範例

完整的去識別化對照表範例請參考：CLAUDE_ANONYMIZATION_MAP.md

Q4: CLAUDE.md 與 README.md 的關係？

答：兩者互補，不衝突：

文檔目標內容重點
README.md給人類看專案簡介（安裝、使用、貢獻指南）
CLAUDE.md給 AI 看深度技術文檔（架構、限制、開發模式）

可以在 README.md 中提到「AI 協作請參考 CLAUDE.md」。

🎉 下一步

恭喜你讀完了本系列的第一篇！現在你應該理解了：

  • ✅ 為什麼需要 CLAUDE.md
  • ✅ CLAUDE.md 的 7 個核心章節
  • ✅ Legacy 專案的實戰案例
  • ✅ 撰寫的最佳實踐

🔜 下一篇預告

在下一篇文章中，我會深入探討：

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

  • 🎯 如何描述複雜的多租戶架構

    • Session 動態切換資料庫的實作細節
    • 多層級權限系統的文檔化
    • 資料庫遷移工具的說明

  • 🐳 Docker 環境的完整文檔化

    • 三層架構的詳細說明
    • XDebug 除錯設定（跨平台相容）
    • 常見問題與解決方案

  • 🧪 測試流程自動化

    • 使用 curl 模擬完整登入流程
    • 批次輸出的測試腳本
    • 如何讓 Claude 自動執行測試

  • 📊 實際案例解析

    • 760 行 CLAUDE.md 的完整拆解
    • 每個章節的撰寫思路
    • 常見陷阱與解決方案

📎 相關資源：

如果你覺得這篇文章有幫助，歡迎分享給正在維護 Legacy 專案的朋友！

有任何問題或想法，歡迎在下方留言討論 👇