33 lines
3.5 KiB
Markdown
33 lines
3.5 KiB
Markdown
---
|
||
name: doc-funcs
|
||
description: 為目前專案的每個 function 建立 .docs/ 草稿並補齊 XML 文件，最後更新 README 功能目錄。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。
|
||
---
|
||
|
||
# 補齊 function 文件
|
||
|
||
你要替目前工作區內的專案補齊 function XML 文件。請依序完成：
|
||
|
||
1. 掃描專案內所有可文件化的 function/method。以目前 repo 的主要語言為準；若是 C#，包含 public/internal/protected/private method、constructor、extension method、operator，排除 generated/bin/obj/.git/.docs 與第三方依賴。
|
||
2. 建立 .docs/ 目錄（若不存在）。先產生總索引 .docs/doc-funcs-index.md，列出所有 function：檔案、型別、簽名、是否已有 XML doc、草稿檔路徑。
|
||
3. 針對每一個 function 派出一個 subagent。每個 subagent 只分析指定 function 與必要上下文，不直接改 code；回傳並在 .docs/ 底下建立一份草稿。草稿檔名需可追溯來源，例如 .docs/doc-funcs/{relative-path}.{type}.{function}.md。草稿內容必須包含：
|
||
- 位置：檔案與行號
|
||
- 簽名：完整簽名
|
||
- 行為分析：方法實際做什麼、重要分支、副作用、例外/失敗行為
|
||
- 建議 `<summary>`：根據功能產生，不要只改寫方法名稱
|
||
- 建議 `<param>`：每個參數的用途、限制、null/empty 行為（能從 code 推論才寫；不能確定就標註需人工確認）
|
||
- 建議 `<remarks>`：至少一個使用情境，描述何時呼叫、前置條件、結果或注意事項
|
||
4. 在實作到原始碼之前，主 agent 必須檢查所有草稿內容是否以繁體中文為主、英文為輔，且沒有任何亂碼、編碼錯誤、不可讀字元或明顯破損文字。若發現問題，先修正草稿並重新檢查，通過後才能進入下一步。
|
||
5. 所有草稿完成且通過檢查後，主 agent 要閱讀草稿並實作到原始碼。若是 C#，使用 XML documentation comments：`<summary>`、`<param>`、`<remarks>`。註解盡量使用繁體中文；保留既有正確文件，僅補齊缺漏或明顯不足處；不要為了文件改變 runtime 行為。
|
||
6. 若遇到大量 function，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 .docs/doc-funcs-index.md 標記 pending。
|
||
7. 補齊後，產生或更新專案根目錄的 README.md 功能目錄。功能目錄必須包含更新時間、功能名稱、使用範例；若 README.md 已有既有內容，保留既有內容並以最小變更更新或新增功能目錄區塊。
|
||
8. README 功能目錄完成後，刪除本次產生的所有草稿與索引：`.docs/doc-funcs/` 與 `.docs/doc-funcs-index.md`。若 `.docs/` 內已無其他內容，可一併移除空的 `.docs/` 目錄；不得刪除使用者既有的 `.docs/` 其他檔案。
|
||
9. 完成後執行合適的格式化/建置或至少語法驗證；若無法執行，說明原因。
|
||
|
||
## 重要限制
|
||
|
||
- 不要修改 generated/bin/obj/.git/.docs 以外的非原始碼檔，除非是建立草稿與索引。
|
||
- 不要新增與文件無關的 helper、測試或重構。
|
||
- 草稿是實作依據，不能跳過。
|
||
- 若 function 行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
|
||
- 原始碼註解與 README 功能目錄盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。
|