# equipment-documentation-manager

> Documentation architecture design and management for equipment projects. Use for: (1) Creating layered doc structure, (2) Determining content placement, (3) Managing change impact, (4) Simplifying redundant content. Triggers (CN): 文件架構、分層設計、文件該放哪、改了要更新哪些、文件太長、高內聚低耦合. Triggers (EN): doc structure, which file, change impact, simplify. Coordinated by: project-coordinator.

- Author: AdoisGod
- Repository: AdoisGod/ClaudeCodeWorkSpace
- Version: 20251215231856
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/AdoisGod/ClaudeCodeWorkSpace
- Web: https://mule.run/skillshub/@@AdoisGod/ClaudeCodeWorkSpace~equipment-documentation-manager:20251215231856

---

---
name: equipment-documentation-manager
description: "Documentation architecture design and management for equipment projects. Use for: (1) Creating layered doc structure, (2) Determining content placement, (3) Managing change impact, (4) Simplifying redundant content. Triggers (CN): 文件架構、分層設計、文件該放哪、改了要更新哪些、文件太長、高內聚低耦合. Triggers (EN): doc structure, which file, change impact, simplify. Coordinated by: project-coordinator."
---

# Equipment Documentation Manager

## 核心理念

### 分層的本質
```
分層 = 漸進式揭露 + 變動隔離

目的：
1. 需要時到對的層找資料（快速定位）
2. 修改時只動單一文件 + README（最小影響範圍）
3. 越前面的層越穩定，越後面的層越常變動
```

### 高內聚低耦合
| 原則 | 實踐 |
|------|------|
| **高內聚** | 相同功能/概念/性質 → 同一份文件 |
| **低耦合** | 文件間不複製內容，只用「詳見 XX.md」指向 |
| **最小影響** | 改 A 功能 → 只改 A 文件 + 更新 README 索引 |

### Claude 協作導向
文件結構優先讓 Claude 能快速定位資訊，再由 Claude 輸出人需要的內容。

| 原則 | 實踐 |
|------|------|
| 文件名即內容 | 編號 + 關鍵字，搜尋容易命中 |
| 開頭即摘要 | 每份文件開頭說明「這是什麼」|
| 查詢指南 | README 提供「找 XX 去哪」對照表 |
| 單一事實來源 | 每個概念只在一處定義 |

---

## 快速決策指引

**建立新專案文件架構？**
→ 見 Section 1：層級定義

**這段內容該放哪個文件？**
→ 見 Section 2：內容歸屬判斷

**改了 A，要更新哪些文件？**
→ 見 Section 3：變動管理

**文件太長/太雜，怎麼處理？**
→ 見 Section 4：精簡原則

**需要詳細的寫作格式？**
→ 見 `references/writing-guide.md`

**需要一致性檢查？**
→ 見 `references/consistency-checkers.md`

---

## Section 1：層級定義

### 通用層級框架

```
00-09  總覽導航    README、設備概述（幾乎不動）
10-19  概念定義    狀態定義、模式定義（很少動）
20-29  硬體規格    軸、感測器、致動器、模組（硬體確定後穩定）
30-39  動作序列    基本動作、檢測序列（開發中調整）
40-49  安全防護    互鎖規則、安全電路（需求確定後穩定）
50-59  介面定義    PC-PLC 交握、記憶體映射（開發中常調整）
60-69  設計規範    命名規則、編碼標準（很少動）
70-79  預留
80-89  異常管理    異常代碼、處理流程（開發中常調整）
90-99  預留
```

### 穩定性排序
```
最穩定 ─────────────────────────────────────── 最常變動

00-09    10-19    20-29    30-39    40-49    50-59    80-89
總覽     概念     硬體     序列     安全     介面     異常
```

### 依專案調整
- **純軟體專案**：省略 20-29 硬體層，10 層放架構概念
- **簡單設備**：30-39 可合併為單一文件
- **複雜設備**：30-39 可拆分為多個子文件（如 31-common, 32-stage1, 33-stage2）

---

## Section 2：內容歸屬判斷

### 判斷流程
```
這段內容是關於...

「設備是什麼」          → 00-09（總覽）
「狀態/模式怎麼定義」   → 10-19（概念）
「有哪些硬體元件」      → 20-29（硬體）
「動作怎麼執行」        → 30-39（序列）
「什麼情況不能動」      → 40-49（安全）
「PC 和 PLC 怎麼溝通」  → 50-59（介面）
「命名/編碼怎麼規定」   → 60-69（規範）
「出錯怎麼處理」        → 80-89（異常）
```

### 歸屬衝突處理
當內容可能屬於多個層級時：

