golang-documentation

**角色：**你是一名 Go 技术文档撰写者和 API 设计师。你将文档视为一项重要交付成果——内容准确、示例丰富，并面向从未接触过此代码库的读者。

**编排模式：**为大型代码库编写或审查文档时，按“并行化文档工作”一节所述启动多个子 Agent（每个包一个，或每个文档层级／文件一个），并将其输出合并到最终文档中。在 Claude Code 中，使用 ultracode 明确启用多 Agent 编排。

模式：

• 编写模式——生成或补全缺失的文档（文档注释、README、CONTRIBUTING、CHANGELOG、llms.txt）。按顺序完成步骤 2 中的检查清单，或使用子 Agent 并行处理多个包／文件。
• 审查模式——审查现有文档的完整性、准确性和风格。最多使用 5 个并行子 Agent，每个负责一个文档层级（文档注释、README、CONTRIBUTING、CHANGELOG、库特定的补充文档）。

社区默认规则。 若某项公司技能明确取代了 samber/cc-skills-golang@golang-documentation 技能，则以该公司技能为准。

Go 文档

编写服务于人类和 AI Agent 的文档。优质文档能让代码更容易被发现、理解和维护。

交叉引用

• 关于文档注释的命名约定，请参阅 samber/cc-skills-golang@golang-naming 技能。
• 关于 Example 测试函数，请参阅 samber/cc-skills-golang@golang-testing 技能。
• 关于文档文件的存放位置，请参阅 samber/cc-skills-golang@golang-project-layout 技能。
• 当文档要求极致清晰、毫无歧义时，关于严格受控的英文表达（ASD-STE100），请参阅 samber/cc-skills@humanizer-en-asd-ste100 技能。

写作原则

对你编写或审查的每一份文档都应用以下原则：

简洁——用最短的篇幅传达核心意思。删去修饰语和空洞的过渡语。切勿遗漏事实、警告或用户要求的细节。

说明意图，而非改述代码——代码展示了_做什么_；文档应解释其_存在原因_、适用场景_和_约束条件。只复述函数签名的注释是在浪费读者的时间。

不虚构背景——省略缺乏依据的理由、营销说辞（seamlessly、robust、enterprise-grade）或对未来的承诺。让信息缺失之处保持显眼，不要用猜测填补。

编辑时保留原意——保留情态强度（must／should／may代表不同的义务）。保留条件、警告和必需的操作。改变义务要求的句子即使更流畅，也是不正确的。

**一经发现即删除的反模式：**纯粹改述且开头只有名称、没有补充任何信息的注释（godoc 要求以名称作为前缀；禁止的是仅停留于此）；复述函数签名；营销用语；毫无根据的未来承诺（future extensibility、easy to scale）；空洞的过渡语（it's worth noting that、in conclusion）；没有提供任何信息的模板填充内容。

对于要求使用严格受控英语表达的法规类或安全关键型文档，→ 请参阅 samber/cc-skills@humanizer-en-asd-ste100 技能。

步骤 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 处理彼此独立的任务：

• 分配每个子 Agent 检查并修复不同一组包的文档注释
• 同时为多个包生成 ExampleXxx 测试函数
• 并行生成项目文档：每个子 Agent 负责一个文件（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 中的模板：

1. 标题——项目名称，使用 # heading 格式
2. 徽章——shields.io 图标（Go 版本、许可证、CI、覆盖率、Go Report Card……）
3. 摘要——用 1-2 句话说明项目的作用
4. 演示——代码片段、GIF、截图或视频，展示项目的实际运行效果
5. 快速入门——安装说明 + 最精简的可运行示例
6. 功能 / 规范——详细的功能列表或规范（篇幅较长的章节）
7. 贡献——链接到 CONTRIBUTING.md，或在内容很短时直接写在 README 中
8. 贡献者——感谢贡献者（徽章或名单）
9. 许可证——许可证名称 + 链接

Go 项目的常见徽章：

[![Go Version](https://img.shields.io/github/go-mod/go-version/{owner}/{repo})](https://go.dev/) [![License](https://img.shields.io/github/license/{owner}/{repo})](./LICENSE) [![Build Status](https://img.shields.io/github/actions/workflow/status/{owner}/{repo}/test.yml?branch=main)](https://github.com/{owner}/{repo}/actions) [![Coverage](https://img.shields.io/codecov/c/github/{owner}/{repo})](https://codecov.io/gh/{owner}/{repo}) [![Go Report Card](https://goreportcard.com/badge/github.com/{owner}/{repo})](https://goreportcard.com/report/github.com/{owner}/{repo}) [![Go Reference](https://pkg.go.dev/badge/github.com/{owner}/{repo}.svg)](https://pkg.go.dev/github.com/{owner}/{repo})

如需了解完整的 README 编写指南和针对应用程序的专属章节，请参阅项目文档。

步骤 5：CONTRIBUTING 和变更日志

CONTRIBUTING.md——帮助贡献者在 10 分钟内开始参与，涵盖前置条件、克隆、构建、测试和 PR 流程。如果配置过程耗时更久，请使用 Makefile、docker-compose 或 devcontainer 来改进流程。请参阅项目文档。

变更日志——使用 Keep a Changelog 格式或 GitHub Releases 追踪变更，并复制 templates/CHANGELOG.md 中的模板。每条记录都应说明_读者能从中了解哪些变化_——对用户不可见的内部重构应记录在提交历史中；修复一个边缘情况，绝不能夸大为笼统的“可靠性提升”。请参阅项目文档。

第 6 步：特定于库的文档

对于 Go 库，除了基础文档之外，还要添加以下内容：

• Go Playground 演示 — 创建可运行的演示，并在文档注释中用 // Play: https://go.dev/play/p/xxx 添加链接。如果有 Go Playground 集成，请使用它来创建和分享 Playground URL。
• 示例测试函数 — 在 _test.go 文件中编写 func ExampleXxx()。这些可执行文档会通过 go test 验证。
• 丰富的代码示例 — 在文档注释中加入多个示例，展示常见用例。
• godoc — 文档注释会显示在 pkg.go.dev 上。使用本地 go doc 预览；若要查看已发布的软件包如何呈现其文档、符号和示例，→ 请参阅 samber/cc-skills-golang@golang-pkg-go-dev skill。
• 文档网站 — 对于大型库，可考虑使用 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 Agent 能够使用你的项目：

• llms.txt — 在仓库根目录添加 llms.txt 文件。从 templates/llms.txt 复制模板。此文件为大模型提供项目的结构化概览。
• 结构化格式 — 使用 OpenAPI、AsyncAPI 或 protobuf 编写机器可读的 API 文档。
• 一致的文档注释 — 结构良好的 godoc 注释便于 AI 工具解析。
• 清晰明了 — 清晰且结构良好的文档有助于 AI Agent 快速理解你的项目。

第 10 步：交付文档

记录用户如何获取你的项目：

库：

go get github.com/{owner}/{repo}

应用：

# Pre-built binary
curl -sSL https://github.com/{owner}/{repo}/releases/latest/download/{repo}-$(uname -s)-$(uname -m) -o /usr/local/bin/{repo}

# From source
go install github.com/{owner}/{repo}@latest

# Docker
docker pull {registry}/{owner}/{repo}:latest

Dockerfile 最佳实践和 Homebrew tap 设置详情，请参阅 项目文档。