Communityコーディング&開発github.com

sk-go-service

Goバックエンドサービスのハンドラ、サービス、リポジトリの実装、拡張、デバッグを支援します。コンテキスト伝播、エラーラッピング、トランザクション境界、テナントスコープ、テーブル駆動テストをカバーします。Goサーバーコードの作成・変更、エンドポイントやgRPCメソッドの追加、リポジトリクエリの修正、パニック・リーク・flakyテストの診断時に使用します。

sk-go-service とは?

このスキルは、Goで書かれたバックエンドサービスの開発を効率的かつ堅牢にするためのベストプラクティスを提供します。主に、コンテキスト伝播、エラーラッピング、トランザクション管理、マルチテナンシー、ゴルーチンの安全な取り扱い、テーブル駆動テストの実装に焦点を当てています。Claude Code、Cursor、CodexといったAIエージェント上で動作し、開発者がGoサービスを拡張・修正する際に、共通のパターンに従ってコードの正確性と保守性を高めます。具体的には、`context.Context`の正しい使い方、`errors.Is`/`As`を用いたエラー比較、トランザクションのサービス層での開始、テナントIDのコードレベルでの強制、ゴルーチンのライフサイクル管理、そしてテストのタイムアウトやレース検出の重要性を説いています。このスキルを使うことで、変更によるバグの混入を防ぎ、プロジェクト全体で一貫した設計を維持しながら開発速度を向上させることができます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-go-service

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Goサービス作業の進め方

同時実行性とマルチテナンシーが存在する環境でも、レイヤー化されたGoサービスを正しく保つための規約です。まず周辺のパッケージを読んでください。ここに書かれていることよりも、そのコードベースで一貫して適用されているローカルパターンが優先されます。

コードを書く前に

ツールチェーンを確認してください。go.modが使用可能な標準ライブラリと言語機能を決定し、同じワークスペース内のサービスでも異なるバージョンを使用していることがよくあります。ループ変数のキャプチャはGo 1.22未満では実際のバグですが、それ以降では問題になりません。errors.Join、slices、mapsはGo 1.21以降が必要です。最新バージョンを想定するのではなく、バージョンを確認してください。

次に、変更しようとしている判断を所有するレイヤーを見つけてください。ハンドラはトランスポートをドメインに変換するだけであり、それ以外は何もしません。サービスが判断を保持します。リポジトリがクエリを保持します。ハンドラに追加されたバリデーションは、サービスの他の呼び出し元からは見えません。

コンテキスト

コンテキストはリクエストに属し、リクエストとともに終了します。

  • 最初のパラメータとして ctx を渡し、データベース呼び出しまでずっと渡し続けてください。コンテキストを受け取らない関数はキャンセルできず、デッドラインを保持できません。
  • context.Context を構造体のフィールドに決して保存しないでください。
  • リクエストコンテキストを、ハンドラよりも長く生存するゴルーチンに渡さないでください。切り離されたバックグラウンド作業には、独自のタイムアウトを持つ独自のコンテキストが必要であり、必要な値はハンドラが返る前に明示的にコピーしてください。
  • 同じことは、リクエストから派生したハンドル(トランザクション、コネクション、リクエストスコープのデータベースアクセッサなど)にも当てはまります。ハンドラが返った後にこれらを使用することは、より親切なエラーメッセージ付きのuse-after-freeです。

エラー

  • %w でラップし、呼び出し元がまだ知らない情報(識別子、操作など)を追加してください。fmt.Errorf("load order %d: %w", id, err)。関数名を前置しないでください。それらが積み重なるとノイズになります。
  • errors.Is と errors.As で比較してください。誰かがラップすると、直接の == 比較は機能しなくなります。
  • トランスポートステータスへの変換は、ハンドラ境界のちょうど一箇所で行ってください。HTTPコードを返すリポジトリは、2つのレイヤーを漏洩しています。
  • sql.ErrNoRows はドメインの結果であり、失敗ではありません。リポジトリの境界でドメインの「見つからない」にマップすることで、サービスが database/sql をインポートしないようにしてください。
  • コンパイラを満足させるためにエラーを決して破棄しないでください。本当に無視できるエラーであれば、コメント付きで _ に代入してください。

トランザクション

トランザクションは、不変条件を所有するレイヤー(通常はサービス、決してリポジトリではない)で開いてください。なぜなら、自分でトランザクションを開くリポジトリは、より大きなトランザクションに合成できないからです。トランザクションハンドルを下位に渡してください。

コミットとロールバックは、パニックを含むすべてのパスで行ってください。成功したコミット後のロールバックは無害である必要があります。これが、defer tx.Rollback() を安全にする理由です。

トランザクション内で、そのトランザクションとアトミックである必要のないI/Oを行わないでください。開いているトランザクション内で支払いプロバイダにHTTP呼び出しを行うと、他の誰かの障害の期間中、データベースロックを保持することになります。

テナンシー

サービスがマルチテナントの場合、テナント識別子はデータベースではなくコードで強制されます。すべてのリポジトリクエリ(読み取りと書き込みの両方)は、テナント述語を保持します。主キーだけでフィルタリングするクエリは、別のテナントの行を平気で返します。コードベースが既に使用しているリクエストコンテキストアクセッサから識別子を派生させ、どのアクセッサが正しいかを確認してください。サブテナントに代わって動作するサービスには通常2つのアクセッサがあり、明白な方がしばしば間違っているものです。

ゴルーチン

すべてのゴルーチンには、既知のライフタイムと既知の所有者が必要です。go と書く前に、誰がそれを待つのか、どのように停止するのか、そのエラーはどこに行くのかに答えてください。エラーがドロップされるゴルーチンは、サイレント障害です。

呼び出し元が待つ場合は errgroup を使用してください。適切でない場合は、明示的な sync.WaitGroup と収集されたエラーチャネルを使用してください。リクエスト処理内の裸の go f() は、ほとんどの場合、欠陥です。

テスト

テーブル駆動で、ケースごとに1つの t.Run を使用し、入力ではなく振る舞いに基づいて名前を付けてください。各ケースは、その入力と期待値を示し、それ以外は何も示しません。すべてのケースで共有されるセットアップはテーブルの上に属します。

テストを実行するときは、常にタイムアウトを渡してください:

go test -count=1 -timeout 60s ./...

-count=1 は結果キャッシュを無効にします。結果キャッシュは、変更したばかりのコードに対して合格を報告します。タイムアウトは見た目以上に重要です。タイムアウトなしのデッドロックしたテストは、マシンが停止するまでメモリを消費し続けます。

パッケージのエクスポートされた振る舞いをテストしてください。エクスポートされていない内部に到達するテストは、実装を固定化し、誠実なリファクタリングのたびに失敗します。

テストがflakyな場合、ほとんどの場合、実際の競合状態を報告しています。そうでないと結論付ける前に -race フラグ付きで実行し、スリープを追加して修正しないでください。

完了と呼ぶ前に

変更をカバーする最も狭いテストを実行し、共有契約が変更された場合は範囲を広げてください。終了コードを飲み込む可能性のあるmakeターゲットではなく、サービス内で golangci-lint run を実行してください。テストを弱めるのではなく、出力を添えて失敗を報告してください。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

関連スキル