分形文檔架構：Claude Code 開發的核心知識管理方法

來源: @Jiaxi_Cui | 原文連結

日期:

標籤: 知識管理 架構設計 文檔組織

---

根據截圖內容和原始推文，我已經掌握了核心概念。現在讓我整理成知識庫文章：

> **來源**: [Jiaxi Cui (@Jiaxi_Cui)](https://twitter.com/Jiaxi_Cui) - [ai-coding-kit/protocols/fractal-docs.md](https://github.com/JessyTsui/ai-coding-kit/blob/master/protocols/fractal-docs.md)  
> **日期**: 2025  
> **標籤**: `Claude Code` `文檔架構` `知識管理` `AI開發` `分形結構`

---

## 核心概念

分形文檔架構是一套基於「自指」(self-reference) 和「自蔓延」(self-propagation) 原則的文檔管理方法，特別適合用於 Claude Code 等 AI 輔助的大規模開發。其核心思想是：**在每個層級維護極簡說明，標記依賴關係與對外提供，實現局部改動自動反映到整體**。

這種方法借鑑了《哥德爾、埃舍爾、巴赫》中提到的「複調」與「自指」概念，在代碼庫中實現了類似分形的結構——每個部分都反映整體的組織原則。

## 三層核心規則

### 1. 根目錄主文檔（根級約束）

**位置**: 項目根目錄的主要 `README.md` 或 `CLAUDE.md`

**要求**: 強調任何功能、架構、寫法更新**必須在工作結束後更新相關目錄的子文檔**

**作用**: 
- 建立全局更新契約
- 確保文檔與代碼同步演進
- 為 AI 提供明確的文檔維護指令

### 2. 資料夾級文檔（目錄級自指）

**位置**: 每個資料夾內的 `README.md` 或 `index.md`

**格式要求**:
```markdown
<!-- 文件開頭聲明 -->
一旦我所屬的文件夾有所變化，請更新我。

## 架構說明（3 行以內）
[極簡描述這個資料夾的職責與定位]

## 文件清單
- **filename.ts** - [地位] - [功能]
- **another.ts** - [地位] - [功能]

範例:

一旦我所屬的文件夾有所變化，請更新我。

## 架構說明
本資料夾負責用戶認證相關功能，包含 JWT 驗證、會話管理與權限檢查。

## 文件清單
- **middleware.ts** - 核心中間件 - 處理請求驗證與權限檢查
- **jwt-utils.ts** - 工具函數 - JWT 簽發與驗證
- **types.ts** - 類型定義 - 認證相關的 TypeScript 類型

3. 文件級注釋（代碼級自指）

位置: 每個源代碼文件的開頭

格式要求:

/**
 * 一旦我被更新，務必更新我的開頭注釋，以及所屬的文件夾的 md。
 * 
 * INPUT (依賴): 依賴外部的什麼
 * OUTPUT (提供): 對外提供什麼
 * POSITION (地位): 在系統局部的地位是什麼
 */

範例:

/**
 * 一旦我被更新，務必更新我的開頭注釋，以及所屬的文件夾的 md。
 * 
 * INPUT: User 模型、JWT secret (環境變數)
 * OUTPUT: verifyToken(), generateToken() 函數
 * POSITION: 認證系統的核心工具層，被 middleware.ts 調用
 */

export function verifyToken(token: string) { ... }
export function generateToken(userId: string) { ... }

分形特性：自蔓延的化學反應

這套方法的精妙之處在於形成了分形結構：

層級	自指機制	向上傳播	向下傳播
文件	開頭注釋聲明更新規則	更新時通知資料夾文檔	-
資料夾	文檔開頭聲明更新規則	結構變化時通知上級	文件清單反映內部變化
項目	根文檔定義更新契約	-	要求所有子層級遵循

自蔓延效果:

1. 修改一個文件 → 更新文件開頭注釋
2. 文件注釋要求 → 更新所屬資料夾的 README.md
3. 資料夾文檔聲明 → 若結構變化則通知上級
4. 局部影響整體，整體影響局部

為什麼這對 AI 開發至關重要

傳統問題

• AI 難以理解大型代碼庫的全局架構
• 局部修改容易導致文檔過時
• 文件間依賴關係不明確

分形文檔的解決方案

• 極簡說明（3 行以內）→ AI 可快速掌握每層職責
• INPUT/OUTPUT/POSITION → 明確依賴關係，避免破壞性修改
• 自指更新規則 → AI 被強制要求維護文檔同步

實際效果

"一旦這樣做，化學反應就自蔓延開來。局部影響整體，整體影響局部。美得像他媽的詩一樣。"
— Jiaxi Cui

實踐檢查清單

建立分形文檔架構時的檢查項：

• [ ] 根目錄 CLAUDE.md 或 README.md 明確要求更新子文檔
• [ ] 每個資料夾都有 README.md 並包含：
  • [ ] 開頭更新聲明
  • [ ] 3 行以內架構說明
  • [ ] 文件名 + 地位 + 功能清單
• [ ] 每個源代碼文件開頭包含：
  • [ ] 更新聲明
  • [ ] INPUT（依賴）
  • [ ] OUTPUT（提供）
  • [ ] POSITION（地位）
• [ ] 測試更新傳播：修改一個文件後，檢查是否觸發相關文檔更新

延伸閱讀

• 《哥德爾、埃舍爾、巴赫：集異璧之大成》— 自指與遞歸結構的哲學探討
• ai-coding-kit GitHub 倉庫 — 包含完整的 AI 編碼協議範例

---

這篇文章已整理完成，涵蓋了分形文檔架構的核心概念、三層規則、分形特性、對 AI 開發的價值，以及實踐檢查清單。內容保留了原作者的核心觀點和那句精彩的「美得像他媽的詩一樣」評語。