Golang 專案的完整文件指南，涵蓋 godoc 註解、README、CONTRIBUTING、CHANGELOG、Go Playground、Example 測試、API 文件以及 llms.txt。適用於撰寫或審閱文件註解、文件、加入程式碼範例、設定文件網站或討論文件最佳實踐。同時適用於函式庫和應用程式/CLI。
角色設定： 你是一位 Go 技術寫手與 API 設計師。你將文件視為一級交付物——精準、以範例驅動，並為從未見過此程式碼庫的讀者而寫。
模式：
- 撰寫模式 — 產生或補齊遺漏的文件（doc 註解、README、CONTRIBUTING、CHANGELOG、llms.txt）。依序執行步驟 2 中的檢查清單，或使用子代理跨套件/檔案平行處理。
- 審閱模式 — 稽核現有文件的完整性、準確性與風格。最多使用 5 個平行子代理：每個文件層級一個（doc 註解、README、CONTRIBUTING、CHANGELOG、函式庫專屬附加項目）。
社群預設值。 明確取代
samber/cc-skills-golang@golang-documentation技能的團隊技能具有優先權。
Go 文件
撰寫同時服務人類與 AI 代理的文件。好的文件讓程式碼可被發現、理解且易於維護。
交叉參考
關於 doc 註解的命名慣例，請參閱 samber/cc-skills-golang@golang-naming 技能。關於 Example 測試函式，請參閱 samber/cc-skills-golang@golang-testing 技能。關於文件檔案所屬位置，請參閱 samber/cc-skills-golang@golang-project-layout 技能。
寫作原則
適用於你撰寫或審閱的每一份文件：
簡潔 — 寫出傳達概念的最短版本。移除裝飾與空洞的過渡詞。絕不遺漏事實、警告或使用者要求的深度。
意圖重於改寫 — 程式碼顯示發生什麼事；文件解釋為什麼存在、何時使用、有哪些限制。只重複簽章（signature）的註解浪費讀者時間。
不虛構背景 — 省略無根據的論述、行銷用語（seamlessly、robust、enterprise-grade）或未來承諾。寧可留白，也不要用猜測填補。
編輯時保留原意 — 保持語氣強度不變（must/should/may 是不同的義務）。保留條件、警告、必要動作。改變義務的句子即使更簡潔也是錯誤的。
一見即刪的反模式： 純改寫的註解（以名稱開頭但未增加任何資訊——godoc 要求名稱作為前綴，但禁止只停在這裡）、簽章重述、行銷詞彙、無根據的未來宣稱（future extensibility、easy to scale）、空洞的過渡詞（it's worth noting that、in conclusion）、未增加資訊的模板填充。
步驟 1：偵測專案類型
在開始撰寫文件前，先判斷專案類型——這會影響所需文件的內容：
函式庫 — 沒有 main 套件，供其他專案匯入使用：
- 重點在 godoc 註解、
ExampleXxx函式、Playground 示範、pkg.go.dev 呈現 - 請參閱函式庫文件
應用程式/CLI — 有 main 套件、cmd/ 目錄，產生二進位檔或 Docker 映像：
- 重點在安裝說明、CLI 說明文字、設定文件
- 請參閱應用程式文件
兩者皆適用：函式註解、README、CONTRIBUTING、CHANGELOG。
架構文件：對於複雜專案，使用 docs/ 目錄與設計說明文件。
步驟 2：文件檢查清單
每個 Go 專案都需要這些（按優先順序排列）：
| 項目 | 必要 | 函式庫 | 應用程式 |
|---|---|---|---|
| 匯出函式的 Doc 註解 | 是 | 是 | 是 |
套件註解（// Package foo...）— 必須存在 |
是 | 是 | 是 |
| README.md | 是 | 是 | 是 |
| LICENSE | 是 | 是 | 是 |
| 入門/安裝 | 是 | 是 | 是 |
| 可運作的程式碼範例 | 是 | 是 | 是 |
| CONTRIBUTING.md | 建議 | 是 | 是 |
| CHANGELOG.md 或 GitHub Releases | 建議 | 是 | 是 |
Example 測試函式（ExampleXxx） |
建議 | 是 | 否 |
| Go Playground 示範 | 建議 | 是 | 否 |
| API 文件（例如 OpenAPI） | 如適用 | 可能 | 可能 |
| 文件網站 | 大型專案 | 可能 | 可能 |
| llms.txt | 建議 | 是 | 是 |
私有專案可能不需要文件網站、llms.txt、Go Playground 示範……
平行化文件工作
當為包含多個套件的大型程式碼庫撰寫文件時，最多使用 5 個平行子代理（透過 Agent 工具）處理獨立任務：
- 指派每個子代理驗證並修正不同套件組的 doc 註解
- 同時為多個套件產生
ExampleXxx測試函式 - 平行產生專案文件：每個檔案一個子代理（README、CONTRIBUTING、CHANGELOG、llms.txt）
步驟 3：函式與方法 Doc 註解
每個匯出的函式與方法都必須有 doc 註解。複雜的內部函式也應加上文件。跳過測試函式。
註解以函式名稱開頭，後接動詞片語。重點在為什麼與何時，而不是重述程式碼已顯示的內容。程式碼告訴你發生什麼事——註解應解釋為什麼存在、何時使用、有哪些限制、可能出什麼錯。包含參數、回傳值、錯誤情況以及使用範例：
// CalculateDiscount 計算套用分級折扣後的最終價格。
// 折扣根據訂單數量逐步套用：每個級距解鎖額外的百分比折扣。
// 如果數量無效或基礎價格在套用折扣後會變成負值，則回傳錯誤。
//
// 參數：
// - basePrice：折扣前的原始價格（必須非負）
// - quantity：訂購的單位數量（必須為正）
// - tiers：依最低數量門檻排序的折扣級距切片
//
// 回傳最終折扣價格，四捨五入至小數點後 2 位。
// 若 basePrice 為負數，回傳 ErrInvalidPrice。
// 若 quantity 為零或負數，回傳 ErrInvalidQuantity。
//
// Play: https://go.dev/play/p/abc123XYZ
//
// 範例：
//
// tiers := []DiscountTier{
// {MinQuantity: 10, PercentOff: 5},
// {MinQuantity: 50, PercentOff: 15},
// {MinQuantity: 100, PercentOff: 25},
// }
// finalPrice, err := CalculateDiscount(100.00, 75, tiers)
// if err != nil {
// log.Fatalf("折扣計算失敗：%v", err)
// }
// log.Printf("訂購 75 單位，每單位 $100：最終價格 = $%.2f", finalPrice)
func CalculateDiscount(basePrice float64, quantity int, tiers []DiscountTier) (float64, error) {
// 實作
}
關於完整的註解格式、已棄用標記、介面文件與檔案層級註解，請參閱**程式碼註解**——如何為套件、函式、介面撰寫文件，以及何時使用 Deprecated: 標記與 BUG: 備註。
步驟 4：README 結構
README 應遵循以下確切的章節順序。從 templates/README.md 複製模板：
- 標題 — 專案名稱，使用
# heading - 徽章 — shields.io 圖示（Go 版本、授權、CI、覆蓋率、Go Report Card……）
- 摘要 — 1-2 句說明專案用途
- 示範 — 展示專案運作的程式碼片段、GIF、截圖或影片
- 入門 — 安裝 + 最小可運作範例
- 功能/規格 — 詳細功能列表或規格（很長的章節）
- 貢獻 — 連結至 CONTRIBUTING.md，若很短則直接內嵌
- 貢獻者 — 感謝貢獻者（徽章或列表）
- 授權 — 授權名稱 + 連結
Go 專案常見徽章：
[](https://go.dev/) [](./LICENSE) [](https://github.com/{owner}/{repo}/actions) [](https://codecov.io/gh/{owner}/{repo}) [](https://goreportcard.com/report/github.com/{owner}/{repo}) [](https://pkg.go.dev/github.com/{owner}/{repo})
關於完整的 README 指引與應用程式專屬章節，請參閱專案文件。
步驟 5：CONTRIBUTING 與 Changelog
CONTRIBUTING.md — 協助貢獻者在 10 分鐘內上手。包含：前置需求、複製、建置、測試、PR 流程。如果設定時間超過 10 分鐘，則應改善流程：加入 Makefile、docker-compose 或 devcontainer 以簡化。請參閱專案文件。
Changelog — 使用 Keep a Changelog 格式或 GitHub Releases 追蹤變更。從 templates/CHANGELOG.md 複製模板。每個條目回答對讀者而言什麼變了——沒有使用者可見影響的內部重構屬於提交歷史。不要將修復的邊界案例誇大成廣泛的「可靠性改善」宣稱。請參閱專案文件。
步驟 6：函式庫專屬文件
對於 Go 函式庫，在基礎之上加入以下項目：
- Go Playground 示範 — 建立可執行的示範，並在 doc 註解中使用
// Play: https://go.dev/play/p/xxx連結。當可用時，使用 go-playground MCP 工具建立並分享 Playground URL。 - Example 測試函式 — 在
_test.go檔案中撰寫func ExampleXxx()。這些是可執行的文件，由go test驗證。 - 豐富的程式碼範例 — 在 doc 註解中包含多個範例，展示常見使用案例。
- godoc — 你的 doc 註解會呈現在 pkg.go.dev 上。使用
go doc在本機預覽；若要檢查已發布的套件如何呈現其文件、符號與範例，→ 請參閱samber/cc-skills-golang@golang-pkg-go-dev技能。 - 文件網站 — 對於大型函式庫，考慮使用 Docusaurus 或 MkDocs Material，包含章節：入門、教學、操作指南、參考、解釋。
- 註冊以提高可發現性 — 加入 Context7、DeepWiki、OpenDeep、zRead。即使是私有函式庫也建議這麼做。
詳情請參閱函式庫文件。
步驟 7：應用程式專屬文件
對於 Go 應用程式/CLI：
- 安裝方式 — 預先建置的二進位檔（GoReleaser）、
go install、Docker 映像、Homebrew…… - CLI 說明文字 — 讓
--help內容詳盡；這是主要文件 - 設定文件 — 記錄所有環境變數、設定檔、CLI 旗標
詳情請參閱應用程式文件。
步驟 8：API 文件
如果你的專案暴露 API：
| API 風格 | 格式 | 工具 |
|---|---|---|
| REST/HTTP | OpenAPI 3.x | swaggo/swag（從註解自動產生） |
| 事件驅動 | AsyncAPI | 手動或程式碼產生 |
| gRPC | Protobuf | buf、grpc-gateway |
盡可能偏好從程式碼註解自動產生。詳情請參閱應用程式文件。
步驟 9：AI 友善文件
讓你的專案能被 AI 代理使用：
- llms.txt — 在儲存庫根目錄加入
llms.txt檔案。從 templates/llms.txt 複製模板。此檔案為 LLM 提供專案的結構化概覽。 - 結構化格式 — 使用 OpenAPI、AsyncAPI 或 protobuf 提供機器可讀的 API 文件。
- 一致的 doc 註解 — 結構良好的 godoc 註解容易被 AI 工具解析。
- 清晰度 — 清晰、結構良好的文件有助於 AI 代理快速理解你的專案。
步驟 10：交付文件
記錄使用者如何取得你的專案：
函式庫：
go get github.com/{owner}/{repo}
應用程式：
# 預先建置的二進位檔
curl -sSL https://github.com/{owner}/{repo}/releases/latest/download/{repo}-$(uname -s)-$(uname -m) -o /usr/local/bin/{repo}
# 從原始碼
go install github.com/{owner}/{repo}@latest
# Docker
docker pull {registry}/{owner}/{repo}:latest
關於 Dockerfile 最佳實踐與 Homebrew tap 設定，請參閱專案文件。
