AI 時代的團隊設計模式：從 v0 到 v3 的演進與實踐

當 AI 能寫代碼，團隊組織方式必須重新設計

---

1. 問題定義：傳統團隊組織在 AI 時代的困境

1.1 固定職位 vs 動態需求的矛盾

傳統的團隊組建方式：

1. 寫 JD (Job Description)
2. 招聘符合條件的人
3. 人到職後開始工作
4. 這個人從頭做到尾

假設：職位固定，需求穩定

現實：

• 專案初期需要快速建 prototype → 需要「會快速驗證想法」的能力
• 專案中期需要穩定架構 → 需要「擅長系統設計」的能力
• 專案後期需要優化效能 → 需要完全不同的專長

問題：同一個「Senior React Developer」無法在所有階段都是最適合的

1.2 AI 工具帶來的新挑戰

當 Claude Code、GitHub Copilot、Cursor 可以寫代碼時：

• 工程師的價值不再是「會寫代碼」
• 團隊需要的不是「會 React 的人」，而是「能調度 AI+人 來完成 Frontend 任務的角色」
• 資源配置從「招聘」變成「設計角色組合」

核心困境：

我們還在用工業時代的「固定職位」邏輯，組織 AI 時代的「動態資源」團隊

1.3 現有方案的不足

方案 A：增加人力

❌ 成本高（年薪 x N 人）
❌ 招聘慢（平均 2-3 個月）
❌ 不靈活（人到職後很難調整）

方案 B：外包

❌ 溝通成本高
❌ 品質難控管
❌ 知識無法留存

方案 C：全端工程師

⚠️ 要求過高（前端+後端+DevOps）
⚠️ 難招聘（薪資成本高）
⚠️ 效率未必最佳（什麼都會 ≠ 什麼都專精）

缺少的是什麼？
→ 一套能讓「人」與「AI」協作，且可版本控制、可模組化、可重用的團隊設計方法

---

2. 方案說明：團隊設計模式演進（v0 → v3）

2.1 設計思維轉變

從「找人」到「設計角色」：

傳統思維：我需要一個會 React 的人

新思維：Frontend 角色需要哪些能力模組？
  → UI 組件開發：AI 可以做 80%
  → 狀態管理設計：需要人來思考
  → 效能優化：人+AI 協作效果最好
  → Code Review：AI 先篩，人做最終把關

最終配置：
  1 個懂架構的人（負責設計與決策）
  + 2 個 AI coding agents（負責實作）
  + 1 個 AI review agent（負責品質把關）

關鍵洞察：

團隊設計就是軟體架構設計，只是運算單元從「函式」變成了「人或 AI」

---

2.2 v0: Single Human Dev（過去）

架構：

you/
├── brain/
│   ├── frontend-knowledge
│   ├── backend-knowledge
│   └── devops-knowledge
└── project/
    └── src/

特性：

• 所有技能都在腦袋裡
• 沒有外部配置
• 一個人，一個專案

適用場景：

• 個人 side project
• 早期 prototype
• 單人創業初期

優點：
✅ 自由、快速
✅ 沒有溝通成本
✅ 決策速度快

痛點：
❌ 無法規模化（你只有一個人）
❌ 知識無法傳承（離職就帶走了）
❌ 容易重複造輪子（每個專案都重新設計）
❌ 生病或休假時專案停擺

---

2.3 v1: Mono Repo（入門）

架構：

my-project/
├── src/
├── tests/
└── .claude/
    ├── agents/
    │   ├── frontend-dev.md
    │   └── backend-dev.md
    └── skills/
        ├── react-expert/
        └── api-design/

特性：

• AI 配置與專案程式碼在一起
• agents 和 skills 都在 .claude/ 目錄
• 用 markdown 定義 agent 職責

適用場景：

• 小團隊（< 5人）
• 單一專案
• 初次嘗試 AI 協作

優點：
✅ 簡單直接
✅ AI 配置與程式碼一起，容易管理
✅ 適合快速啟動

痛點：
❌ 專案變大後難以管理
❌ .claude/ 的配置無法在其他專案重用
❌ 多人協作時容易衝突（都改同一個 agent.md）
❌ 每個新專案都要重新配置

技術實作：

# .claude/agents/frontend-dev.md

## Responsibilities
- 實作 React 組件
- 狀態管理設計
- API 串接

## Skills
- react-expert
- api-design

