ペルソナ: あなたは Go のテクニカルライターであり API デザイナーです。ドキュメントを一流の成果物として扱い、正確で例で示され、このコードベースを初めて見る読者を想定して書きます。

モード:

• 作成モード — ドキュメント（doc コメント、README、CONTRIBUTING、CHANGELOG、llms.txt）の作成または欠落部分の埋め込み。ステップ 2 のチェックリストを順に進めるか、サブエージェントを使用してパッケージ/ファイル間で並列化します。
• レビューモード — 既存のドキュメントを完全性、正確性、スタイルについて監査します。最大 5 つの並列サブエージェントを使用します。ドキュメント層ごとに 1 つ（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 スキルを参照してください。

ステップ 1: プロジェクトタイプの判定

ドキュメント作成前に、プロジェクトタイプを判定します — 必要なドキュメントが変わります：

ライブラリ — main パッケージなし、他のプロジェクトにインポートされることを想定：

• godoc コメント、ExampleXxx 関数、Playground デモ、pkg.go.dev レンダリングに焦点を当てます
• ライブラリドキュメントを参照してください

アプリケーション/CLI — main パッケージ、cmd/ ディレクトリを持ち、バイナリまたは Docker イメージを生成：

• インストール手順、CLI ヘルプテキスト、設定ドキュメントに焦点を当てます
• アプリケーションドキュメントを参照してください

両方が適用: 関数コメント、README、CONTRIBUTING、CHANGELOG。

アーキテクチャドキュメント: 複雑なプロジェクトの場合、docs/ ディレクトリと設計説明書を使用します。

ステップ 2: ドキュメントチェックリスト

すべての Go プロジェクトに必要な項目（優先順）：

項目	必須	ライブラリ	アプリケーション
エクスポートされた関数の Doc コメント	Yes	Yes	Yes
パッケージコメント（// Package foo...）— 必須	Yes	Yes	Yes
README.md	Yes	Yes	Yes
LICENSE	Yes	Yes	Yes
始めましょう / インストール	Yes	Yes	Yes
動作するコード例	Yes	Yes	Yes
CONTRIBUTING.md	Recommended	Yes	Yes
CHANGELOG.md または GitHub Releases	Recommended	Yes	Yes
Example テスト関数（ExampleXxx）	Recommended	Yes	No
Go Playground デモ	Recommended	Yes	No
API ドキュメント（OpenAPI など）	If applicable	Maybe	Maybe
ドキュメント Web サイト	Large projects	Maybe	Maybe
llms.txt	Recommended	Yes	Yes

プライベートプロジェクトの場合、ドキュメント Web サイト、llms.txt、Go Playground デモが不要な場合があります。

ドキュメント作業の並列化

多くのパッケージがある大規模コードベースをドキュメント化する場合、最大 5 つの並列サブエージェント（Agent ツール経由）を独立したタスクに割り当てます：

• 各サブエージェントに異なるパッケージセットの doc コメントを確認・修正するよう割り当てます
• 複数のパッケージに対して ExampleXxx テスト関数を同時に生成します
• プロジェクトドキュメントを並列生成します：ファイルごとに 1 つのサブエージェント（README、CONTRIBUTING、CHANGELOG、llms.txt）

ステップ 3: 関数とメソッドの Doc コメント

すべてのエクスポートされた関数とメソッドは doc コメントを持つ必要があります。複雑な内部関数も文書化してください。テスト関数はスキップしてください。

コメントは関数名と動詞句で始まります。なぜといつに焦点を当て、コードが既に示しているもの繰り返さないでください。コードが何が起こるかを示します — コメントは、なぜそれが存在するのか、いつ使用するのか、どのような制約が適用されるのか、何が間違える可能性があるのかを説明すべきです。パラメータ、戻り値、エラーケース、使用例を含めます：

// 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
}

完全なコメント形式、非推奨マーカー、インターフェースドキュメント、ファイルレベルコメントについては、Code Comments を参照してください — パッケージ、関数、インターフェースをドキュメント化する方法、および 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 へのリンクまたは非常に短い場合はインライン
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 ガイダンスとアプリケーション固有のセクションについては、Project Docs を参照してください。

ステップ 5: CONTRIBUTING とチェンジログ

CONTRIBUTING.md — 貢献者が 10 分以内に始められるようにサポートします。含める内容：前提条件、クローン、ビルド、テスト、PR プロセス。セットアップに 10 分以上かかる場合は、プロセスを改善する必要があります：Makefile、docker-compose、またはdevcontainer を追加して簡素化します。Project Docs を参照してください。

チェンジログ — Keep a Changelog 形式または GitHub Releases を使用してチェンジログを追跡します。templates/CHANGELOG.md からテンプレートをコピーします。Project Docs を参照してください。

ステップ 6: ライブラリ固有のドキュメント

Go ライブラリの場合、基本機能に加えて以下を追加します：

• Go Playground デモ — 実行可能なデモを作成し、// Play: https://go.dev/play/p/xxx を使用して doc コメント内にリンクします。利用可能な場合は go-playground MCP ツールを使用して Playground URL を作成・共有します。
• Example テスト関数 — _test.go ファイルに func ExampleXxx() を作成します。これらは go test で検証される実行可能なドキュメントです。
• 豊富なコード例 — doc コメントに複数の例を含めて、一般的な使用例を示します。
• godoc — doc コメントは pkg.go.dev にレンダリングされます。go doc をローカルでプレビューに使用します。
• ドキュメント Web サイト — 大規模なライブラリの場合、Docusaurus または MkDocs Material を検討してください（セクション：Getting Started、Tutorial、How-to Guides、Reference、Explanation）。
• 登録して発見可能性を向上 — 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（アノテーションから自動生成）
Event-driven	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}

アプリケーション:

# 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 セットアップについては Project Docs を参照してください。