昨天建立了標準化的開發流程，每個任務都有了完整的文件記錄。

但很快我就遇到新問題：

docs/
├── task1.md
├── design.md
├── bug_fix_2.md
├── architecture_notes.txt
├── meeting_20250110.md
├── api_spec.json
└── ... 更多散落的文件

這就像把所有衣服都丟在一個大箱子裡，要找白襯衫時得翻遍整個箱子。

當文件數量超過 10 個，找東西就變成一場災難。

文件總編輯的思考

我戴上「文件總編輯」的帽子，開始思考一個核心問題：文件的目的是什麼？是為了記錄，還是為了被找到和使用？

答案顯而易見。

文件的價值在於被閱讀和使用。

一個好的文件架構應該要易於導航，新人也能快速找到需要的資訊。每種文件都有明確的歸屬，職責清晰。隨著專案成長不會變得混亂，能夠持續擴展。還要能配合開發流程的需要，支援整個工作流程。

設計理念：職責分離原則

我採用了軟體設計中的「關注點分離」（Separation of Concerns）原則來設計文件架構：

docs/
├── product/        # 產品文件（WHAT & WHY）
├── architecture/   # 架構文件（HOW）
├── design/         # UI/UX 設計
├── tasks/          # 開發任務
├── roles/          # SDLC AI 增強角色
└── function/       # 功能參考

每個目錄都有明確的職責。

product/ 定義做什麼和為什麼，回答 What 和 Why 的問題，主要給產品經理和利害關係人看。

architecture/ 定義如何實現，回答 How 的問題，是架構師和開發者的領域。

design/ 定義外觀和體驗，關注 Look 和 Feel，設計師和前端開發者會常來這裡。

tasks/ 管理開發任務，追蹤 When 和 Who，整個開發團隊都會用到。

roles/ 定義 AI 協作角色，說明 Who helps，讓 AI 助手和團隊成員理解如何協作。

function/ 放功能參考資料，是所有人的 Reference。

每個目錄的設計考量

Product - 產品文件

product/
├── requirements/        # 需求定義
├── features/           # 功能規格
│   ├── FEATURE-001-project-management/
│   ├── FEATURE-002-event-sourcing/
│   ├── local-first-summary.md
│   └── saas-architecture.md
├── roadmap/            # 產品路線圖
└── issues/             # Issue 管理

設計考量：

• 使用 FEATURE-XXX 編號系統，方便追蹤和引用
• 每個功能一個資料夾，包含完整的規格和相關文件
• 區分需求（what）和功能（how to implement）

Architecture - 架構文件

architecture/
├── README.md           # 架構總覽
├── decisions/          # 架構決策 (ADR/MADR)
│   ├── 0001-use-clean-architecture-with-mvi.md
│   ├── 0002-use-sqldelight-migration.md
│   └── README.md
├── components/         # 元件設計
├── database/          # 資料庫設計
└── patterns/          # 設計模式

設計考量：

• decisions/ 使用 ADR 格式記錄架構決策
• 編號系統確保決策的時間順序
• 分離靜態設計（components）和動態決策（decisions）

Design - UI/UX 設計

design/
├── style-guide/        # 設計系統
│   └── style_guide.md  # Grimo 設計語言
├── components/         # UI 元件規格
├── assets/            # 設計資源
│   ├── bg/           # 背景圖片
│   ├── logo/         # 標誌設計
│   └── ui/           # UI 參考圖
└── logo.md           # 標誌設計說明

設計考量：

• 區分規範（style-guide）和資源（assets）
• 支援二進位檔案（圖片、設計稿）
• 維持設計系統的一致性

Tasks - 任務管理

tasks/
├── README.md              # 任務管理指南
├── active/                # 進行中任務（未來擴展）
├── completed/             # 已完成任務（未來擴展）
├── backlog/              # 待辦任務（未來擴展）
├── templates/            # 任務模板
└── XXXX_type_description.md  # 實際任務文件

設計考量：

• 所有任務平鋪在 tasks/ 目錄下，用編號排序
• README.md 作為任務儀表板，集中管理狀態
• 預留 active/completed/backlog 目錄供未來擴展

Roles - AI 協作角色

roles/
├── README.md                               # 角色總覽
├── technical-implementation-architect.md   # TIA 角色
├── architecture-research-specialist.md     # ARS 角色
└── solution-architect.md                   # SA 角色