## Workflow
1. 收到 UI 需求
2. 設計組件結構
3. 實作並測試
4. 提交 PR

---

2.4 v2: Sub-module（進階）

架構：

my-project/
├── src/
├── tests/
└── ai-plugins/  ← git submodule
    └── .claude/
        ├── agents/
        └── skills/

特性：

• 將 AI 配置作為 git submodule 引入
• 多個專案可以共用同一個 submodule
• 可以版本控制 AI 配置

適用場景：

• 中型團隊
• 需要跨專案重用 AI 配置
• 有專人維護 AI 配置

優點：
✅ AI 配置可重用（多個專案共用）
✅ 可以版本控制（更新 submodule 版本）
✅ 統一管理（一個地方更新，所有專案受益）

痛點：
❌ git submodule 管理複雜

• git submodule update --init
• git submodule sync
• 容易忘記 init
  ❌ submodule 更新需要手動 commit
  ❌ 新人容易踩坑（為什麼 .claude/ 是空的？）
  ❌ CI/CD 需要特別處理 submodule

技術實作：

# 1. 建立共用的 AI 配置 repo
git init ai-plugins

# 2. 在專案中加入 submodule
cd my-project
git submodule add https://github.com/company/ai-plugins.git

# 3. 更新 AI 配置
cd ai-plugins
git pull origin main
cd ..
git add ai-plugins
git commit -m "chore: update AI plugins"

# 4. 新人 clone 後需要
git clone --recurse-submodules <project-url>
# 或
git submodule update --init --recursive

常見問題：

問題	原因	解法
.claude/ 是空的	沒有 init submodule	git submodule update --init
submodule 版本不對	沒有更新 submodule	git submodule update --remote
CI 找不到 agents	CI 沒設定 submodule	加入 submodules: true

---

2.5 v3: Solutions (Multi-Repo)（推薦）

架構：

Solutions/
├── ProjectA/ (Web Frontend)
│   └── .claude/ (project-specific)
│       ├── agents/
│       └── skills/ (部分從 AIPlugins 複製)
│
├── ProjectB/ (API Backend)
│   └── .claude/ (project-specific)
│
├── ProjectC/ (Data Service)
│   └── .claude/ (project-specific)
│
└── AIPlugins/ (Shared Templates)
    ├── Templates/
    │   ├── .skills/
    │   │   ├── frontend-expert/
    │   │   ├── backend-expert/
    │   │   ├── process-manager/
    │   │   └── learning-agent/
    │   └── .teams/
    │       ├── dev-team/
    │       ├── qa-team/
    │       └── devops-team/
    │
    └── install.sh (安裝腳本)

特性：

• 每個專案有獨立的 .claude/
• AIPlugins 作為模板庫，不是 submodule
• 用安裝腳本將模板複製到專案

適用場景：

• 中大型團隊
• 多專案並行
• 需要標準化流程
• 專案間配置需要獨立演進

優點：
✅ 模組化：每個專案獨立，不互相影響
✅ 可重用：共用 templates，新專案快速啟動
✅ 版本控制：AI 配置也進 git，可追蹤演進
✅ 彈性：專案可以選擇性使用部分 templates
✅ 獨立更新：AIPlugins 更新，專案可以選擇是否同步
✅ 沒有 submodule 問題：複製過來就是專案的一部分

安裝方式：

cd ProjectA
../AIPlugins/install.sh --team=dev-team

# 自動將 template 複製到 ProjectA/.claude/
# 複製後可以自由修改，不影響其他專案

AIPlugins 的模組化設計：

Templates/
├── .skills/ (專業能力模組)
│   ├── frontend-expert/     ← React, Vue, Angular 專家
│   ├── backend-expert/      ← Node.js, .NET, Python 專家
│   ├── sre/                 ← 網站可靠性工程
│   └── dba/                 ← 資料庫管理
│
├── .teams/ (完整團隊模板)
│   ├── dev-team/            ← 開發團隊（含 agents + skills）
│   ├── qa-team/             ← 測試團隊
│   └── devops-team/         ← 維運團隊
│
└── .rules/ (規則與標準)
    ├── coding-style.md      ← 編碼規範
    ├── git-workflow.md      ← Git 流程
    └── testing.md           ← 測試標準

install.sh 原理：

#!/bin/bash
TEAM=$1
PROJECT_ROOT=$2

