開発者マニュアル Stable
TenkaCloud本体、インフラコード、共通パッケージ、各Portal、リポジトリのツールを変更 する人のためのマニュアルです。本体のコードを変えずに競技をデプロイする作業は 競技開催者の役割です。
あなたのゴール
プラットフォームの契約を壊さず、必要なリポジトリ検査に通る、範囲の明確な変更を 1つ作ります。
リポジトリを準備する
bun install
git submodule update --init problems
make doctor
make doctorは不足しているローカル要件を表示しますが、自動インストールや設定変更
は行いません。Getting startedから必要な実行経路
だけを選びます。
変更前に担当場所を見つける
| パス | 担当 |
|---|---|
apps/ |
管理者・参加者・開発者向けWebアプリ |
infrastructure/ |
AWS CDK stack、環境設定、デプロイ経路 |
packages/ |
共通contract、SDK、runtime adapter、CLI |
scripts/ |
リポジトリ検査、デプロイ補助、生成物 |
problems/ |
commitを固定した公式問題カタログsubmodule |
契約を変える前に、最寄りのテストとリポジトリ内の指示を読みます。 プラットフォーム構成はplane間の責務とevent 契約を説明しています。
変更の流れ
- テスト可能な完了条件を持つGitHub Issueから始める。
- 最小の担当moduleと既存テストを見つける。
- 実装と利用者向け文書を同時に更新する。
- 作業中は範囲を絞ったテストを実行する。
- Pull Request前に
make harnessとmake before-commitを実行する。 - 最終差分を確認し、対象ファイルだけをstageする。
.env、認証情報、生成されたsecret、無関係な変更をcommitしません。単体テストが
greenでも、実AWSデプロイやブラウザ操作まで証明したことにはなりません。未確認の
境界は正確に報告します。
コード変更か環境設定か
- 対応済みの値へ開催者が変えるだけなら、既存の
.envパラメータを使い、説明を 更新します。競技開催者マニュアルを参照。 - 受け付ける値、検証、生成リソース、実行時の挙動を変えるなら、担当コード、テスト、
.env.example、マニュアルを同じPull Requestで更新します。 - データベース保存先の変更では、データ移行とロールバックの境界を明示します。 暗黙のdual writeを追加しません。
MCP 2026-07-28
TenkaCloudのAlways-On control planeは、sessionを持たないMCP 2026-07-28 endpointを 提供します。MCPは、AI clientがTenkaCloudの許可された機能を呼ぶための共通形式です。 開発者向け接続では、専門用語の説明と対応runtime一覧だけを読み取れます。
接続先は{ALWAYS_ON_CONTROL_PLANE_ORIGIN}/mcp/developerです。clientは最初に
server/discoverを呼び、各requestへ次を付ける必要があります。
MCP-Protocol-Version: 2026-07-28- JSON bodyのmethodと同じ
Mcp-Method tools/callとresources/readでは、対象名と同じMcp-Name_meta内のprotocol version、client info、client capabilities
このendpointはinitialize、Mcp-Session-Id、sticky routingを使いません。旧仕様だけを
話すclientは接続できません。公開情報の一覧結果には5分のpublic cache、認証後の結果には
保存しないprivate cache指定が返ります。request bodyが32 KiBを超えると、toolを
実行する前に拒否します。
| endpoint | 境界 |
|---|---|
/mcp/developer |
公開・read-only。explain_concept、list_runtime_capabilities |
/mcp/problem-author |
公開・read-only。渡されたJSONだけを純粋に検証 |
/mcp/organizer |
Auth0 issuer、audience、organization、tenant、roleを既存middlewareで検証 |
/mcp/participant |
team keyを検証し、そのteam IDとevent IDだけへ固定 |
開催者endpointが401 Unauthorizedを返す場合、WWW-Authenticate内の
resource_metadataから保護対象リソース情報を取得できます。現行のAuth0構成では、
管理者が事前登録したOAuth clientを使用します。Dynamic Client Registration（DCR）を
公開せず、Client ID Metadata Document（CIMD）は接続先の認証サーバーが
client_id_metadata_document_supported対応を明示した場合にだけ使用します。
deploy、teardown、設定変更を同期toolとして公開していません。将来追加する場合は Tasks extensionでdurable handle、cancel、idempotencyを実装し、危険な操作は multi-round-trip requestによる明示確認を要求します。それまでは既存の画面と運用手順を 使用します。
MCP hostはtoolを呼ぶたびにtool名と引数を表示し、利用者の承認を得る必要があります。 現在の全toolはread-only、non-destructive、idempotentと宣言しています。ただしHTTP serverから、remote clientが手元の承認画面を本当に表示したかは確認できません。確認 なしでtoolを呼ぶclientは接続しないでください。
MCPの実装はapps/always-on-control-plane、problem検証contractは
packages/problem-sdkが担当します。protocol header、role間の認証混同、他tenant・
他team・flag・credentialの漏えいをnegative testで確認します。
レビュー依頼前の確認
- 新しい挙動を確認する範囲の絞られたテストがある。
- 利用者向けの英語と日本語が一致している。
- 生成物と索引が最新である。
- link、type、format、関係するbuildが通る。
- 未実施のライブ検証をNot runと書く。
- IssueとPull Requestがコード差分だけでなく利用者への影響を説明している。
問題内容を変更する作業はpackの担当です。その場合は 問題作成者マニュアルを使ってください。