設計考量：

• 每個角色一個文件，定義明確職責
• 支援 AI 助手理解和扮演不同角色
• 促進人機協作的標準化

文件索引系統：README.md 的藝術

每個目錄都有自己的 README.md，扮演不同角色：

根目錄 README（總圖書管理員）

# Grimo 專案文件

## 文件結構總覽
[提供全局視角，引導讀者到正確位置]

## 文件維護狀態
[顯示各類文件的健康狀態]

## 快速開始
[新人入門指南]

子目錄 README（分區管理員）

# 任務文件指南

## 目錄
[本區導航]

## 文件類型
[分類說明]

## 工作流程
[使用指南]

## 任務清單
[即時狀態追蹤]

實戰經驗：演化式架構

這個文件架構不是一開始就設計好的，而是演化出來的：

V1：混沌期

docs/
└── 所有文件混在一起

V2：初步分類

docs/
├── design/
├── tasks/
└── notes/

V3：職責分離

docs/
├── product/
├── architecture/
├── design/
├── tasks/
└── roles/

V4：精細化管理（現在）

加入子目錄、編號系統、模板、索引

意外收穫：AI 助手的最愛

這個結構化的文件架構帶來一個意外收穫 - AI 助手（Claude）的效率大幅提升：

以前的對話是這樣：

我：幫我實作專案管理功能
AI：請問具體需求是什麼？有設計文件嗎？
我：有，但我忘記在哪了...

現在變成這樣：

我：幫我實作 FEATURE-001
AI：我看到 product/features/FEATURE-001-project-management/
    已經有完整規格，現在開始實作...

AI 現在可以快速定位相關文件、理解專案脈絡、準確執行任務，還能在正確位置更新文件。

維護哲學：活文件 vs 死文件

文件架構設計好了，但如何保持活力？我的原則是：

活文件特徵

與程式碼同步更新、有明確的維護者、被經常引用和查閱、包含實用的資訊。

死文件特徵

寫完就沒更新過、沒人知道誰負責、從來沒被引用、資訊過時或錯誤。

關鍵策略：

1. 文件即程式碼：用 Git 管理，可追蹤變更
2. 持續更新：每次改程式碼時更新相關文件
3. 定期審查：每月檢查文件健康度
4. 自動化檢查：用工具檢查死連結、過期內容

實用工具：文件管理輔助

我使用的一些實用技巧：

1. 文件模板

# 快速創建新任務
cp docs/tasks/templates/functional-requirement-example.md \
   docs/tasks/0008_fr_new_feature.md

2. 狀態統計

# 統計任務狀態
grep "## 狀態" docs/tasks/*.md | sort | uniq -c

3. 文件地圖生成

# 生成文件樹狀圖
tree docs -I "*.png|*.jpg" > docs/structure.txt

4. Markdown 連結檢查

# 檢查死連結
markdown-link-check docs/**/*.md

設計 docs/ 架構的 10 個原則

經過這段時間的實踐，我總結出設計文件架構的 10 個原則：

1. 單一職責：每個目錄有明確的職責範圍
2. 扁平優先：避免過深的巢狀結構
3. 編號系統：重要文件使用編號便於排序和引用
4. 索引檔案：每個目錄都有 README.md 作為索引
5. 模板標準：提供模板確保一致性
6. 命名規範：統一的命名讓搜尋更容易
7. 版本追蹤：所有文件納入 Git 管理
8. 交叉引用：文件之間可以互相連結
9. 狀態可見：重要資訊的狀態要一目了然
10. 演化友善：架構要能隨專案成長而擴展

好的架構讓知識有序傳承

一個好的文件架構就像一個井井有條的圖書館，每本書都有它的位置，每個人都能找到需要的資訊。

對於一人公司來說，這特別重要。

你既是作者也是讀者。你需要在不同角色間切換。你的 AI 助手需要理解專案。你的未來自己會感謝現在的你。

文件架構反映了你的思維架構。清晰的文件架構，代表清晰的專案思維。

今日金句

「混亂的文件是知識的墳墓，有序的架構讓知識永生。」

關於作者：Sam，一人公司創辦人。正在打造 Grimo，一個智能任務管理和分配平台。

專案連結：GitHub - grimostudio