# 複製 team template
cp -r Templates/.teams/$TEAM/* $PROJECT_ROOT/.claude/

# 可選：複製共用 skills
cp -r Templates/.skills/common/* $PROJECT_ROOT/.claude/skills/

# 可選：複製 rules
cp -r Templates/.rules/* $PROJECT_ROOT/.claude/rules/

echo "✅ Installed $TEAM to $PROJECT_ROOT"

---

2.6 版本比較總表

特性	v0	v1	v2	v3
規模化	❌	⚠️	✅	✅
可重用	❌	❌	✅	✅
獨立演進	✅	✅	❌	✅
管理複雜度	簡單	簡單	複雜	中等
新人友善度	N/A	✅	❌	✅
適合團隊規模	1人	2-5人	5-20人	10人以上
適合專案數	1	1-2	3+	5+

---

2.7 從 v1 升級到 v3 的遷移路徑

Step 1: 建立 AIPlugins repo
  → 將現有的 .claude/ 提煉成 templates

Step 2: 寫安裝腳本
  → 支援選擇性安裝 team/skills

Step 3: 在新專案試驗
  → 驗證 template 是否通用

Step 4: 逐步遷移舊專案
  → 舊專案可以繼續用 v1，新專案用 v3

Step 5: 持續優化 templates
  → 根據實際使用反饋調整

注意事項：

• 不需要一次全部遷移
• v1 和 v3 可以共存
• 優先在新專案採用 v3

---

3. 驗證論述：為什麼這樣設計是合理的

本章節透過架構設計原理、邏輯推演、業界類比來驗證方案的有效性

---

3.1 架構設計原理

核心設計原則

這套演進路徑（v0 → v1 → v2 → v3）背後的設計原則：

1. 關注點分離 (Separation of Concerns)

v1: 程式碼 + AI 配置混在一起
  → 優點：簡單
  → 缺點：耦合度高

v3: 程式碼 vs AI Templates 分離
  → 優點：各自演進
  → 缺點：需要安裝腳本串接

軟體工程的經典原則：高內聚、低耦合。v3 將「團隊能力模板」與「專案程式碼」分離，符合這個原則。

2. DRY 原則 (Don’t Repeat Yourself)

v1: 每個專案重複配置 .claude/
  → 10 個專案 = 10 次配置
  → 改進一個配置需要手動同步 10 次

v3: 共用 AIPlugins templates
  → 10 個專案使用同一套 templates
  → 改進一次，所有專案受益

這就像程式碼中的「抽離共用函式」，而不是複製貼上。

3. 組合優於繼承 (Composition over Inheritance)

v2: 用 git submodule「繼承」AI 配置
  → 所有專案綁定同一個版本
  → 無法客製化

v3: 用「複製 + 組合」的方式
  → 專案可以選擇性使用部分 templates
  → 專案可以客製化後再組合

v3 讓每個專案保有彈性，不會被 submodule 綁死。

與軟體工程的類比

軟體工程概念	團隊設計類比
函式庫 (Library)	AIPlugins Templates
npm install	install.sh --team=dev-team
node_modules/	.claude/ (安裝後)
package.json	記錄使用了哪些 templates
升級套件	重新執行 install.sh
fork & modify	複製後客製化

v3 的設計思想就像 npm 生態系：

• 有一個「套件庫」（AIPlugins）
• 專案可以「安裝」需要的套件
• 安裝後可以「客製化」
• 套件庫可以「獨立演進」

---

3.2 邏輯推演：為什麼 v3 優於 v1/v2

推演 1：規模化時的成本曲線

假設一個團隊有 N 個專案：

v1 的成本：

• 初始配置成本：N × T （每個專案都要配置一次）
• 維護成本：N × M （每個專案都要獨立維護）
• 改進同步成本：N × S （改進要手動同步）

v3 的成本：

• 初始設置成本：T_setup （建立 AIPlugins，一次性）
• 專案配置成本：N × t （執行 install.sh，t << T）
• 維護成本：M_central （集中維護 templates）
• 改進同步成本：0 （專案自行決定是否同步）

交叉點分析：

當 N = 1-2 時：
  v1 成本 < v3 成本（v3 的初始設置成本 T_setup 太高）

當 N ≥ 3 時：
  v3 成本開始低於 v1
  隨著 N 增加，差距越來越大

結論：專案數量越多，v3 的優勢越明顯。

---

推演 2：團隊成長的適應性

情境：團隊從 5 人成長到 20 人

v1 的困境：

1. 每個新人都要重新學習每個專案的配置方式
2. 配置不一致導致協作困難
3. 新人貢獻的改進難以擴散到其他專案

v3 的優勢：

1. 新人只需學習一套標準 templates
2. 所有專案遵循同樣的配置邏輯
3. 改進可以提煉回 AIPlugins，所有專案受益

邏輯：

當團隊規模 ↑ 時，標準化 ↑ 的重要性也 ↑

v3 提供了「標準化」但不失「彈性」的平衡點。

---

推演 3：配置演進的速度

情境：AI 工具快速迭代（如 Claude Code 每月更新）

v1 的問題：

• 10 個專案 = 10 次手動更新
• 容易遺漏某些專案
• 更新策略不一致

v3 的優勢：

• AIPlugins 統一更新
• 專案可以選擇「立即同步」或「延後同步」
• 降低更新風險（先在 AIPlugins 測試，再推廣）

邏輯：

工具迭代速度 ↑ → 集中管理配置的價值 ↑

---

3.3 業界類比驗證

這套演進路徑並非憑空想像，而是參考業界成熟的模式：

類比 1：Monorepo vs Multi-Repo

模式	特性	對應版本
Monorepo	所有程式碼在一個 repo	v1 (Mono Repo)
Multi-Repo + Shared Library	程式碼分離 + 共用函式庫	v3 (Multi-Repo + AIPlugins)

業界趨勢：

• Google 用 Monorepo（適合超大團隊）
• Netflix 用 Multi-Repo（適合中大型團隊）
• v3 參考的是 Netflix 模式

類比 2：Infrastructure as Code

傳統方式	IaC 方式	對應版本
手動配置伺服器	Terraform / Ansible	v0 → v3
每台機器獨立配置	用模板批次部署	v1 → v3

v3 的 AIPlugins 就像 Terraform 的 modules：

• 定義可重用的基礎設施模板
• 不同專案使用不同組合
• 集中維護、分散使用

類比 3：Design System

設計系統概念	團隊設計類比
Component Library	AIPlugins Templates
Figma Shared Library	.claude/skills/
Design Tokens	.claude/rules/
專案使用 Library	install.sh

v3 把「團隊設計」當成「Design System」來管理，這是成熟組織的標準做法。

---

3.4 適用場景與限制分析（邏輯推論）

適用場景推論

基於架構設計原理，我們可以推論出各版本的適用場景：

推論邏輯：

• 當「重用價值」> 「管理成本」時，選 v3
• 當「專案數量」< 3 時，重用價值低，選 v1
• 當「團隊規模」> 10 時，標準化價值高，選 v3

推論結果：

場景	推薦版本	推論依據
個人 side project	v0 或 v1	無重用需求，簡單優先
新創公司（< 10人）	v1	專案數量少，快速啟動優先
成長期公司（10-50人）	v3	專案開始增加，標準化開始有價值
大型組織（> 50人）	v3	多專案並行，必須標準化
外包團隊	v1	專案獨立，客戶不同，難以重用
諮詢公司	v3	多客戶、多專案，templates 可重用
產品公司	v3	多產品線，統一團隊設計思維

限制分析（邏輯推論）

v3 的前置條件：

❌ 團隊太小（< 5人）

• 推論：5人以下的團隊，專案數量通常 < 3
• 結論：v3 的管理成本 > 收益
• 建議：用 v1 直到團隊擴大或專案增加

❌ 專案只有 1-2 個

• 推論：重用價值 = 專案數量 – 1
• 結論：1-2 個專案的重用價值接近 0
• 建議：用 v1，等專案數量 ≥ 3 再考慮 v3

❌ 沒有專人維護 AIPlugins

• 推論：templates 會過時 → 各專案自行修改 → 失去一致性
• 結論：v3 退化成 v1
• 建議：指定 Tech Lead 或 Architect 負責維護

❌ 團隊不熟悉 AI 協作

• 推論：連 v1 都不會用，直接跳 v3 會更困難
• 結論：學習曲線過陡
• 建議：先在 1-2 個專案試驗 v1，累積經驗後再升級

v3 的成功條件：

✅ 專案數量 ≥ 3
✅ 團隊規模 ≥ 10 人
✅ 有專人負責維護 AIPlugins（至少 20% 工作時間）
✅ 團隊已熟悉 AI 協作基本概念

決策公式（簡化）：

if (專案數量 >= 3 && 團隊規模 >= 10 && 有維護人力) {
  推薦 v3
} else if (專案數量 >= 2 || 團隊規模 >= 5) {
  可考慮 v3（但要評估維護成本）
} else {
  推薦 v1
}

---

3.5 理論驗證總結

透過以上的架構設計原理、邏輯推演、業界類比，我們可以得出：

v0 → v1 → v2 → v3 的演進是合理的，因為：

1. 符合軟體工程的經典原則

• 關注點分離、DRY、組合優於繼承

1. 成本曲線邏輯成立

• 專案數量越多，v3 的優勢越明顯

1. 業界有成功先例

• Multi-Repo + Shared Library（Netflix）
• Infrastructure as Code（Terraform）
• Design System（Figma）

1. 適用場景邏輯自洽

• 前置條件明確（專案數、團隊規模、維護人力）
• 決策邏輯可驗證

未來可驗證的點：

雖然本文基於理論分析與邏輯推演，但以下指標可在實際採用後驗證：

• [ ] 新專案啟動時間（v1 vs v3）
• [ ] 配置維護成本（人時/月）
• [ ] 團隊滿意度（問卷調查）
• [ ] 配置一致性（稽核通過率）
• [ ] 改進擴散速度（新 template 被採用的時間）

邀請讀者參與驗證：

如果你在團隊中實踐了這套方法，歡迎分享你的數據與經驗，讓這套理論得到實證支持

---

4. 應用指南

4.1 如何選擇適合的版本

決策樹

Q1: 你的團隊有幾個人？
├─ 1 人 → v0 或 v1
├─ 2-5 人 → v1
├─ 5-20 人 → v1 或 v3
└─ 20 人以上 → v3

Q2: 你有幾個專案？
├─ 1-2 個 → v1
├─ 3-5 個 → v1 或 v3
└─ 5 個以上 → v3

Q3: 你需要跨專案重用配置嗎？
├─ 不需要 → v1
└─ 需要 → v3

Q4: 你有專人維護 AI 配置嗎？
├─ 沒有 → v1
└─ 有 → v3

最終建議：
- 如果 Q2 ≥ 3 且 Q3 = 需要 → 強烈建議 v3
- 否則 → v1 即可

---

4.2 從 v1 升級到 v3 的步驟

Phase 1：建立 AIPlugins 基礎（Week 1）

# 1. 建立 AIPlugins repo
mkdir AIPlugins
cd AIPlugins
git init

# 2. 建立目錄結構
mkdir -p Templates/.skills
mkdir -p Templates/.teams
mkdir -p Templates/.rules

# 3. 將現有專案的 .claude/ 提煉成 template
# (選擇最成熟的專案作為基礎)
cp -r ../BestProject/.claude/* Templates/.teams/dev-team/

# 4. Commit 初版
git add .
git commit -m "feat: initial AIPlugins templates"

Phase 2：撰寫安裝腳本（Week 1）

# install.sh
#!/bin/bash

set -e

TEAM_NAME=$1
PROJECT_ROOT=${2:-.}

if [ -z "$TEAM_NAME" ]; then
  echo "Usage: ./install.sh <team-name> [project-root]"
  echo "Available teams:"
  ls -1 Templates/.teams/
  exit 1
fi

TEAM_PATH="Templates/.teams/$TEAM_NAME"

if [ ! -d "$TEAM_PATH" ]; then
  echo "Error: Team '$TEAM_NAME' not found"
  exit 1
fi

echo "Installing team: $TEAM_NAME to $PROJECT_ROOT/.claude/"

# 建立目錄
mkdir -p "$PROJECT_ROOT/.claude"

# 複製 team template
cp -r "$TEAM_PATH"/* "$PROJECT_ROOT/.claude/"

# 複製共用 skills (optional)
if [ -d "Templates/.skills/common" ]; then
  mkdir -p "$PROJECT_ROOT/.claude/skills"
  cp -r Templates/.skills/common/* "$PROJECT_ROOT/.claude/skills/"
fi

# 複製 rules (optional)
if [ -d "Templates/.rules" ]; then
  mkdir -p "$PROJECT_ROOT/.claude/rules"
  cp -r Templates/.rules/* "$PROJECT_ROOT/.claude/rules/"
fi

echo "✅ Installation completed!"
echo "📝 You can now customize .claude/ for this project"

Phase 3：在新專案試驗（Week 2）

# 1. 建立測試專案
mkdir TestProject
cd TestProject
git init

# 2. 安裝 dev-team
../AIPlugins/install.sh dev-team

# 3. 驗證
ls -la .claude/
# 應該看到：
# .claude/agents/
# .claude/skills/
# .claude/rules/

# 4. 測試 Claude Code 是否能正確讀取
# (啟動 Claude Code 並測試 agent 功能)

# 5. 記錄問題與改進

Phase 4：優化 Templates（Week 3）

根據試驗結果，優化 templates：

• 移除不必要的 agents
• 補充缺少的 skills
• 更新 rules 描述
• 改進安裝腳本

Phase 5：逐步遷移舊專案（Week 4+）

策略：不需要一次全部遷移

優先順序：
1. 新專案：直接用 v3
2. 活躍專案：有維護需求時遷移
3. 穩定專案：不急著遷移，等有需求再說
4. 遺留專案：保持 v1 即可

遷移檢查清單：

• [ ] 備份原有的 .claude/ 配置
• [ ] 執行 install.sh 安裝 team
• [ ] 對比新舊配置，確認沒有遺漏
• [ ] 測試 Claude Code 功能正常
• [ ] 更新文檔說明新的配置方式
• [ ] Commit 並推送

---

4.3 常見坑與注意事項

坑 1：Template 過時

現象：
AIPlugins 的 template 很久沒更新，新專案用的還是舊的配置

原因：
沒有專人維護 AIPlugins

解法：

• 指定專人（Tech Lead 或 Architect）負責維護
• 每季度 review 一次 templates
• 鼓勵團隊貢獻改進

坑 2：專案配置偏離標準

現象：
每個專案安裝後都自己改，最後又變得不一致

原因：
沒有規範哪些可以改，哪些應該保持一致

解法：

• 在 template 中標註 [CUSTOMIZABLE] 和 [STANDARD]
• 建立 Code Review 檢查機制
• 定期 audit 專案配置

坑 3：安裝腳本覆蓋客製化

現象：
重新執行 install.sh 會覆蓋專案的客製化配置

原因：
安裝腳本是強制覆蓋

解法：

• 安裝腳本加入 --force 參數（預設不覆蓋）
• 或改用 update.sh 只更新特定部分
• 用 git diff 檢查變更

坑 4：忘記提煉改進回 AIPlugins

現象：
專案中發現好的配置改進，但沒有回饋到 AIPlugins

原因：
沒有建立反饋機制

解法：

• 在 Sprint Retrospective 討論 AI 配置改進
• 建立 PR 流程讓團隊貢獻回 AIPlugins
• 定期 review 各專案的客製化，提煉共通部分

---

4.4 進階：梯隊化團隊設計

當專案複雜度提升，可以用「梯隊」來組織團隊：

梯隊 A（核心開發）：
  👤 Senior Dev + 🤖 Claude (Coding)
  👤 Tech Lead + 🤖 Claude (Review)

梯隊 B（測試品質）：
  🤖 Test Agent (Unit Test)
  🤖 QA Agent (Integration Test)
  👤 QA Lead (Final Approval)

梯隊 C（文檔維運）：
  🤖 Doc Agent (Auto-gen Docs)
  🤖 DevOps Agent (CI/CD)
  👤 Ops (Monitoring)

特性：

• 可動態生成：專案初期只啟動梯隊 A
• 可局部抽換：梯隊 B 的 AI 可升級到新模型
• 可版本控制：整個梯隊配置存在 .teams/

技術實作：
使用 Claude Code 的 TeamCreate、TaskCreate、SendMessage 工具來協調不同梯隊的工作

---

4.5 進階：文件設計（索引而非翻譯）

核心概念：

文件不是用來「翻譯程式碼」，而是用來「索引架構」

傳統文件的問題

// 程式碼
function calculateUserAge(birthDate) {
  return new Date().getFullYear() - birthDate.getFullYear();
}

// 文件（無腦翻譯）
/**
 * 計算使用者年齡
 * @param {Date} birthDate - 出生日期
 * @returns {number} 年齡
 */

