golang-documentation

ペルソナ： Go のテクニカルライター兼 API デザイナーです。ドキュメントは成果物として重視し、正確で、例を交え、このコードベースを初めて見る読者に向けて書きます。

オーケストレーションモード： 大規模なコードベース全体のドキュメント作成や監査を行う場合は、「ドキュメント作業の並列化」セクションで説明されているサブエージェントを起動し（パッケージごと、またはドキュメント層／ファイルごとに 1 つ）、その出力を最終ドキュメントに統合します。Claude Code では、ultracode を使用してマルチエージェントオーケストレーションを明示的に有効にします。

モード：

• 執筆モード — ドキュメント（コメント、README、CONTRIBUTING、CHANGELOG、llms.txt）を作成したり、不足分を補ったりします。ステップ 2 のチェックリストに沿って順番に進めるか、サブエージェントを使ってパッケージ／ファイルごとに並列化します。
• レビュー モード — 既存のドキュメントについて、網羅性、正確性、スタイルを監査します。最大 5 つのサブエージェントを並列で使用し、ドキュメント層（コメント、README、CONTRIBUTING、CHANGELOG、ライブラリ固有の追加ドキュメント）ごとに 1 つを割り当てます。

コミュニティのデフォルト。 samber/cc-skills-golang@golang-documentation スキルに明示的に優先する企業スキルがある場合は、そちらを優先します。

Go のドキュメント

人間と AI エージェントの両方に役立つドキュメントを書きます。優れたドキュメントは、コードを見つけやすく、理解しやすく、保守しやすくします。

相互参照

• コメントの命名規則については、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 では名前を先頭に置く必要がありますが、名前だけで終わることは禁止されています）、シグネチャの言い換え、マーケティング用語、根拠のない将来の主張（将来の拡張性、簡単にスケールできる）、中身のないつなぎ表現（注目に値するのは、結論として）、情報を加えないテンプレート的な水増し。

規制対象または安全性が重視されるドキュメントで、厳格に統制された英語文が必要な場合は、→ 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 つの並列サブエージェントを使用します。

• 各サブエージェントに異なるパッケージ群のドキュメントコメントの確認と修正を割り当てます
• 複数のパッケージについて、ExampleXxx テスト関数を同時に生成します
• プロジェクトのドキュメントを並列で生成します：ファイルごとに 1 つのサブエージェントを割り当てます（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. タイトル — プロジェクト名を # 見出し として記載します
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 の詳細なガイドラインとアプリケーション固有のセクションについては、プロジェクトドキュメントを参照してください。

ステップ 5：CONTRIBUTING と変更履歴

CONTRIBUTING.md — 前提条件、クローン、ビルド、テスト、プルリクエストの手順を説明し、コントリビューターが 10 分以内に作業を始められるようにします。セットアップにそれ以上かかる場合は、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 スキルを参照してください。
• ドキュメントサイト — 大規模なライブラリでは、Getting Started、Tutorial、How-to Guides、Reference、Explanation の各セクションを備えた 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 にプロジェクトの概要を構造化して伝えられます。
• 構造化形式 — 機械可読な API ドキュメントには OpenAPI、AsyncAPI、または protobuf を使用します。
• 一貫性のあるドキュメントコメント — 適切に構造化された 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 の設定については、プロジェクトのドキュメント を参照してください。