albertsko/go-skill

1. スコープ

これらのプラクティスは、Go 1.27 の言語セマンティクス、ランタイムのデフォルト、およびデフォルトの実験構成を前提としています。

2. コンセプトファイルへのルート

スコープ内のコードとタスクに基づいてルートし、変更や差分については変更されたコードに焦点を当てます。インデックスはトピックと参考となるコードパターンを組み合わせています。X、T、x、v は任意の名前を表します。以下に示す追加のルートを含め、該当するすべての参照を開いてください。

見出しの ID プレフィックスでプラクティスを見つけ、その完全な ID を引用してください。プラクティスに従い、例をイディオムとして使用し、理由、例外、トレードオフでメカニズム、適用可能性、コストを確認してください。シグナルは、不足している可能性のあるプラクティスを特定します。

また、不足しているセーフガードや症状については、以下の参照も開いてください。

• モジュールまたはファイルの言語バージョンの不一致、ビルド制約、ランタイム動作のオーバーライド：MOD。
• error をチェックまたは破棄するコード：ERH。
• ゴルーチンまたはチャネル：CTX、GOR、SHR。
• ブロッキング I/O（ネットワーク、データベース、HTTP、ファイル）または HTTP ハンドラ：CTX。
• 並行コードのテスト：TBA と TST。
• メモリまたはゴルーチン数の増加：PRO と MRT。
• GC CPU の高使用率、またはコンテナ内のプログラム：BRT、PRO、TRC。
• ホットパス、またはコードを高速化するリクエスト：PRO、ALO、BEN。

2.1 言語

• CST code-structure.md: シャドーイング、パッケージ/組み込み名 (url、len、new、max)、早期リターン (return 後の else)、func init()。
• STD struct-design.md: ゲッター/セッター (GetX/SetX)、埋め込み (sync.Mutex)、昇格フィールドリテラル、関数型オプション (NewXWithY、Config 引数)、new(expr) とポインタヘルパー (ptr[T]、intPtr)。
• INT interfaces.md: インターフェースの作成/所有権、単一実装インターフェース、具象型 vs インターフェース結果、any/interface{}、型付き nil インターフェース/エラー。
• GEN generics.md: 型パラメータ ([T any])、制約 (comparable、~int、~string、cmp.Ordered、golang.org/x/exp/constraints)、推論、ジェネリックメソッド、自己参照制約。
• FNM functions-and-methods.md: 値/ポインタまたは混合レシーバ、ミューテックスを保持する値レシーバ、名前付き結果 (n int, err error)、裸のリターン。
• LOP loops.md: 範囲コピー (v.field =)、式の評価、イテレーションごとの変数 (v := v、&v、ゴルーチンクロージャ)、range n、for i := 0; i <、slices.Backward、ラベル付き break、switch/select 内の break。
• ITR iterators.md: イテレータの消費/作成、iter.Seq/iter.Seq2（パラメータを含む）、yield、iter.Pull、Next()/Value()、すべての要素をスライスとして返すメソッド、slices.Collect。
• DEF defer-and-cleanup.md: ループ内の defer、遅延引数/レシーバの評価、io.Closer のクリーンアップ (defer f.Close()、resp.Body、rows.Close())、Close/Sync エラー、os.Create。

2.2 データ