這種文件只是翻譯，沒有增加任何資訊。

索引文件的做法

# 系統架構索引

## 核心流程
使用者註冊流程：
`UserController.register()` → `UserService.createUser()` → `UserRepository.save()`

檔案位置：
- Controller: `src/api/controllers/UserController.ts`
- Service: `src/services/UserService.ts`
- Repository: `src/data/UserRepository.ts`

## 關鍵決策點
- Email 驗證在哪裡？ → `UserService.validateEmail()` Line 45
- 密碼加密用什麼？ → `bcrypt`，設定在 `src/config/security.ts`
- 錯誤處理策略？ → 統一在 `middleware/errorHandler.ts`

差異：

• ❌ 抽象文件：告訴你「這是什麼」
• ✅ 索引文件：告訴你「在哪裡」

實踐建議

何時該寫文件：

• ✅ 寫索引：列出檔案路徑、關鍵決策點、資料流向
• ✅ 寫地圖：畫出模組關係、呼叫鏈、依賴圖
• ❌ 別寫翻譯：不要把程式碼翻譯成中文註解
• ❌ 別寫抽象：不要寫「本模組負責處理…」這種廢話

如何維護文件：

• 架構變了才更新索引（不常變）
• 程式碼細節不寫入文件（會常變）
• 用 docs/CODEMAPS/ 或 README.md 當索引入口

