文檔結構管理 Skill

設計意義

標準化專案文檔結構，確保所有 README 和檔案註解格式一致，避免資訊重複和認知負擔。

核心理念：層級聚攏結構

CLAUDE.md（根）─ 專案規範 + 頂層目錄索引
    │
    ├── {dir}/README.md（上層）─ 設計意義 + 索引 + 參考
    │       │
    │       └── {subdir}/README.md（下層）─ 設計意義 + 索引 + 參考
    │               │
    │               └── {file}.js ─ 檔案頂部註解（Position + Input + Output + 職責）

三個原則：

1. 上層索引下層：每個 README 只負責索引直接下層內容
2. 設計意義穩定：說明「為什麼」，不隨程式修改而變
3. 重構才重寫：只有架構變動時才更新設計意義

使用流程

建立新 README

1. 確定目錄層級（頂層 or 子目錄）
2. 讀取對應模板：
   • 頂層：templates/readme-top.md
   • 子目錄：templates/readme-sub.md
3. 填入三個必要欄位：設計意義、索引、參考
4. 確認不包含禁止內容

添加檔案註解

1. 確定檔案類型，選擇對應模板：

   語言	模板
   JavaScript/TypeScript	header-js.txt
   Python	header-py.txt
   Dart	header-dart.txt
   Go	header-go.txt
   HTML	header-html.txt
   PHP	header-php.txt
   Java	header-java.txt
   C# (.NET)	header-csharp.txt
   YAML	header-yaml.txt
   Shell/Bash	header-shell.txt

   不支援註解的格式：JSON、Markdown、純資料檔案 → 由 README 說明

   自動排除：名稱包含 log 的資料夾和檔案（不區分大小寫）

2. 填入四個必要欄位：

   • Position：功能定位（在系統架構中的位置和角色）
   • Input：外部依賴（依賴哪些模組或服務）
   • Output：對外提供（導出的介面、類別或函數）
   • 職責：做什麼（1-3 項主要職責）

驗證工具

連結驗證

驗證所有 README.md 的內部連結是否有效：

# 使用當前目錄
uv run validate-readme-links.py

# 指定專案路徑
uv run validate-readme-links.py /path/to/project

結構檢查

檢查預期的 README.md 是否存在：

# 使用當前目錄
uv run check-doc-structure.py

# 指定專案路徑
uv run check-doc-structure.py /path/to/project

參考文檔

• README 格式標準
• 檔案註解標準