全面的 Golang 项目文档指南，涵盖 godoc 注释、README、CONTRIBUTING、CHANGELOG、Go Playground、示例测试、API 文档和 llms.txt。在编写或审查文档注释、文档、添加代码示例、搭建文档站点或讨论文档最佳实践时使用。适用于库和应用程序/CLI。
角色： 你是一名 Go 技术写作者和 API 设计师。你将文档视为一等交付物——准确、以示例驱动，并且为从未见过此代码库的读者编写。
模式：
- 写入模式 — 生成或补充缺失的文档（文档注释、README、CONTRIBUTING、CHANGELOG、llms.txt）。按步骤 2 中的清单顺序工作，或使用子代理跨包/文件并行处理。
- 审查模式 — 审计现有文档的完整性、准确性和风格。最多使用 5 个并行子代理：每个文档层一个（文档注释、README、CONTRIBUTING、CHANGELOG、库特定附加内容）。
社区默认。 明确覆盖
samber/cc-skills-golang@golang-documentation技能的公司技能优先。
Go 文档
编写既服务于人类又服务于 AI 代理的文档。好的文档使代码可发现、可理解且可维护。
交叉引用
参见 samber/cc-skills-golang@golang-naming 技能了解文档注释中的命名约定。参见 samber/cc-skills-golang@golang-testing 技能了解示例测试函数。参见 samber/cc-skills-golang@golang-project-layout 技能了解文档文件应放置的位置。
写作原则
适用于你编写或审查的每一份文档：
简洁 — 编写传达思想的最短版本。去除修饰和空洞的过渡。绝不遗漏事实、警告或用户要求的深度。
意图而非复述 — 代码展示什么发生了；文档解释为什么存在、何时使用、什么约束适用。仅重述签名的注释浪费读者时间。
不编造上下文 — 省略无依据的理由、营销声明（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 项目都需要这些（按优先级排序）：
| 项目 | 必需 | 库 | 应用程序 |
|---|---|---|---|
| 导出函数上的文档注释 | 是 | 是 | 是 |
包注释（// Package foo...）— 必须存在 |
是 | 是 | 是 |
| README.md | 是 | 是 | 是 |
| LICENSE | 是 | 是 | 是 |
| 入门/安装 | 是 | 是 | 是 |
| 可工作的代码示例 | 是 | 是 | 是 |
| CONTRIBUTING.md | 推荐 | 是 | 是 |
| CHANGELOG.md 或 GitHub Releases | 推荐 | 是 | 是 |
示例测试函数（ExampleXxx） |
推荐 | 是 | 否 |
| Go Playground 演示 | 推荐 | 是 | 否 |
| API 文档（例如 OpenAPI） | 如适用 | 可能 | 可能 |
| 文档网站 | 大型项目 | 可能 | 可能 |
| llms.txt | 推荐 | 是 | 是 |
私有项目可能不需要文档网站、llms.txt、Go Playground 演示……
并行化文档工作
在记录具有许多包的大型代码库时，最多使用 5 个并行子代理（通过 Agent 工具）处理独立任务：
- 分配每个子代理验证并修复不同包集中的文档注释
- 同时为多个包生成
ExampleXxx测试函数 - 并行生成项目文档：每个文件一个子代理（README、CONTRIBUTING、CHANGELOG、llms.txt）
步骤 3：函数和方法文档注释
每个导出的函数和方法都必须有文档注释。也记录复杂的内部函数。跳过测试函数。
注释以函数名称和动词短语开头。专注于为什么和何时，而不是重述代码已显示的内容。代码告诉你什么发生了——注释应解释为什么存在、何时使用、什么约束适用以及可能出什么问题。包括参数、返回值、错误情况和用法示例：
// CalculateDiscount computes the final price after applying tiered discounts.
// Discounts are applied progressively based on order quantity: each tier unlocks
// additional percentage reduction. Returns an error if the quantity is invalid or
// if the base price would result in a negative value after discount application.
//
// Parameters:
// - basePrice: The original price before any discounts (must be non-negative)
// - quantity: The number of units ordered (must be positive)
// - tiers: A slice of discount tiers sorted by minimum quantity threshold
//
// Returns the final discounted price rounded to 2 decimal places.
// Returns ErrInvalidPrice if basePrice is negative.
// Returns ErrInvalidQuantity if quantity is zero or negative.
//
// Play: https://go.dev/play/p/abc123XYZ
//
// Example:
//
// 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("Discount calculation failed: %v", err)
// }
// log.Printf("Ordered 75 units at $100 each: final price = $%.2f", finalPrice)
func CalculateDiscount(basePrice float64, quantity int, tiers []DiscountTier) (float64, error) {
// implementation
}
关于完整的注释格式、弃用标记、接口文档和文件级注释，请参见 代码注释 — 如何记录包、函数、接口，以及何时使用 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 演示 — 创建可运行的演示，并在文档注释中使用
// Play: https://go.dev/play/p/xxx链接。可用时使用 go-playground MCP 工具创建和共享 Playground URL。 - 示例测试函数 — 在
_test.go文件中编写func ExampleXxx()。这些是由go test验证的可执行文档。 - 丰富的代码示例 — 在文档注释中包含多个示例，展示常见用例。
- godoc — 你的文档注释在 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 文档。
- 一致的文档注释 — 结构良好的 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 设置。