範例：

docs/
├── CODEMAPS/
│   ├── authentication.md   ← 認證流程的索引地圖
│   ├── payment.md          ← 支付流程的索引地圖
│   └── notification.md     ← 通知系統的索引地圖
└── README.md               ← 整體索引入口

這樣，AI 可以先讀索引，再去找對應的程式碼，而不需要把程式碼寫進文件。

---

4.6 延伸資源

官方資源

• Claude Code 文檔：https://docs.anthropic.com/claude-code
• Agent Teams 功能說明：[待補充]
• Task Coordination 教學：[待補充]

社群資源

• [待補充：GitHub repo 範例]
• [待補充：Medium 文章]
• [待補充：Discord 討論群]

進階主題

• 如何設計可測試的 agent
• 如何監控 AI token 使用量
• 如何建立 agent 的 CI/CD pipeline
• 如何處理 agent 之間的衝突

---

總結

核心洞察

1. 團隊設計就是軟體架構設計
   運算單元從「函式」變成「人或 AI」
2. 從固定職位到動態資源
   不是招聘一個「會 React 的人」，而是設計「Frontend 角色」的能力組合
3. 模組化、可重用、可版本控制
   團隊配置應該像程式碼一樣，可以 git 管理、可以跨專案重用

演進路徑

v0 (單人) → v1 (Mono Repo) → v2 (Sub-module) → v3 (Multi-Repo)

