Skip to content

LESSON_GUIDE.md

Latest commit

 

History

History
245 lines (206 loc) · 6.73 KB

LESSON_GUIDE.md

File metadata and controls

245 lines (206 loc) · 6.73 KB

場景 7：Agent 文檔大師

學習目標

  • 體驗 Agent 文檔專家：從程式開發者升級為文檔專家
  • 讓 Agent 自主理解程式碼並生成完整技術文檔體系
  • 學習如何讓 Agent 創建多種類型的開發者文檔
  • 掌握 Agent 驅動的文檔自動化流程

場景說明

您有一個功能完整的任務管理 API 系統 (taskManager.js)，包含用戶管理、任務管理、項目管理等功能，但完全缺乏文檔。程式碼中沒有註解、沒有 API 說明、沒有使用指南。

與傳統手動撰寫文檔不同，您將學習如何讓 Agent 作為技術文檔專家，從深度理解程式碼架構開始，自主生成完整的文檔體系。

專案結構

07-documentation/
├── README.md           # 本檔案
├── taskManager.js      # 待文檔化的 API 系統（300+ 行程式碼）
└── docs/              # Agent 將生成的文檔目錄
    ├── API.md         # API 參考文檔
    ├── GUIDE.md       # 開發者指南
    ├── DEPLOYMENT.md  # 部署說明
    ├── ARCHITECTURE.md # 架構文檔
    └── examples/      # 使用範例

文檔挑戰

現有程式碼狀況

  • 300+ 行程式碼：複雜的 Express.js API
  • 0 註解：完全沒有程式碼註解
  • 0 文檔：沒有任何使用說明
  • 複雜功能：JWT 認證、資料驗證、權限控制
  • 多個模組：用戶、任務、項目、統計等

需要的文檔類型

  1. ** API 參考文檔**：所有端點的詳細說明
  2. ** 開發者指南**：快速開始、使用範例
  3. ** 程式碼註解**：JSDoc 格式的函數註解
  4. ** 部署文檔**：環境配置、部署步驟
  5. 🏗️ 架構說明：系統設計、數據流
  6. ** 測試指南**：如何測試各個 API

Demo 劇本

重點：Agent 文檔專家體驗

在這個場景中，Agent 將展現其作為技術文檔專家的能力，不只是生成文檔，而是深度理解系統並創建高品質的技術文檔。

階段 1：Agent 系統分析 (3分鐘)

步驟 1：讓 Agent 深度分析 API 系統

@workspace 請深度分析 taskManager.js 這個任務管理 API 系統：
1. 理解整體架構和設計模式
2. 識別所有 API 端點和其功能
3. 分析認證機制和權限控制
4. 理解數據模型和業務邏輯
5. 評估程式碼品質和潛在問題
提供詳細的分析報告

使用模式：Ask

** 觀察重點**：

  • Agent 會仔細閱讀整個程式碼
  • 理解程式碼的架構和邏輯
  • 識別文檔化的重點

步驟 2：讓 Agent 規劃文檔架構

基於你的分析，請設計完整的文檔架構：
1. 需要哪些類型的文檔？
2. 每種文檔的目標讀者是誰？
3. 文檔之間如何組織和連結？
4. 優先級順序如何安排？
說明你的設計理由

使用模式：Ask

階段 2：Agent 文檔生成 (10分鐘)

步驟 3：讓 Agent 生成 API 參考文檔

請為 taskManager.js 生成完整的 API 參考文檔，要求：
1. 所有端點的詳細說明
2. 請求/回應格式和範例
3. 錯誤碼說明
4. 認證需求
5. 使用 Markdown 格式
儲存為 docs/API.md

使用模式：Agent

步驟 4：讓 Agent 創建開發者指南

創建開發者快速入門指南，包含：
1. 系統介紹和特色
2. 環境設置步驟
3. 認證流程說明
4. 常見使用場景的完整範例
5. 最佳實踐建議
儲存為 docs/GUIDE.md

使用模式：Agent

步驟 5：讓 Agent 為程式碼加註解

為 taskManager.js 添加完整的 JSDoc 註解：
1. 每個函數的用途說明
2. 參數和返回值描述
3. 使用範例
4. 錯誤處理說明
5. 相關連結
直接更新原始檔案

使用模式：Agent

步驟 6：讓 Agent 生成架構文檔

生成系統架構文檔，包含：
1. 系統整體架構圖（ASCII art）
2. 資料模型說明
3. API 流程圖
4. 安全機制說明
5. 擴展性設計
儲存為 docs/ARCHITECTURE.md

使用模式：Agent

階段 3：Agent 文檔優化 (2分鐘)

步驟 7：讓 Agent 創建使用範例

創建實用的程式碼範例：
1. 完整的用戶註冊和登入流程
2. 任務 CRUD 操作範例
3. 項目管理範例
4. 錯誤處理範例
5. 使用不同程式語言的客戶端範例
在 docs/examples/ 目錄下創建

使用模式：Agent

步驟 8：讓 Agent 生成部署文檔

創建生產環境部署指南：
1. 環境需求和依賴
2. 環境變數配置
3. Docker 部署方案
4. 雲端部署步驟（AWS/Azure）
5. 監控和日誌設置
儲存為 docs/DEPLOYMENT.md

使用模式：Agent

重點技巧

Agent 文檔專家特色：

  1. 深度理解：Agent 能理解複雜的程式碼邏輯
  2. 全面覆蓋：自主決定需要哪些文檔
  3. 品質保證：生成專業級的技術文檔
  4. 一致性：確保文檔風格和術語統一

有效的 Agent 指令：

  • "分析系統並生成完整文檔體系"
  • "創建開發者友好的使用指南"
  • "確保文檔的準確性和完整性"
  • "提供實用的程式碼範例"

避免的做法：

  • 不要限制 Agent 的文檔範圍
  • 不要忽略文檔的目標讀者
  • 不要跳過程式碼註解
  • 不要忘記實際使用範例

Demo 展示要點

Agent 能力展示：

  1. 理解能力：快速掌握 300+ 行程式碼的邏輯
  2. 組織能力：合理規劃文檔結構
  3. 表達能力：用清晰的語言解釋技術概念
  4. 完整性：涵蓋從入門到部署的所有環節

效率對比：

  • 傳統方式：手動撰寫需要 2-3 天
  • Agent 方式：10-15 分鐘生成完整文檔

預期成果

生成前

  • 程式碼註解： 0 行
  • API 文檔： 不存在
  • 使用指南： 不存在
  • 部署說明： 不存在
  • 新手友好度： 極低

生成後

  • 程式碼註解： 完整 JSDoc
  • API 文檔： 詳盡規範
  • 使用指南： 清晰易懂
  • 部署說明： 步驟完整
  • 新手友好度： 極佳

文檔品質指標

Agent 生成的文檔應達到：

  • 準確性：100% 符合程式碼實際行為
  • 完整性：涵蓋所有 API 和功能
  • 易讀性：清晰的結構和範例
  • 實用性：可直接用於開發
  • 維護性：易於後續更新

生成的文檔預覽

API.md 範例片段

## POST /api/users/register

註冊新用戶帳號。

### 請求格式
```json
{
  "username": "string",
  "email": "string",
  "password": "string"
}

回應格式

  • 成功 (201)
{
  "success": true,
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "createdAt": "2025-06-02T10:00:00Z"
  }
}

##  下一步
場景 8 將展示 **Agent 完全主導**，讓 Agent 完全主導端到端的專案開發，從需求分析到功能實現。