@@ -1,6 +1,6 @@
---
name : doc-funcs
description : 先判斷專案語言，再為每個 function 與每個指令檔（腳本／CI／部署設定檔）建立 .docs/ 草稿並補齊註解，並整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿；由使用者選擇實作方式後寫回原始碼／覆蓋指令檔／更新 workflow readme，接著保守優化被文件化原始碼的效能與排版，最後重建 README 專案列表、功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、為腳本或 CI/部署設定檔逐行加註解、整理 workflow README、建立 .docs 草稿，或提到 doc-funcs、function 文件化、指令檔註解、workflow 文件化、XML documentation comments 時使用此 skill。
description : 先判斷專案語言，再為每個 function 與每個指令檔（腳本／CI／部署設定檔）建立 .docs/ 草稿並補齊註解，並整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿；由使用者選擇實作方式後寫回原始碼／覆蓋指令檔／更新 workflow readme， 並依專案內多數檔案的大小寫命名慣例正規化 Dockerfile 與 README 檔名（含同步更新引用）， 接著保守優化被文件化原始碼的效能與排版，最後重建 README 專案列表、功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、為腳本或 CI/部署設定檔逐行加註解、整理 workflow README、建立 .docs 草稿，或提到 doc-funcs、function 文件化、指令檔註解、workflow 文件化、XML documentation comments 時使用此 skill。
---
# 補齊 function 與指令檔文件
@@ -13,7 +13,11 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
- 檢查專案檔與設定檔（例如 `*.csproj` /`*.sln` 、`package.json` 、`pyproject.toml` /`requirements.txt` 、`go.mod` 、`pom.xml` /`build.gradle` 、`Cargo.toml` 等）、主要副檔名分布與 README，推斷主要語言。
- 依語言決定 function 註解格式：C# 用 XML documentation comments（ `<summary>` /`<param>` /`<remarks>` ）；其他語言改用該語言慣用的文件註解格式（例如 JS/TS 用 JSDoc、Python 用 docstring、Go 用 doc comment、Java 用 Javadoc）。
- 在 `.docs/doc-funcs-index.md` 開頭記錄判斷出的主要語言與將採用的註解格式，作為後續所有 subagent 的依據。
- 統計專案檔名的大小寫慣例，作為後續 `Dockerfile` 與 README 檔名正規化（第 6 步、第 8 步） 的依據：
- 樣本範圍排除 generated/bin/obj/.git/.docs 與第三方依賴；把檔名歸類為「全大寫」（如 `README.md` 、`CHANGELOG.md` ）、「首字大寫」（如 `Dockerfile` 、`Makefile` ）、「全小寫」（如 `readme.md` 、`dockerfile` ）等風格。
- 優先以同類型檔案為樣本（README 看其他 `*.md` 文件檔、Dockerfile 看其他容器/建置相關檔）；同類型樣本不足 3 個時，改看全專案檔名分布。
- 只有某一風格明顯過半才視為「專案多數慣例」；無明顯多數時不做檔名正規化，保留原檔名。
- 在 `.docs/doc-funcs-index.md` 開頭記錄判斷出的主要語言、將採用的註解格式，以及檔名命名慣例的判斷結果（多數風格或「無明顯多數」）。
## 第 1 步：掃描 function 與指令檔
@@ -93,6 +97,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
- function 草稿：依第 0 步判斷的語言把建議文件寫入原始碼（C# 用 XML documentation comments）。註解盡量使用繁體中文；保留既有正確文件，僅補齊缺漏或明顯不足處；此步驟不得為了文件改變 runtime 行為。
- 指令檔草稿：用草稿內容**覆蓋原始指令檔**（草稿已是含用途/日期/逐行註解的完整版本）。
- Dockerfile 檔名正規化：覆蓋 Dockerfile 類指令檔時，若實際檔名大小寫與第 0 步判斷的專案多數命名慣例不符（例如專案多數為全小寫但檔名為 `Dockerfile` ，或反之），用 `git mv` 把檔名調整為慣例風格；在大小寫不敏感的檔案系統上需兩段式改名（先 `git mv Dockerfile Dockerfile.tmp` 再 `git mv Dockerfile.tmp dockerfile` ）。改名後必須同步更新專案內引用該檔名的位置（例如 docker-compose 的 `dockerfile:` 、CI workflow 的 build 參數、文件內連結），確保建置行為不變；此檔名與引用調整不視為變更指令邏輯。第 0 步判斷為「無明顯多數」時保留原檔名，不做改名。
- workflow README 草稿：用草稿內容**覆蓋 `.gitea/workflows/readme.md` **，保留 workflow 實際設定不變，僅整理成說明文件。
- 若選「逐個草稿實作」，每完成一個就回報並等待使用者確認。
- 若遇到大量目標，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 `.docs/doc-funcs-index.md` 標記 pending。
@@ -113,7 +118,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
## 第 8 步：重建 README
補齊後，重建專案根目錄的 README.md 。若根目錄已有 README.md ，先刪除既有檔案，再產生新的 README.md ；不要保留或合併舊內容。README 必須包含更新時間，更新時間必須使用台灣時區（Asia/Taipei）並固定輸出為 `yyyy/MM/dd HH:mm:ss` 格式，例如 `2026/06/22 18:30:05` ；README 必須在功能列表前加入專案列表，並只列出所有專案內的公開方法（public method、public constructor、public extension method、public operator），但不得列出單元測試方法；若方法位於測試專案、測試檔案、測試型別，或帶有測試框架屬性/命名（例如 `Test` 、`Fact` 、`Theory` 、`TestMethod` 、`TestCase` 、`SetUp` 、`TearDown` 、`Initialize` 、`Cleanup` ），即使是 public 也要排除。產生 README 前，必須先為每個公開方法決定「最終功能名稱」：
補齊後，重建專案根目錄的 README。README 檔名依第 0 步判斷的專案多數命名慣例決定（例如多數全大寫用 `README.md` 、多數全小寫用 `readme.md` ）；第 0 步判斷為「無明顯多數」或無法判斷時，沿用既有 README 檔名，完全沒有既有 README 時預設 `README.md` （不論大小寫） ，先刪除既有檔案，再以慣例檔名 產生新的 README；不要保留或合併舊內容，也不得同時留下兩種大小寫的 README。若檔名大小寫因此改變，需同步更新專案內引用舊 README 檔名的位置（例如文件連結、CI、套件描述檔） 。README 必須包含更新時間，更新時間必須使用台灣時區（Asia/Taipei）並固定輸出為 `yyyy/MM/dd HH:mm:ss` 格式，例如 `2026/06/22 18:30:05` ；README 必須在功能列表前加入專案列表，並只列出所有專案內的公開方法（public method、public constructor、public extension method、public operator），但不得列出單元測試方法；若方法位於測試專案、測試檔案、測試型別，或帶有測試框架屬性/命名（例如 `Test` 、`Fact` 、`Theory` 、`TestMethod` 、`TestCase` 、`SetUp` 、`TearDown` 、`Initialize` 、`Cleanup` ），即使是 public 也要排除。產生 README 前，必須先為每個公開方法決定「最終功能名稱」：
- 預設功能名稱為 `Type.Method` 。
- 若公開方法所在的型別簡名在不同專案或不同命名空間中重複，最終功能名稱不得只使用 `Type.Method` ，必須在型別前加入可辨識的專案或模組前綴，格式為 `Module.Type.Method` 。例如 `Hangfire.ServiceCollectionExtension.AddHangfireOptions` 、`Hangfire.SqlServer.ServiceCollectionExtension.AddSqlServerHangfire` 、`Swagger.ServiceCollectionExtension.AddSwagger` 、`Swagger.ApplicationBuilderExtension.UseSwaggerUI` 。
@@ -157,7 +162,8 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do
## 重要限制
- 不要修改 generated/bin/obj/.git/.docs 以外的非原始碼/非指令檔，除非是建立草稿、索引，依流程實作註解、依草稿覆蓋指令檔、優化本次被文件化原始碼，或 刪除並重建根目錄 README.md 。
- 不要修改 generated/bin/obj/.git/.docs 以外的非原始碼/非指令檔，除非是建立草稿、索引，依流程實作註解、依草稿覆蓋指令檔、優化本次被文件化原始碼、 刪除並重建根目錄 README，或依第 0 步判斷的專案多數命名慣例正規化 `Dockerfile` 與 README 檔名（含同步更新引用舊檔名的位置） 。
- `Dockerfile` 與 README 的檔名正規化只在專案多數慣例明確（某一風格明顯過半）時執行；無明顯多數就保留原檔名。改名時必須同步更新所有引用，不得造成建置或連結失效。
- 不要新增與文件無關的 helper、測試或重構。
- 草稿是實作依據，不能跳過；所有草稿一律由 subagent 產生。
- function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。