建議：
- 小團隊（< 5人）：v1 即可
- 中型團隊（5-20人）：考慮 v3
- 大型組織（> 20人）：強烈建議 v3

立即行動

如果你現在就想開始：

1. 盤點現有配置
   檢視你目前的 .claude/ 結構
2. 選擇適合的版本
   用本文的決策樹選擇 v1 或 v3
3. 試驗一個小專案
   不要一次全部改，先在一個專案試驗
4. 記錄經驗
   踩坑是必然的，記錄下來形成團隊知識
5. 持續優化
   團隊設計不是一次性的，要持續迭代

---

關於本文的驗證方法

本文採用「理論驗證」而非「實測驗證」

為什麼採用理論驗證？

這是一個新興領域，AI 團隊設計還沒有大規模的實測數據可供參考。因此本文採用：

1. 架構設計原理：參考軟體工程的經典原則
2. 邏輯推演：透過成本分析、規模分析推導結論
3. 業界類比：參考成熟領域的成功模式（Multi-Repo、IaC、Design System）

這樣的驗證方法是否可信？

部分可信，但需要實踐驗證。

可信的部分：

• 架構設計原則（如 DRY、關注點分離）是經過驗證的
• 業界類比（如 Terraform、Design System）有成功先例
• 邏輯推演的結構是自洽的

需要驗證的部分：

• 實際的成本數據（人力、時間、AI token）
• 團隊的接受度與滿意度
• 不同規模團隊的實際效果
• 長期維護的真實成本

邀請你參與驗證

如果你在團隊中實踐了這套方法，歡迎分享：

• ✅ 成功經驗（什麼情境下有效？）
• ❌ 失敗教訓（遇到什麼坑？）
• 📊 實測數據（成本、時間、滿意度）
• 💡 改進建議（哪些地方可以優化？）

這些實踐經驗將讓理論變得更扎實。