| 情境 | 決策 |
|------|------|
| 序列中用到的軸規格 | 軸規格放 20 層，序列只寫「使用 Conv_Y1」|
| 序列中的 PC 交握細節 | 交握放 50 層，序列只寫「詳見 53.md」|
| 安全規則影響的序列 | 安全規則放 40 層，序列引用「受 INT-005 限制」|

### 拆分原則
單一文件超過 300 行時，考慮拆分：
- 依**功能模組**拆（如：載台1序列、載台2序列）
- 依**變動頻率**拆（穩定的放一起，常改的放一起）
- 拆分後在 README 更新索引

---

## Section 3：變動管理

### 依賴方向單向化
```
低層 ← 高層（高層依賴低層，低層不知道高層）

00-README ← 被所有文件引用，但不引用任何文件內容
    ↑
20-硬體   ← 被 30-序列 引用
    ↑
30-序列   ← 被 50-介面 引用
    ↑
50-介面
```

### 變動影響判斷

| 變動類型 | 要改的文件 | 不用改的文件 |
|---------|-----------|-------------|
| 新增硬體 | 20 層 + README 索引 | 30/40/50 層（等要用到再改）|
| 新增序列 | 30 層 + README 索引 | 20 層（硬體已存在）|
| 修改 PC 交握 | 50 層 | 30 層（只寫「詳見 5x.md」）|
| 新增異常代碼 | 80 層 + README 索引 | 其他層 |
| 修改安全規則 | 40 層 + README 索引 | 30 層（只引用規則編號）|

### 關鍵原則：引用而非複製
```markdown
❌ 耦合寫法（30 層內文）：
「MR1204: Trigger, MR1205: Permit, MR1206: MoveDone, MR1207: PhotoDone」

✅ 解耦寫法（30 層內文）：
「交握協議：LineScan 4 訊號（詳見 53.md）」
```

---

## Section 4：精簡原則

### 移除的內容類型
| 類型 | 範例 | 理由 |
|------|------|------|
| 過度解釋 | 「為什麼需要這個功能」| 讀者不需要被說服 |
| 重複說明 | 同一概念在多處展開 | 違反單一事實來源 |
| 操作指引 | 步驟 1、2、3... | 屬於操作手冊，非規格文件 |
| 實作細節 | 變數定義、程式邏輯 | 屬於程式碼，非規格文件 |
| 圖示效果有限 | ASCII art 流程圖 | 用文字或表格更清楚 |

### 保留的內容類型
| 類型 | 範例 | 理由 |
|------|------|------|
| 是什麼 | 功能定義、規格數值 | 核心資訊 |
| 怎麼判斷 | 條件、完成判定 | 驗證依據 |
| 特殊考量 | 安全優先、例外情況 | 避免誤用 |
| 引用指向 | 「詳見 XX.md」| 維持低耦合 |

### 精簡前後對照
```markdown
精簡前（608 行）：
- 設計理念說明
- 範例情境 × 5
- ASCII 流程圖
- 操作步驟 1-9
- 注意事項（安全/操作/維護）
- 偽代碼重複段落

精簡後（194 行）：
- 條件定義表
- 涉及元件表
- 記憶體位址表
- 交叉引用
```

---

## Section 5：README 設計

### README 的職責
1. **索引導航**：列出所有文件，說明找什麼去哪
2. **架構總覽**：說明分層邏輯
3. **快速查詢**：提供「問題 → 文件」對照表
4. **變動記錄**：主要版本變更摘要

### README 結構範本
```markdown
# [專案名稱] 技術知識庫

## 文件架構
[層級說明 + 文件清單]

## 快速查詢
| 想知道... | 查哪個文件 |
|-----------|-----------|
| XX 規格？ | 20-xx.md |
| XX 流程？ | 30-xx.md |

## 文件關係
[簡要說明依賴方向]

## 版本記錄
[主要變更摘要]
```

---

## 附錄：觸發詞對照

| 使用者說 | Claude 應該做 |
|---------|--------------|
| 「建立文件架構」| 依 Section 1 建議層級結構 |
| 「這該放哪」| 依 Section 2 判斷歸屬 |
| 「改了 X 要改什麼」| 依 Section 3 判斷影響範圍 |
| 「文件太長」| 依 Section 4 精簡或依 Section 2 拆分 |
| 「檢查一致性」| 見 `references/consistency-checkers.md` |
| 「寫作格式」| 見 `references/writing-guide.md` |

---

## 與 project-coordinator 協作

本 skill 可被 `project-coordinator` 協調，提供以下資訊：

### 提供給 coordinator
- 文件層級定義（Section 1）
- 變動影響規則（Section 3）
- 文件規格內容

### 接收 coordinator 請求
- 「工作紀錄提到 X，需要更新哪些文件？」
- 「檢查文件與工作進度是否同步」

### 協作觸發
當使用者說「檢查同步」「今天該更新什麼」時，由 `project-coordinator` 主導，本 skill 提供文件規格資訊。