agent-ready-go

エージェント対応の Go

すべてのツールが機械可読な出力を生成し、エラーが構造化され、コマンドがデフォルトで非対話的に実行されるようにすることで、Go アプリケーションを AI コーディングエージェントが効果的に扱えるようにします。

ワークフロー

Go アプリをエージェント対応にするには、次の手順を実行します。

1. 監査 — エージェント対応チェックリストに照らして不足箇所を特定します
2. 構造化ログ — JSON 出力で slog、Zap、ZeroLog、または Logrus を追加・設定します
3. 機械可読な出力 — すべてのコマンドが JSON を出力できることを確認します
4. リンティング — 詳細な設定を含む .golangci.yml を追加します
5. テスト — カバレッジのしきい値を設定し、go test -race -count=1 -timeout=5m が実行できることを確認します
6. エラー処理 — 構造化エラーと適切な終了コードを設定します
7. 非対話的な設計 — --yes／-y フラグを用意し、プロンプトより環境変数を優先します
8. Makefile — build、test、lint、cover のターゲットを標準化します

新規プロジェクトでは、すべての手順を適用してください。既存のプロジェクトでは、まず監査を行い、不足している項目だけに対応してください。

Step 1: 監査

次のチェックリストをプロジェクトに適用してください。❌ の項目に対応します。

• 構造化ロガーが設定されている（slog／Zap／ZeroLog／Logrus）
• TTY ではない場合、または LOG_FORMAT=json の場合、ロガーが JSON を出力する
• CLI コマンドが --json または --output json フラグに対応している
• 詳細なリンター設定を含む .golangci.yml が存在する
• go test -race が成功する
• エクスポートされた主要な API に、godoc で動作する ExampleXxx テストがある
• 任意の行カバレッジより、コントラクト／振る舞いのテストが優先されている
• go vet ./... が問題なく成功する
• すべてのエラーがコンテキスト情報付きでラップされている（fmt.Errorf("...: %w", err)）
• 終了コードが 0 = 成功、0 以外 = 失敗となっている（CLI エントリーポイントで panic を発生させない）
• すべての I/O を伴う関数に context.Context が渡されている
• 対話型プロンプトに --yes／-y のバイパスフラグがある
• build、test、lint、cover、ci のターゲットを含む Makefile がある
• HTTP サービスが SIGTERM／SIGINT を受けた際にグレースフルシャットダウンする
• HTTP サービスにヘルスチェックのエンドポイント（/healthz、/readyz）がある
• govulncheck ./... が問題なく成功する
• NO_COLOR が尊重され、TTY 以外への出力に ANSI コードが含まれない
• 設定が環境変数から読み込まれ、起動時に検証される

Step 2: 構造化ログ

slog、Zap、ZeroLog、Logrus の設定パターンについては、references/logging.md を参照してください。

主な要件：

• !isatty(os.Stdout.Fd()) の場合、または LOG_FORMAT=json の場合は JSON 形式を使用します
• level、ts、msg に加えて、コンテキストフィールドを含めます
• 運用ログの出力に fmt.Println を使用しないでください
• stderr にログを出力し、機械可読なデータ用に stdout を空けておきます

Step 3: 機械可読な出力

エージェントは結果を検証するために stdout を解析します。重要なコマンドはすべて JSON 出力に対応する必要があります。

var outputJSON bool
cmd.Flags().BoolVar(&outputJSON, "json", false, "output results as JSON")

if outputJSON {
    enc := json.NewEncoder(os.Stdout)
    enc.SetIndent("", "  ")
    _ = enc.Encode(result)
} else {
    fmt.Printf("Created: %s\n", result.Name)
}

原則：構造化データは stdout に、進捗や人間向けのメッセージは stderr に出力します。

fmt.Fprintln(os.Stderr, "Processing...")  // progress to stderr
json.NewEncoder(os.Stdout).Encode(result) // data to stdout

Step 4: リンティング

assets/.golangci.yml をプロジェクトのルートにコピーし、次を実行します。

golangci-lint run ./...

golangci-lint v1.59 以降（v1.x 系列）が必要です。

リンターの説明と調整方法については、references/testing.md を参照してください。

Step 5: テスト

テストのセットアップ全般については、references/testing.md を参照してください。

go test -race -count=1 -timeout=5m -coverprofile=coverage.out ./...
go tool cover -func=coverage.out | tail -1

CI で任意の行カバレッジ率（たとえば 80%）を強制しないでください。エージェントにも人間にも、水増しされた単体テストより、シグナルの高いコントラクトテストのほうが役立ちます。

その代わり、エクスポートされた主要な API すべてに、動作する ExampleXxx テストがあることを必須にします。

1. サンプルは、コンパイルによって正しさが保証されるドキュメントとして機能します。
2. 説明どおりに API コントラクトが動作することを証明します。
3. エージェントが誤った使用パターンを幻覚するのを防ぎます。

Step 6: エラー処理

構造化エラーのパターンと終了コードの規約については、references/error-handling.md を参照してください。

簡単なルール：

• 必ずラップします：fmt.Errorf("loading config: %w", err)
• CLI の main() がすべてのエラーを捕捉し、適切なコードで終了します
• ビジネスロジックの深い箇所で os.Exit を呼び出さないでください。エラーを上位に返します
• init()／パッケージレベルのセットアップ以外で panic を使用しないでください

ステップ 7：非対話型設計

パターンについては、references/non-interactive.mdを参照してください。

エージェントの実行を妨げるプロンプトには、--yes／-yによる回避手段を用意する必要があります。

if !yes {
    confirmed, _ := promptConfirm("Delete all records?")
    if !confirmed {
        return nil
    }
}
// proceed

ステップ 8：Makefile

assets/Makefileをプロジェクトのルートにコピーします。 プロジェクトに合わせてBINARY_NAMEとMAIN_PKGを調整してください。

標準ターゲット：make build、make test、make lint、make cover、 make ci（パイプライン全体を実行）。

リソース

ファイル	内容
references/logging.md	slog、Zap、ZeroLog、LogrusのJSON設定
references/testing.md	レース検出器、カバレッジ、golangci-lintの調整
references/error-handling.md	構造化エラー、終了コード、コンテキスト
references/non-interactive.md	--yesフラグ、環境変数、標準入力の検出
references/services.md	HTTPのグレースフルシャットダウン、ヘルスチェック、OTel、リクエストID
references/config.md	設定管理、環境変数の解析、検証
assets/.golangci.yml	本番環境向けリンター設定
assets/Makefile	標準的なビルド／テスト／lint／カバレッジのターゲット