Extend Service Extension のローカルデバッグガイド
注釈：本資料はAI技術を用いて翻訳されています。
概要
このガイドでは、ローカルマシンで Extend Service Extension アプリをデバッグする方法を説明します。
すべての Extend アプリタイプに共通するデバッグ概念（環境変数のセットアップ、VS Code デバッグワークフロー、ログの読み方、よくある起動時のエラーなど）については、 Extend ローカルデバッグガイドを参照してください。
このガイドは Visual Studio Code（VS Code） を中心に説明しますが、概念自体はどのエディタや IDE にも適用できます。
言語固有のセットアップ（前提条件、プロジェクト構成、実行コマンド、デバッガー設定）については、 ご利用の言語のガイドに直接進んでください。
リクエストがサービスを通過する流れ
すべての Extend Service Extension アプリは、言語に関わらず同じレイヤー構造のスタック上に構築されています。 この仕組みを理解することで、問題の発生箇所を絞り込みやすくなります。
Game Client / AGS
│ HTTP (REST)
▼
gRPC-Gateway (port 8000) ← HTTP ↔ gRPC を変換
│ gRPC
▼
gRPC Server (port 6565) ← ビジネスロジックはここにある
│
▼
AccelByte CloudSave / その他の AGS サービス
ポートの概要:
| ポート | 用途 |
|---|---|
6565 | gRPC サーバー（内部用 — gRPC-Gateway が使用） |
8000 | gRPC-Gateway HTTP/REST — ブラウザ、Postman、curl などから呼び出す |
8080 | Prometheus メトリクスエンドポイント（/metrics） |
問題が発生した場合は、レイヤーごとに順を追って調査してください。
| 症状 | 最も可能性の高いレイヤー | まず確認する場所 |
|---|---|---|
| サービスが起動しない | 環境変数 / 認証情報 | .env ファイル、IAM クライアント認証情報 |
| HTTP 4xx レスポンス | Auth インターセプター | service.proto の権限定義 |
| HTTP 5xx レスポンス | ビジネスロジック / ストレージ | サービスおよびストレージの実装ファイル |
| デバッガーが一度も停止しない | ポートの競合またはビルドモード | ポート 6565/8000 で実行中のプロセスを確認 |
| Proto の変更が反映されない | 生成コードが古い | protobuf バインディングを再生成 |
環境セットアップ
共通の変数（AB_BASE_URL、AB_CLIENT_ID、AB_CLIENT_SECRET、
PLUGIN_GRPC_SERVER_AUTH_ENABLED、LOG_LEVEL）とその .env ファイルの作成・確認方法については、
汎用ガイドの環境セットアップを参照してください。
Extend Service Extension 特有の変数: BASE_PATH
Extend Service Extension では、他の Extend アプリタイプにはない、追加の環境変数が1つ必要です。
# このサービスが配信される URL のプレフィックス。/ で始まる必要があります。
BASE_PATH=/guild
| 変数 | 用途 | 例 |
|---|---|---|
BASE_PATH | gRPC-Gateway HTTP エンドポイントの URL プレフィックス。/ で始まる必要があります。 | /guild |
BASE_PATH は、gRPC-Gateway がすべての HTTP エンドポイントを配信する際の URL パスを制御します。
この変数がないとサービスは起動できません。
サービスをローカルで実行する
VS Code タスクおよびターミナルでの実行方法については、 汎用ガイドのサービスをローカルで実行するを参照してください。
gRPC-Gateway が起動していることを確認する
サービスが起動したら、ブラウザで http://localhost:8000<BASE_PATH>/apidocs/ を開いてください。
Swagger UI が表示されエンドポイントが一覧表示されれば、gRPC-Gateway も正しく動作しています。
ご利用の言語における正確なターミナル実行コマンドについては、言語別ガイドを参照してください。
デバッガーの接続
VS Code でのデバッガー接続手順については、 汎用ガイドのVS Code でのデバッガー接続を参照してください。
Service Extension 特有の .vscode/launch.json 設定、および VS Code 以外のセットアップについては、
言語別ガイドを参照してください。
ブレークポイントの設定と状態の確認
ブレークポイントの設定方法、VS Code のデバッグパネルの使い方、コードのステップ実行、条件付きブレークポイントの記述方法については、 汎用ガイドのブレークポイントの設定と状態の確認を参照してください。
SE サービスファイルにおける推奨ブレークポイント配置場所と、言語ごとの条件付き構文の例については、 言語別ガイドを参照してください。
ログの読み方
構造化された JSON ログ形式、ログレベル、gRPC の呼び出しペア、jq の使い方については、
汎用ガイドのログの読み方と理解を参照してください。
言語固有の jq パイプコマンドについては、言語別ガイドを参照してください。
よくある問題
すべての Extend アプリに共通するよくある問題（認証情報のエラー、401 Unauthenticated、ブレークポイントに一度も到達しない、など）については、 汎用ガイドのよくある問題を参照してください。
以下は、Extend Service Extension 特有の問題です。
サービスが起動しない — BASE_PATH が設定されていない
症状:
{"level":"ERROR","msg":"BASE_PATH envar is not set or empty"}
原因: BASE_PATH 環境変数が設定されていない、または / で始まっていません。
解決策: .env に BASE_PATH=/guild（または / で始まる任意のパス）を追加し、サービスを再起動してください。
エンドポイントが 500 Internal Server Error を返す
症状: HTTP 500 または gRPC ステータス Internal。
診断方法:
- リクエストが発生した時刻付近のターミナル出力で
ERRORログを確認します。 - 失敗しているサービスメソッド内にブレークポイントを設定します。
- ストレージ呼び出しにステップインし、CloudSave がエラーを返していないか確認します。
- リクエスト内の
namespaceが、AGS 環境内の実在するネームスペースと一致しているか確認します。
Proto の変更が反映されない
症状: service.proto を編集したが、サービスの動作が変わらない。
原因: 生成されたコードスタブが再生成されていません。
解決策: VS Code の 「Proto: Generate」 タスクを実行するか、./proto.sh を直接実行してから、
サービスを再起動してください。
エンドポイントを手動でテストする
Swagger UI
ブラウザで http://localhost:8000<BASE_PATH>/apidocs/ にアクセスしてください。
組み込みの Swagger UI を使えば、追加のセットアップなしでブラウザから直接 API ドキュメントを読み、リクエストを送信できます。
Postman
リポジトリ内の demo/ ディレクトリには、事前に構築されたリクエストを含む Postman コレクションファイル
（*.postman_collection.json）が用意されています。これらを Postman にインポートし、
環境変数（baseUrl、namespace、token）をローカル環境に合わせて更新してください。
curl と grpcurl
curl と grpcurl を使ったテストについては、
汎用ガイドのgrpcurl でのテストを参照してください。
PLUGIN_GRPC_SERVER_AUTH_ENABLED=true の場合は、すべての curl リクエストに
-H "Authorization: Bearer <your-token>" を追加してください。
AI を活用したデバッグ
チームで AI ツールを使用していない場合、または業務での AI 利用が推奨されていない場合は、 このセクションをスキップしてください。このガイドの他のセクションはすべて単独で完結しており、 AI アシスタントは必要ありません。
Claude Code、GitHub Copilot などの AI コーディングアシスタントは、 見慣れないコードの説明、ログの解析、的確な修正案の提示など、デバッグの補助役として活用できます。
デバッグスキルの使用
Extend Service Extension アプリテンプレートには、.claude/skills/debugging-guide/SKILL.md
にあらかじめ用意された エージェントスキル が付属しています。スキルとは、特定の領域（この場合は
Extend アプリのデバッグ支援）で AI が何をすべきかを正確に指示する一連の指示のことです。
このスキルファイルは、各言語のテンプレートリポジトリで利用できます。
| 言語 | SKILL.md |
|---|---|
| Go | .claude/skills/debugging-guide/SKILL.md |
| C# | .claude/skills/debugging-guide/SKILL.md |
| Java | .claude/skills/debugging-guide/SKILL.md |
| Python | .claude/skills/debugging-guide/SKILL.md |
スキルが有効になったら、AI チャットで以下のいずれかを入力して呼び出します。
| 意図 | 入力内容 |
|---|---|
| 実際の問題をデバッグする | /debugging-guide Go — getting 500 on GetGuildProgress |
| デバッグガイドを作成・更新する | /debugging-guide write Go |
| AI に判断させる | 問題を自然な文章で説明する — AI が適切なモードを選択します |
エージェントスキルは Claude Code でそのまま動作します。他の AI ツールや IDE 拡張機能を使用する場合は、
Agent Skills オープンスタンダードに対応しているかどうかを確認してください。
ご利用のツールがスキルに対応していない場合は、.claude/skills/debugging-guide/SKILL.md の内容をコピーし、
チャットセッションの最初のメッセージ（またはシステムプロンプト）として貼り付けてください。
以下は、参考用のスキルファイル全文です。これをコピーして、ご自身の Extend アプリリポジトリの
.claude/skills/debugging-guide/SKILL.md として保存できます。
デバッグスキル全文を表示（SKILL.md）
---
name: debugging-guide
description: >
Expert guide writer and debugging assistant for AccelByte Extend Service Extension apps.
Use when a developer asks for help debugging their Extend service, diagnosing startup or
runtime errors, understanding logs, setting up a debugger, or when writing or updating a
DEBUGGING_GUIDE.md for an Extend app. Covers Go but the workflow is applicable to other
supported languages (Python, C#, Java).
argument-hint: "[language] [brief issue description or 'write guide']"
allowed-tools: Read, Grep, Glob, Bash(go *), Bash(dlv *), Bash(ss *), Bash(curl *), Bash(grpcurl *), Bash(jq *)
---
# Debugging Guide Skill — Extend Service Extension
You are an expert backend developer and technical writer specializing in AccelByte Gaming
Services (AGS) Extend apps. Your two modes of operation are:
1. **Debug Mode** — Help a developer diagnose and fix a real issue in their running service.
2. **Write Mode** — Author or update a `DEBUGGING_GUIDE.md` for an Extend Service Extension repository.
Detect which mode is needed from `$ARGUMENTS`. If the argument mentions a specific error,
log output, or symptom, use Debug Mode. If it mentions "write", "guide", or "document", use
Write Mode. If ambiguous, ask one clarifying question: *"Do you want help debugging a live
issue, or do you want me to write/update the debugging guide?"*
---
## Architecture Context
Every Extend Service Extension app shares this layered architecture:
\`\`\`
Game Client / AGS
│ HTTP (REST)
▼
gRPC-Gateway (port 8000) ← translates HTTP ↔ gRPC
│ gRPC
▼
gRPC Server (port 6565) ← business logic lives here
│
▼
AccelByte CloudSave / other AGS services
\`\`\`
Key environment variables:
| Variable | Purpose |
|---|---|
| `AB_BASE_URL` | AccelByte environment base URL |
| `AB_CLIENT_ID` / `AB_CLIENT_SECRET` | OAuth client credentials |
| `BASE_PATH` | URL prefix (must start with `/`) |
| `PLUGIN_GRPC_SERVER_AUTH_ENABLED` | `false` to skip IAM token validation locally |
| `LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` |
---
## Debug Mode
### Step 1 — Identify the layer where the failure occurs
- Service fails to **start** → environment variables and IAM login.
- Returns **4xx** → auth interceptor and proto-defined permissions.
- Returns **5xx** → business logic and storage layer.
- Debugger **won't pause** → port conflicts or build mode.
- **Proto changes ignored** → regenerate bindings.
### Step 2 — Collect evidence
1. Ask for full log output at `LOG_LEVEL=debug`. Look for `"level":"ERROR"` lines.
2. Read the source files referenced in the error before suggesting a fix.
3. Check environment: `printenv | grep -E 'AB_|BASE_PATH|PLUGIN_GRPC|LOG_LEVEL'`
4. Check ports: `ss -tlnp | grep -E '6565|8000|8080'`
### Step 3 — Common-issue checklist
| Symptom | Likely cause | Where to look |
|---|---|---|
| `BASE_PATH envar is not set or empty` | Missing/invalid `BASE_PATH` | `main.go` startup |
| `unable to login using clientId and clientSecret` | Wrong credentials or unreachable `AB_BASE_URL` | `main.go` → OAuth login |
| All requests return `401 Unauthenticated` | Token missing/expired or wrong permission | Auth interceptor; `service.proto` |
| `500 Internal Server Error` | CloudSave call failed or data parse error | Storage and service files |
| Breakpoints never hit | Wrong port, auth failure before breakpoint | Disable auth, check port conflicts |
| Proto changes have no effect | Generated code not regenerated | Run `./proto.sh` |
### Step 4 — Suggest a minimal fix
- Explain *why* the fix works.
- Read the file first, then show the exact change.
- Provide a verification step after every fix.
### Step 5 — Verify
\`\`\`bash
# Confirm service starts cleanly
go run main.go 2>&1 | jq 'select(.level == "ERROR")'
# Confirm endpoint responds
curl -s http://localhost:8000/guild/v1/admin/namespace/mygame/progress | jq .
# Confirm gRPC layer directly
grpcurl -plaintext localhost:6565 list
\`\`\`
---
## Write Mode
### Audience
Junior developers and game developers with limited backend experience. Avoid assuming knowledge
of gRPC, protobuf, or IAM. Use plain language. VS Code-centric but include notes for other IDEs.
### Required sections
1. Overview + architecture diagram
2. Project structure reference (file-to-responsibility table, port table)
3. Prerequisites (language-specific)
4. Environment setup (.env, key variables, why to disable auth locally)
5. Running the service (terminal + VS Code task)
6. Attaching the debugger (VS Code launch config, other IDEs/headless)
7. Breakpoints and inspection (placement table, stepping shortcuts, conditional breakpoints)
8. Reading logs (format, levels, gRPC pairs, jq)
9. Common issues (symptom / cause / fix per issue)
10. Testing endpoints manually (Swagger UI, curl, Postman, grpcurl)
11. AI-assisted debugging (this skill, MCP servers, prompting tips)
12. Tips and best practices
### Before writing, always read first
1. Existing `DEBUGGING_GUIDE.md` if present — update, do not replace accurate content.
2. `main.go` (or equivalent entry point) for ports, startup sequence, and env vars.
3. Service and storage files to understand the business logic layer.
4. `.vscode/launch.json` for the debug configuration name and settings.
5. `.vscode/mcp.json` for configured MCP servers.
6. `service.proto` for endpoint names and permission requirements.
MCP サーバー
このアプリテンプレートには、.vscode/mcp.json に2つの Model Context Protocol（MCP）
サーバー設定が付属しています。これらは、AI アシスタントに AccelByte 固有の知識への直接アクセスを提供します。
| サーバー | 提供する内容 |
|---|---|
| (ags-extend-sdk-mcp-server)[https://github.com/AccelByte/ags-extend-sdk-mcp-server] | AccelByte Extend SDK のシンボル、型、使用パターンに関する知識 |
| (ags-api-mcp-server)[https://github.com/AccelByte/ags-api-mcp-server] | AGS REST API へのライブアクセス（環境に AB_BASE_URL が必要） |
Extend アプリをデバッグする際の一般的な AI プロンプトのコツについては、 汎用ガイドのAI を活用したデバッグを参照してください。
ログを貼り付けて要約を依頼する。
「Extend Service からの JSON ログ 30 行です。どのリクエストが失敗し、原因は何ですか?」
バグを理解したら、的を絞ったテストを依頼する。
「CloudSave が not-found エラーを返すケースをカバーする、
GetGuildProgressの Go 単体テストを書いてください。pkg/service/mocks/内のモックを使用してください。」
ヒントとベストプラクティス
ログレベル、認証の無効化、条件付きブレークポイント、VS Code パネル、ポート確認など、一般的なヒントについては、 汎用ガイドのヒントとベストプラクティスを参照してください。
Extend Service Extension 特有のヒント:
-
.protoを変更したら、必ず proto バインディングを再生成してください。service.protoを編集した後に./proto.shを実行し忘れることは、わかりにくいコンパイルエラーや実行時エラーの 最も一般的な原因の1つです。正確な再生成コマンドについては、各言語のガイドを参照してください。 -
権限については
service.protoを確認してください。 有効なトークンを使用しているにもかかわらず リクエストが401 Unauthenticatedを返す場合は、service.proto内の該当する RPC のpermission.resourceとpermission.actionフィールドを確認してください。エンドポイントが 要求する正確な権限をトークンが持っていない可能性があります。
言語別ガイド
上記のセクションでは、すべての言語に共通する概念とワークフローを説明しています。セットアップ手順、 プロジェクト構成、実行コマンド、デバッガー設定、言語固有のトラブルシューティングについては、 ご利用の言語専用のガイドを参照してください。