• NUM numbers.md: 8 進数 (0644)、整数オーバーフロー (int32(、math.MaxInt)、float ==、NaN/Inf、math.FMA。
• SLC slices.md: 長さ/容量、append エイリアシング、事前割り当て (make([])、nil/空 ([]T{}、s == nil)、len チェック、copy/slices.Clone、[low:high:max]、スライスから配列への変換。
• COL collection-helpers.md: min/max、slices 挿入/削除/ソート/検索、maps、cmp、clear。古い形式：sort.Slice、math.Min/math.Max、append(s[:i], s[i+1:]...)、マップクリア delete ループ。
• MAP maps.md: マップサイズ設定 (make(map、map[K]V{})、ソート済みキー (maps.Keys、sort.Strings)、マップイテレーション中の書き込み。
• MRT memory-retention.md: キャッシュ/長期生存マップ (ミューテックスと併用、削除、ピーク後のサイズ)、保持された部分文字列/部分スライス、ドロップされたポインタのゼロ化、strings.Clone/bytes.Clone、runtime.AddCleanup/runtime.SetFinalizer、unique.*、weak.*。
• CMP comparison.md: 比較可能な型 (インターフェース/構造体の ==、[T comparable])、slices.Equal/maps.Equal、reflect.DeepEqual、関数値 (runtime.FuncForPC)。
• STX strings-text.md: バイト/ルーン (len(s) を文字数として使用、[]rune)、UTF-8 検証 (utf8)、string(int)、文字列 range、unicode テーブル。
• SPR strings-processing.md: Trim*/Cut*、SplitSeq/FieldsSeq/Lines、strings.Split/strings.Index、strings.Builder、文字列 += ループ、bytes/bytes.Buffer、fmt.Append*/strconv.Append*、[]byte(fmt.Sprintf(。

2.3 エラー

• PAN panics.md: panic vs error、recover、Must、panic(nil)/panicnil、debug.SetCrashOutput。
• ERC errors-creating.md: ラップ (%w/%v、fmt.Errorf、コンテキストなし return err/return nil, err)、errors.New、センチネル (var Err) vs エラー型 (Error() string)、errors.Join、ErrUnsupported。
• ERH errors-handling.md: errors.Is/errors.AsType、err ==、err.(type)、errors.As、メッセージ比較、タイムアウト/キャンセルセンチネル (net.Error、os.ErrDeadlineExceeded、context.DeadlineExceeded)、結果の前に err をチェック、無視されたエラー (_ =、x, _ :=)。
• LOG logging.md: log/slog のセットアップとエラーログ、log.Printf/log.Println、同じエラーのログ記録と返却。

2.4 並行処理

• CND concurrency-design.md: 並行性 vs 並列性、起動しきい値 (要素ごとのゴルーチン)、ワーカープールサイズ設定、runtime.NumCPU()、GOMAXPROCS。
• SHR shared-state.md: データ競合、happens-before、競合状態、ミューテックス vs チャネル、ゴルーチン書き込み、sync.Mutex/RLock、ロック中のフォーマット (fmt.Sprintf)、共有 append/マップ。
• SYN sync-primitives.md: 型付きアトミック (sync/atomic、atomic.Pointer、atomic.AddInt64/atomic.Value、ゴルーチン n++)、sync.Map、sync.Once/sync.OnceValue、sync.Cond、コピーされた sync 値。
• GOR goroutine-lifecycle.md: ゴルーチンリーク、停止計画/所有者、早期リターン後にブロックされた送信者、バッファなし結果チャネル、go func()、sync.WaitGroup、wg.Add/wg.Go、errgroup (g.Go、SetLimit)。
• CHA channels.md: 通知チャネルとサイズ設定 (make(chan、chan bool、chan struct{})、select 優先順位、nil チャネル、close。
• CTX context.md: context.Context の受け渡し、defer cancel()/context.WithTimeout、ブロッキング操作の周りの ctx.Done()、値キー (context.WithValue、ctx.Value)、main 外での context.Background()。
• CXC context-cancellation.md: キャンセルの原因 (ctx.Err()、<-ctx.Done()、context.Canceled/context.DeadlineExceeded/context.Cause、WithCancelCause)、context.AfterFunc、バックグラウンド処理 (WithoutCancel、ゴルーチン r.Context())、signal.Notify/signal.NotifyContext。

2.5 標準ライブラリ

• TIM time.md: time.Duration 単位/ベア数値、time.Time 比較 (==)、ループ内のタイマー (time.After)、time.NewTimer、time.Tick。
• JSN json.md: encoding/json、encoding/json/v2、JSON タグ (omitzero、omitempty)、埋め込みマーシャラ、数値デコード (json.Unmarshal into map[string]any)。
• SQL database-sql.md: database/sql、sql.Open、PingContext、プールサイズ、クエリ引数/プリペアドステートメント (db.Query、.Exec、QueryRow、ExecContext、SQL via fmt.Sprintf)、sql.Null[T]、rows.Next/rows.Err。
• IOF io-and-files.md: io.Reader/io.Writer と fs.FS パラメータ、filename string、os.Open、os.ReadFile、os.DirFS、os.Root、ユーザー入力との filepath.Join。
• HCL http-client-and-net.md: クライアントのタイムアウト/共有/プール (http.Get、http.Post、http.DefaultClient、http.Client、http.Transport)、net/netip vs net.IP/net.ParseIP、net.JoinHostPort vs fmt.Sprintf("%s:%d"。
• HSV http-server.md: ハンドラ (http.ResponseWriter、*http.Request、http.Handler、r.Body/r.Method)、ServeMux パターン/HandleFunc、http.Error、サーバータイムアウト (http.ListenAndServe、http.Server)、MaxBytesHandler、ResponseController、CrossOriginProtection。
• RND randomness-and-ids.md: uuid、crypto/rand、math/rand、math/rand/v2、rand.Seed。

2.6 テスト

• TBA testing-basics.md: テストカテゴリ/ビルドタグ (func TestX、//go:build integration)、-race、t.Parallel、-shuffle、テーブル駆動テスト/t.Run、ヘルパー、外部 _test パッケージ。
• TST testing-state.md: t.Cleanup、TestMain、t.Context vs テスト context.Background()、t.Chdir/t.Setenv/t.TempDir vs os.Chdir/os.Setenv/os.MkdirTemp、testing/synctest、テスト時間/time.Sleep、cryptotest。
• TTL testing-tools.md: httptest、testing/iotest、fstest、slogtest、ファジング (func FuzzX)。
• BEN benchmarks.md: func BenchmarkX、b.Loop vs b.N/b.ResetTimer、代表的な入力/再利用、benchstat。
• COV coverage-and-test-output.md: -coverpkg、-cover、go build -cover/GOCOVERDIR、t.Output/t.Attr/t.ArtifactDir、テスト fmt.Println、go test -json。

2.7 パフォーマンス

レイアウト、割り当て、インライン化のプラクティスは、ベンチマーク、プロファイル、またはトレースで特定されたホットパスにのみ適用してください。

• PRO profiling.md: pprof (net/http/pprof、/debug/pprof、runtime/pprof、pprof.Lookup)、ヒープ差分、ゴルーチンダンプ、goroutineleak/ブロック/ミューテックスプロファイル (SetBlockProfileRate、SetMutexProfileFraction)、ラベル (pprof.Do)、ゴルーチンカウント (runtime/metrics)。
• TRC tracing.md: 実行トレース (runtime/trace、trace.Start)、フライトレコーダー (FlightRecorder)、レイテンシスパイク/まれな低速リクエスト、スケジューリング/GC ポーズ。
• MLY memory-layout.md: キャッシュ局所性/ストライド (ホット []*T ループ)、フォールスシェアリング (1 つのスライス内のゴルーチンごとのカウンタ)、命令レベル並列性、フィールドアライメント、structs.HostLayout。
• ALO allocations.md: エスケープ分析 (-gcflags、ローカルポインタの返却)、呼び出し側所有バッファ、コンパイラ除外変換 (ホット string(b))、allocs/op、sync.Pool。
• BRT build-and-runtime-tuning.md: インライン化、PGO (default.pgo)、GOGC/GOMEMLIMIT/debug.SetGCPercent、コンテナ対応 GOMAXPROCS (automaxprocs、runtime.GOMAXPROCS)。
• CGO cgo.md: cgo 呼び出しのバッチ処理 (import "C"、C.)、#cgo ディレクティブ (noescape、nocallback)。

2.8 プロジェクトとツール

• PKG packages-and-docs.md: プロジェクトレイアウト、パッケージの凝集性/名前 (util、common)、エイリアス (type X = Y、//go:fix inline)、ドキュメントコメント、エクスポートされたドキュメントコメントの欠落、Deprecated:、例 (func ExampleX)。
• TOL tooling.md: gofmt、go vet、リンター (golangci-lint)、tool ディレクティブ/tools.go、go fix モダナイザ、テスト vet チェック (-vet=)、CI スクリプト、@latest。
• MOD modules-and-builds.md: go.mod の衛生管理/replace、godebug///go:debug、ワークスペース (go.work)、ビルド制約 (//go:build、// +build)。

3. タスクへの適用

• コードを書く場合： ルーティングされたファイル内の該当するすべてのプラクティスを満たします。
• コードをレビューする場合： コマンドが利用可能な場合は、最初に go vet ./...、go test -race ./...、go fix -diff ./... を実行します。コードを変更せずに残す必要がある場合はコピーを使用します。ルーティングされたすべてのファイルのすべての シグナル 箇条書きをチェックします。例外 でカバーされているヒットは除外します。残りを ID | file:line | 何が問題か | 修正方法 として報告します。重複するプラクティスの場合は、最初に最も具体的な ID を引用し、次に他の ID を引用します。どのプラクティスでもカバーされない問題には - を使用します。影響度順に並べます：誤った結果、競合、パニック、リーク、ハング、次にリソース/パフォーマンス問題、次に古いイディオム/スタイル。
• デバッグする場合： 症状を シグナル と 理由 に一致させ、コード内のメカニズムを確認し、プラクティス を適用します。
• コードをモダナイズする場合： go fix ./... を差分が空になるまで実行してモダナイザを適用し、差分をレビューします。モダナイザは安全であると証明できないコード形状をスキップするため、ルーティングされたファイルの シグナル をチェックして、残っている古いイディオムを手動で書き換えます。ルーティングされたファイルのシグナルの箇条書きがどれも一致せず、go vet ./... とテストがパスしたら完了です。

パフォーマンスの向上を主張する前に、ベンチマークまたはプロファイルでそれを測定してください。