15. References 上下文資料引用
References 是「把大量參考資料組織給 Claude，按需讀」的一整套機制——核心目標是避免上下文爆掉，讓 Claude 看到的內容剛好夠用。 我們今天精簡 PAM CLAUDE.md（650 行 + 5 個 rules）就是用了這個原則。
15.1 為什麼需要 Reference 機制
Claude 的 context window 大但不無限：
情境：你問 Claude「PAM 通知功能要怎麼擴充？」
❌ 把所有東西塞 context：
CLAUDE.md（670 行）
+ Models.cs（2000 行）
+ 所有 Controller（10000 行）
+ 所有 Service（5000 行）
+ Docs/（30 份文件）
→ 17,000+ 行 → 撐爆 context window
→ 即使沒爆，注意力也分散
✅ Reference 模式：
CLAUDE.md（650 行，含「通知系統 → 詳見 NOTIFICATION.md」）
+ 按需讀 Docs/dev/NOTIFICATION.md
→ 800-1000 行 → 焦點集中
→ Reference 是「目錄 + 按需讀全文」的設計策略。
15.2 三大 Reference 機制
| 機制 | 何時觸發 | 寫法 | 適用 |
|---|---|---|---|
A. @filename 對話引用 | 你打 @xx 時即刻載入 | @Docs/dev/PROTECTION.md | 一次性、即時、你決定 |
| B. Skill references/ 子資料夾 | Skill 啟動時 Claude 自動評估要不要讀 | skills/X/references/*.md | Skill 內常用文件 |
| C. CLAUDE.md → Docs/ 文字 ref | Claude 看到 ref 行，按需主動 Read | 📖 詳見 [Docs/dev/X.md] | 系統文檔大綱 |
→ 三者並存互補，不衝突。
15.3 機制 A：@filename 對話引用
寫法
對話中打：
@Controllers/HrController.cs
@Docs/dev/PROTECTION.md
@~/Notes/meeting-2026-04-25.md
→ Claude 在當前訊息完整載入該檔案內容，作為討論基礎。
適用情境
| 情境 | 範例 |
|---|---|
| 一次性 review 某檔案 | 「@HrController.cs 找出所有 SQL 注入風險」 |
| 對比兩份文件 | 「@old-spec.md 跟 @new-spec.md 哪裡不同」 |
| 即興討論最新文件 | 「@meeting-notes.md 這份會議我有什麼 action item」 |
跟 Read tool 的差異
@filename | Claude 主動 Read | |
|---|---|---|
| 觸發 | 你打字 | Claude 判斷該讀 |
| 訊息可見 | 顯示 @xxx | 內部 tool call |
| 適合 | 你「點名」要 Claude 看的檔案 | Claude 自主探索 |
限制
- 只能用於 Claude Code（Cowork 對話內也支援）
- 大檔案會佔大量 context（用前要評估）
- 整檔載入，不能只取片段（要片段請用 Read with offset/limit）
15.4 機制 B：Skill references/ 子資料夾
結構
skills/
├── wiki-ingest/
│ ├── SKILL.md ← 主規範（必讀）
│ └── references/ ← 子資料（按需讀）
│ ├── frontmatter-spec.md
│ ├── link-format.md
│ └── examples.md
├── wiki-compile/
│ ├── SKILL.md
│ └── references/
│ ├── chapter-detection.md
│ └── map-generation.md
設計哲學
| 內容類型 | 該放哪 |
|---|---|
| 觸發條件 + 步驟總覽 | SKILL.md（永遠讀） |
| 細節規範 / 邊界 case | references/X.md（按需讀） |
| 範例 / 範本 | references/examples.md |
| 故障排除 | references/troubleshooting.md |
→ SKILL.md 保持精簡（< 100 行），細節分散在 references/。
Claude 怎麼決定要讀
當 Skill 觸發時，Claude 看到 SKILL.md 提到：
## 詳細規格
frontmatter 規格 → 見 `references/frontmatter-spec.md`
連結格式 → 見 `references/link-format.md`
完整範例 → 見 `references/examples.md`→ Claude 評估當前任務需要哪些，逐一 Read。
範例：今天打包的 plugin
karpathy-wiki-pattern.plugin 的 4 個 skill 都用了這個結構：
wiki-ingest/
├── SKILL.md ← 觸發 + 6 步驟
└── references/
└── (具體規範)
wiki-compile/
├── SKILL.md ← 觸發 + 流程
└── references/
└── (細節)
15.5 機制 C：CLAUDE.md → Docs/ 文字 ref
寫法（PAM 實例）
## 強制面談流程
候選人（乙丙等）→ HR確認面談名單 → 自動產PDF → ...
📖 完整規格（含 PDF 套表欄位、gen_import 匯出規則）：[Docs/dev/INTERVIEW.md](Docs/dev/INTERVIEW.md)Claude 行為
讀到「📖 完整規格：[Docs/dev/INTERVIEW.md]」後：
- 不會自動 Read — 等你的任務確實需要才讀
- 你問「面談 PDF 缺一欄」→ Claude 才 Read INTERVIEW.md
- 你問「修改面談流程的某個 SQL」→ 不必 Read INTERVIEW.md，直接動 code
→ ref 等於「你能找到完整資料的地址」，但不強制每次讀。
寫好 ref 的 3 個原則
- 動詞清楚：「📖 完整規格」/「📋 API 對照」/「🔧 故障排除」——讓 Claude 一眼判斷該不該讀
- 括號加情境：「（含 PDF 套表欄位、gen_import 匯出規則）」——告訴 Claude 這份文件涵蓋什麼
- 路徑可點：用 markdown link 格式
[文字](path)比純路徑好讀
PAM CLAUDE.md 內已有的 ref（節錄）
| 文件 | 內容 | 何時讀取 |
|------|------|---------|
| API_REFERENCE.md | 160+ API 端點完整清單 | 新增/修改 API 時 |
| DATABASE.md | 29 DbSet 資料表清單 | 查詢資料表結構時 |
| NOTIFICATION.md | 催繳通知系統、範本變數 | 修改通知功能時 |
| EXCEL_IMPORT.md | Excel 匯入規格 + 104 整合 | 修改匯入功能時 |
| ...（共 14 份）→ 一個整潔的 reference 索引表，比塞 14 份內容到 CLAUDE.md 好太多。
15.6 三機制何時用哪個？
你打字明確指定 1 個檔案
→ 機制 A（@filename）
任務在 skill 範圍內，需要該 skill 的細節文件
→ 機制 B（skill references/）
跨多個任務都會被引用的系統文檔
→ 機制 C（CLAUDE.md → Docs/ ref）
實際上通常並用：
| 場景 | 用到的機制 |
|---|---|
| 修 PAM 面談 bug | C 找路徑 → A 載入 INTERVIEW.md → 動 code |
| 寫新 skill | B 在新 skill 加 references/ |
| 想看歷史 commit | A 直接 @CHANGELOG.md |
| 全新模組規劃 | C 在 CLAUDE.md 新增 ref 行 |
15.7 跟 Rules / Skills / CLAUDE.md 的差異
Claude 上下文層次
CLAUDE.md ← 永遠讀（系統概覽 + 業務規則 + ref 索引）
│
├─→ Rules ← 條件式啟用（紅線、禁忌）
│
├─→ Skills ← 任務式啟用（操作 SOP）
│ │
│ └─→ references/ ← skill 內細節（按需讀）
│
├─→ @filename ← 你即時點名載入
│
└─→ Docs/ ← 透過 ref 讓 Claude 按需 Read
4 者本質差異：
| 何時生效 | 內容類型 | |
|---|---|---|
| CLAUDE.md | 永遠 | 系統性、business rules |
| Rules | 條件（glob/desc） | 紅線、禁忌、規範 |
| Skills | 任務描述匹配 | 操作步驟、SOP |
| References | 你或 Claude 主動讀 | 細節、規格、範例 |
→ 不衝突，互補設計。
15.8 避免上下文爆掉的策略
策略 1：分層 ref，不重複
CLAUDE.md：
「面談流程概覽 → 詳見 INTERVIEW.md」（10 行）
INTERVIEW.md：
「PDF 套表詳細欄位 → 詳見 INTERVIEW_PDF_FIELDS.md」（200 行）
INTERVIEW_PDF_FIELDS.md：
「（最細節 600 行）」
→ Claude 只讀到當前任務需要的層級，不過度展開。
策略 2：強類型 ref（讓 Claude 判斷準）
❌ 不夠好：
更多資訊：[X.md](X.md)✅ 強類型：
📖 完整規格（含資料庫 schema + API endpoint）：[X.md](X.md)
🔧 故障排除（常見錯誤 + log 解讀）：[Y.md](Y.md)
📋 API 對照表（160+ endpoints）：[Z.md](Z.md)→ Claude 看標籤就知道要不要讀。
策略 3：references/ 內檔案命名講重點
❌ details.md / notes.md — 看不出什麼內容
✅ frontmatter-spec.md / link-format.md / error-cases.md — 自帶語意
→ Claude 從檔名就能判斷該讀哪個。
策略 4：定期 audit ref 健康度
問自己：
- 哪些 ref 超過 6 個月沒被讀？→ 可能可以合併或刪
- 哪些 ref 經常被讀全文？→ 可能該移回 CLAUDE.md
- 哪些 ref 名稱不清楚？→ 改名
15.9 PAM 已有的 Reference 結構
ExamSystem/
├── CLAUDE.md（650 行）
│ ├── 規則總覽 → .claude/rules/*.md（5 個 rule）
│ ├── 強制面談流程 → 📖 Docs/dev/INTERVIEW.md
│ ├── 主管交接 → 📖 Docs/dev/REVIEWER_TRANSFER.md
│ ├── 公告系統 → 📖 Docs/dev/ANNOUNCEMENT.md
│ ├── 標語系統 → 📖 Docs/dev/TAGLINE.md
│ ├── 今日要事 → 📖 Docs/dev/TODAY_PAGE.md
│ ├── 人員管理保護 → 📖 Docs/dev/PROTECTION.md
│ ├── 超額說明歷程 → 📖 Docs/dev/OVERRIDE_LOG.md
│ ├── 考核結案報表 → 📖 Docs/dev/EXAM_REPORT.md
│ └── ...（共 14 份 Docs/dev ref）
├── .claude/rules/
│ └── (5 個 rule，每個 < 15 行)
└── Docs/dev/
├── API_REFERENCE.md
├── DATABASE.md
├── PAGES.md
├── DEPLOY.md
├── NOTIFICATION.md
├── EXCEL_IMPORT.md
├── CHANGELOG.md
├── EXAM_REPORT.md
├── REVIEWER_TRANSFER.md
├── TODAY_PAGE.md
├── PROTECTION.md
├── OVERRIDE_LOG.md
├── INTERVIEW.md
├── ANNOUNCEMENT.md
├── TAGLINE.md
├── COORDINATOR.md
├── 104_WRITEBACK_FLOW.md
└── EXAM_FORM_PDF.md
設計：
- CLAUDE.md = 系統概覽 + ref 索引（永遠讀）
- rules = 紅線（按 glob 觸發）
- Docs/dev = 細節規格（按 ref 在需要時 Read）
→ 任何任務 Claude 看到的 context 都剛好夠用。
15.10 為新模組設計 Reference 的工作流
當你開始一個新模組（假設「績效面談 v2」）時：
Step 1：在 CLAUDE.md 加大綱段
## 績效面談 v2
升級面談流程，加入線上簽核 + DocuSign 整合 + 自動催繳。
📖 完整規格：[Docs/dev/INTERVIEW_V2.md](Docs/dev/INTERVIEW_V2.md)Step 2：寫詳細 spec 到 Docs/dev/INTERVIEW_V2.md
# 績效面談 v2 規格
## 流程
...
## 資料結構
...
## API
...
## 邊界 case
...Step 3：如果有跨檔案紅線，加 rule
# .claude/rules/06-interview-v2.md
---
glob: "Services/InterviewV2*|Controllers/InterviewV2*"
---
- 簽核流程不可繞過 DocuSign callback
- 催繳排程必須冪等（避免重複寄）Step 4：如果有反覆使用的範本，放到 references/
skills/interview-followup/
├── SKILL.md
└── references/
├── docusign-callback.md
└── reminder-template.md
→ CLAUDE.md 只多 5 行 ref，但 Claude 在做 v2 任務時能拿到完整 60 頁規格。
15.11 何時不該用 Reference 機制
- ❌ 規則只有 10 行 → 直接寫 CLAUDE.md，不必 ref 出去
- ❌ 一次性訊息（如「這次只動前端」）→ inline 對話即可
- ❌ 一年改一次的東西 → 內嵌即可，ref 反而增加維護成本
- ❌ 互不相關的多份文件並列 → 不要硬連，分開存就好
→ Reference 是「分層管理」，不是「為了 ref 而 ref」。
15.12 常見錯誤
| ❌ 錯誤 | 影響 | ✅ 正確 |
|---|---|---|
| ref 路徑不對 | Claude 找不到，回頭問你 | 用相對路徑 + 確認檔案存在 |
| ref 沒寫情境 | Claude 不知道何時讀 | 加「📖 含 X / Y / Z 內容」說明 |
| 檔案太大塞滿 references/ | 失去精簡效果 | 一個 reference 應 < 200 行 |
@filename 載超大檔 | 一次吃光 context | 用 Read with offset/limit |
| Docs/ 用過時內容 | 誤導 Claude | 定期 audit + 加 last-updated |
15.13 Vincent 應用建議
短期（已做）
- ✅ PAM CLAUDE.md 14 個 Docs/dev ref（系統文檔）
- ✅ .claude/rules/ 5 個 rule（紅線）
- ✅ 4 個 skill 各自 references/（plugin 內）
中期
- 🟡 為 PAM 14 份 Docs/dev/ 寫一致的「📖 含 X / Y / Z」標準格式
- 🟡 audit 哪些 ref 半年沒被觸動 → 評估合併
長期
- ⏸ 把 PAM Docs/dev/ 整套打包成 plugin 的 references/
- ⏸ 跨專案共用的 ref（年代集團 IT 通用規範）
進階主題
- 詳細概念：上下文壓縮（Reference 防爆 context 的姊妹機制）
- CLAUDE.md 結構：CLAUDE.md（專案手冊）
- 4 層機制：CLAUDE.md 4 層機制
- Plugin 內的 references：13-Plugin 建置與使用
- Rules 對照：14-Rules 規則目錄
- 實作範例：查看 PAM CLAUDE.md
← 上一章：14-Rules 規則目錄 | 回到 README