为 Go 项目编写面向人类与 AI 的完整文档（godoc…

当你需要为 Go 库或应用/CLI 编写、审查或补全文档（代码注释、README、贡献指南、变更日志、API 文档、AI 可读文档）时使用。

适用场景

解决思路

1. 先判定项目类型：无 main 包、供他人导入的是库，重点写 godoc 注释、ExampleXxx 函数、Playground 演示与 pkg.go.dev 渲染；含 main 包或 cmd/ 目录、产出二进制或 Docker 镜像的是应用/CLI，重点写安装说明、CLI 帮助文本与配置文档；函数注释、README、CONTRIBUTING、CHANGELOG 两者都要写；复杂项目另用 docs/ 目录写架构与设计文档。
2. 按优先级补齐文档清单：导出函数的 doc comment、包注释（// Package foo...，必须存在）、README.md、LICENSE、快速上手/安装、可运行代码示例为必需；CONTRIBUTING.md、CHANGELOG.md 或 GitHub Releases、ExampleXxx 示例测试（仅库）、Go Playground 演示（仅库）、llms.txt 为推荐；API 文档（如 OpenAPI）、文档网站视情况而定。
3. 大型代码库用最多 5 个并行子代理拆分独立任务：每个子代理负责不同包集合的注释校验与修复、并行生成多个包的 ExampleXxx、或每个子代理负责一个文档文件（README、CONTRIBUTING、CHANGELOG、llms.txt），最后合并输出。
4. 为每个导出函数和方法写 doc comment（复杂内部函数也要写，测试函数跳过）：以函数名加动词短语开头，重点解释为什么存在、何时使用、有何约束、可能出什么错，并写明参数、返回值、错误情况与用法示例。
5. 写文档时遵循原则：用最短篇幅表达完整意思，删掉修饰与空洞过渡；讲意图而非复述代码；不编造理由、营销词（seamlessly、robust、enterprise-grade）或未来承诺；编辑时保留 must/should/may 等情态与条件、警告、必需操作；见到纯复述签名、营销词汇、无根据的未来声明、空洞过渡、模板填充等反模式立即删除。
6. README 按固定顺序组织：标题、徽章（Go 版本、许可证、CI、覆盖率、Go Report Card）、1-2 句摘要、演示（代码片段/GIF/截图/视频）、快速上手（安装+最小可运行示例）、功能/规格说明、贡献（链接 CONTRIBUTING.md）、贡献者致谢、许可证；徽章使用 shields.io 模板。
7. 写 CONTRIBUTING.md 让贡献者 10 分钟内上手，覆盖前置条件、克隆、构建、测试与 PR 流程；若搭建耗时过长，用 Makefile、docker-compose 或 devcontainer 改进流程。
8. 用 Keep a Changelog 格式或 GitHub Releases 维护变更日志，每条写清对读者而言发生了什么变化；无用户可见影响的内部重构只留在提交历史，修复边缘情况不要夸大为“可靠性提升”。
9. 库项目额外补充：用 // Play: https://go.dev/play/p/xxx 在注释中链接可运行的 Go Playground 演示；在 _test.go 中写 func ExampleXxx() 作为被 go test 验证的可执行文档；注释中提供多个常见用例示例；用 go doc 本地预览 pkg.go.dev 渲染效果；大型库可考虑 Docusaurus 或 MkDocs Material 建站（Getting Started、Tutorial、How-to、Reference、Explanation）；到 Context7、DeepWiki、OpenDeep、zRead 注册以提升可发现性。
10. 应用/CLI 项目额外补充：说明预编译二进制（GoReleaser）、go install、Docker 镜像、Homebrew 等安装方式；把 --help 文本写全面，它是主要文档；记录所有环境变量、配置文件与 CLI 标志。
11. 若项目暴露 API，按风格选格式与工具：REST/HTTP 用 OpenAPI 3.x 配合 swaggo/swag 从注解自动生成；事件驱动用 AsyncAPI（手写或代码生成）；gRPC 用 Protobuf 配合 buf、grpc-gateway；尽量从代码注解自动生成。
12. 为 AI 消费优化文档：在仓库根目录添加 llms.txt 提供结构化项目概览；API 文档用 OpenAPI、AsyncAPI 或 protobuf 等机器可读格式；保持 godoc 注释结构一致便于解析；整体保持清晰结构。
13. 写交付文档：库用 go get github.com/{owner}/{repo}；应用给出预编译二进制 curl 下载、go install github.com/{owner}/{repo}@latest、docker pull {registry}/{owner}/{repo}:latest 等命令，并参考 Dockerfile 最佳实践与 Homebrew tap 配置。

适用边界 · 注意事项

• 私有项目可能不需要文档网站、llms.txt、Go Playground 演示等重型文档设施。
• 若公司内部技能明确取代 samber/cc-skills-golang@golang-documentation，则以公司技能为准。
• 需要严格受控英语（ASD-STE100）的受监管或安全关键文档，应改用 humanizer-en-asd-ste100 技能。