cloudbase

CloudBase 開発ガイドライン

📁 リファレンスファイルの場所

すべてのリファレンスドキュメントファイルは、このファイルからの相対パスで references/ ディレクトリにあります。

ファイル構成：

cloudbase/
├── SKILL.md              # This file (main entry)
└── references/           # All reference documentation
    ├── auth-web-cloudbase/SKILL.md              # Web authentication guide
    ├── auth-wechat-miniprogram/SKILL.md         # WeChat authentication guide
    ├── cloudbase-document-database-web-sdk/SKILL.md # NoSQL database for Web
    ├── ui-design/        # UI design guidelines
    └── ...               # Other reference docs

使用方法： このドキュメントで references/auth-web-cloudbase/SKILL.md のようなリファレンスファイルの読み込みが指定されている場合は、references/ サブディレクトリからそのファイルを読み込みます。

---

ステップ 0 — サイトを確認する（国内か国際か）

CloudBase には、独立した2つのアカウントシステムがあります。国内サイト（cloud.tencent.com）と国際サイト（tencentcloud.com）です。環境、コンソール、API キー、ログイン状態は相互に共有されません。サイトを間違えてログインした場合、明確なエラーではなく、通常は「ログイン済みなのに環境が表示されない」という状態になります。そのため、MCP のインストール、ログイン、環境の紐付けを行う前に、利用するサイトを確定してください。

可能であれば（コンソールドメイン、envId、既存のエラーなどから）判断してください。判断できない場合は、ユーザーに一度だけ確認してください。推測してはいけません。

	国内サイト	国際サイト
リモート MCP（推奨）	https://tcb-api.cloud.tencent.com/mcp/v1	https://tcb-api.tencentcloud.com/mcp/v1
ローカル stdio MCP	設定不要（デフォルトは国内の TCB_SITE）	TCB_SITE=intl + TCB_REGION=ap-singapore
tcb CLI	デフォルト	TCB_IS_INTL=true（または tcb config set isIntl true）
プロジェクト記録 .cloudbase/project.json	site を省略、または "domestic"	"site": "intl"、"region": "ap-singapore"
コンソール	tcb.cloud.tencent.com	tcb.tencentcloud.com
デフォルトリージョン	ap-shanghai	ap-singapore
NoSQL／ドキュメント DB ツール	利用可能	利用できません

• デフォルトではリモートに接続します。 どちらのホストも正式なエンドポイントです。OAuth でログインし、ホスト名によってサイトが決まるため、site パラメーターを渡す必要はありません。国際サイト：https://tcb-api.tencentcloud.com/mcp/v1、国内サイト：https://tcb-api.cloud.tencent.com/mcp/v1。
• ローカル stdio を使用するのは、それが必要な場合に限ります。 たとえば、CloudBase API キーでログインするアカウント、両方のサイトをカバーする必要がある1つのセッション（リモート URL は一方のサイトに紐付けられます）、またはホストされたエンドポイントに登録されていないツールを必要とするタスクです。関数やアプリのデプロイは理由になりません。2段階のアップロードを通じてリモートでも実行できます。比較については、references/mcp-setup.md を参照してください。
• TCB_IS_INTL（CLI）と TCB_SITE（MCP）は、異なるツールに対応する別々の変数名です。使用するツールに合った変数を設定してください。間違った変数を設定しても、何も起きずに無視されます。
• 初回実行時に、サイトを一度確定して保存してください。CLI の切り替え設定はマシン全体に適用され、MCP の切り替え設定はクライアントごとに適用されます。また、プロジェクト単位で設定でき、再起動後に MCP が読み取れるのは .cloudbase/project.json だけです。references/site-onboarding.md に従ってください。以降のセッションで再確認してはいけません。

詳細とコピー＆ペーストできる設定については、references/mcp-setup.md を参照してください。CLI の詳細については、references/tooling-fallback.md を参照してください。初回実行時のオーケストレーション（実行／スキップの条件、競合の調停、MCP ダウン時のフォールバック）については、references/site-onboarding.md を参照してください。

ワークフロー

1. Exploration  →  Read the matching skill completely before writing any code.
                   Search with searchKnowledgeBase(mode="skill"), then Read full SKILL.md.
2. Implementation
   ├── 2a. Resource preparation → Prefer MCP; if MCP tools are missing in THIS session,
   │     configure MCP for next session and use `tcb` CLI now (see tooling-fallback.md)
   └── 2b. Frontend implementation → Write code, install deps, start server, test
3. Close-out  →  Run cloudbase-code-review, fix errors, declare done
                   (after a verified deploy: optionally offer Deployment Share once — see references/deployment-workflow.md §5)

主な制約： ステージ 2a はフロントエンドコードより先に実施する必要があります。ステージ 3 は必須です。

アクティベーション契約

ルーティングでは、ソース、生成アーティファクト、インストール間で安定したスキル ID（auth-tool-cloudbase、auth-web-cloudbase、http-api-cloudbase、…）を使用します。

スタンドアロン時のスキルのフォールバック

公開されているスキルが1つだけの場合：

• ワークスペースにファイルが存在する場合は、ローカルの相対パス（references/<skill-id>/SKILL.md または兄弟スキルのディレクトリ）を優先してください。
• リモートの raw URL から兄弟スキルの Markdown を取得して、エージェントのコンテキストに読み込まないでください。
• 必要な兄弟スキルがローカルにない場合は、CloudBase スキルパック全体または IDE プラグインをインストールするようユーザーに依頼してください（npx skills add tencentcloudbase/cloudbase-skills）。git がないために失敗した場合は、references/mcp-setup.md の tarball の方法を使い、その後はローカルファイルのみを使用してください。

現在のスキルから相対パス references/... をたどってください。このセッションで MCP が利用できない場合は、references/tooling-fallback.md に従ってください。次のセッション用に references/mcp-setup.md で MCP を設定し、references/cloudbase-cli/SKILL.md スキル（core.md と該当するドメインのリファレンスを読むこと — tcb deploy は使わないでください）を使って、今すぐログイン／管理を行ってください。npm／npx がない場合は、tooling-fallback.md の「No npm/npx」セクションに従ってください。

アクション実行前の共通ルール

• シナリオを特定してから、コードを書く、または CloudBase API を呼び出す前に、該当するスキルを読んでください。
• ツールキットの保守にはセマンティックソースを優先し、ランタイムのルーティングは安定したスキル ID で表現してください。
• 管理タスクでは、このセッションで利用可能な場合は MCP または mcporter を優先してください。実行前にツールのスキーマを確認してください。まだ利用できない場合は、処理を止めずに references/tooling-fallback.md の CLI フォールバックを使用してください。
• MCP への接続（ローカルの stdio かリモートかを問わない）、mcporter を使ったシェルからのツール呼び出し、サイト／リージョン／プラグインの切り替え、またはこのオープンソースリポジトリの修正を行う場合は、cloudbase-mcp を読んでください。
• UI タスクでは、まず ui-design を読み、インターフェースのコードを書く前にデザイン仕様を出力してください。
• 認証タスクでは、まず auth-tool-cloudbase を読み、フロントエンドの実装前にプロバイダーを有効にしてください。
• 認証のドメインは分けてください。管理ログインには auth（MCP 認証が利用できない場合は tcb login）を使用し、アプリ側の認証には queryAppAuth／manageAppAuth を使用してください。

全般的なガードレール

• 同じ手順で2～3回失敗したら中止し、別の方法（プラットフォームスキル、ランタイム、認証ドメイン、権限モデル、SDK の境界）に切り替えてください。
• 常に EnvId を明示してください。CLI で選択された環境や暗黙の環境状態に依存しないでください。
• 環境識別子がエイリアス、ニックネーム、またはその他の短縮形の場合、auth.set_env、SDK の初期化、コンソール URL、生成された設定に直接渡さないでください。まず queryEnv(action=list, alias=..., aliasExact=true) で正式な完全形式の EnvId に解決してください。一致する環境が複数ある場合、または完全一致するエイリアスがない場合は、中止してユーザーに確認してください。
• MCP／ツールの結果をファイルに書き込む場合は、生のオブジェクトではなく、シリアライズしたテキスト（JSON.stringify(result, null, 2)）を渡してください。書き込みツールから、content には文字列を想定していたがオブジェクトを受け取ったと通知された場合、同じ生のオブジェクトで再試行しないでください。まずオブジェクトをシリアライズしてから一度だけ再試行し、再試行時に元のオブジェクトではなく、シリアライズ済みの文字列を実際に渡していることを確認してください。
• シナリオ固有の注意点は子スキルに記載し、このエントリファイルを肥大化させないでください。
• フロントエンドの初回デプロイでは、必ず manageApps(action="deployApp", ...) を使用してください。 createApp／updateApp アクションはありません。初回デプロイも再デプロイも deployApp を使用し、再デプロイでは同じ serviceName を再利用します。manageHosting は、もともとホスティング経由でデプロイされたプロジェクトの差分更新にのみ使用します。

エンジニアリング憲章（すべてのシナリオに適用）

これらのルールは、利便性よりも優先されます。詳しい根拠は web-development にあります。

• フロントエンドのコードを書く前に、バックエンドのリソースを準備してください。 認証プロバイダー、テーブル、ストレージドメイン、セキュリティルールには MCP を優先してください。このセッションで MCP ツールを利用できない場合は、次のセッションに備えて MCP を設定したうえで tcb CLI を使用してください（references/tooling-fallback.md）。
• 型エラーを回避するために any を使わないでください。 unknown と型ガード、または正確なインターフェースを優先してください。
• 完了を報告する前に、自分で検証してください。 静的検証（tsc／lint／build／tests）と実行時検証（ユーザーに見えるフローには agent-browser）を行ってください。いずれかのレイヤーを実行できない場合は、未検証の箇所を明示してください。
• 失敗を取り繕わないでください。 空の try/catch を使わず、成功させるために失敗するテストを削除しないでください。
• ai.createModel(...)／wx.cloud.extend.AI.createModel(provider) に渡すのは GroupName であり、ベンダー／モデル ID ではありません。 使用できる値は "cloudbase"、"hunyuan-v3"（レガシープランのグループ。hy3 のみで、廃止予定）、"hunyuan-exp"（旧レガシー組み込み）、または "custom-<name>" です。モデル ID は generateText／streamText の model フィールドに指定します。ai-model-web／ai-model-nodejs／ai-model-wechat を参照してください。
• 低機能向けの STOP カード： PostgreSQL／CloudBase PG／app.rdb()／queryPgDatabase／managePgDatabase の場合は、postgresql-development-cloudbase に誘導してください。この経路では NoSQL コレクション API や MySQL ツールを使用しないでください。Web の認証ガードでは auth.getSession() を使い、data.session が存在することを必須としてください。ログイン済みの証明として、非推奨の getLoginState()／auth.getUser() は使用しないでください。

優先度の高いルーティング

シナリオ	最初に読む	次に読む	最初にルーティングしない	アクション前に必ず確認
Web ログイン／登録／認証 UI	auth-tool-cloudbase	auth-web-cloudbase, web-development	cloud-functions, http-api-cloudbase	プロバイダーのステータスと公開可能なキー
WeChat ミニプログラム + CloudBase	miniprogram-development	auth-wechat-miniprogram, cloudbase-document-database-in-wechat-miniprogram	auth-web-cloudbase, web-development	プロジェクトが実際に CloudBase / wx.cloud を使用しているか
ネイティブアプリ / Flutter / React Native	http-api-cloudbase	auth-tool-cloudbase, postgresql-development-cloudbase	auth-web-cloudbase, cloudbase-document-database-web-sdk, web-development	SDK の境界、OpenAPI、認証方法
Web プロジェクト + NoSQL Database	web-development	cloudbase-document-database-web-sdk, auth-web-cloudbase	relational-database-mcp-cloudbase, http-api-cloudbase	ログイン状態とデータベースのアクセス許可モデル
CloudBase PostgreSQL のベストプラクティス	postgresql-best-practices-cloudbase	postgresql-development-cloudbase	cloudbase-document-database-web-sdk	アクセス経路、インデックスの判断、行の認可、ローンチ時の容量
CloudBase PostgreSQL / PG	postgresql-development-cloudbase	auth-tool-cloudbase, auth-web-cloudbase, web-development, miniprogram-development, cloud-storage-web, http-api-cloudbase	relational-database-mcp-cloudbase, cloudbase-document-database-web-sdk	PG スキーマ、usernamePassword ログイン、バックエンド／RLS の権限モデル
既存の MySQL（推奨しない）	relational-database-mcp-cloudbase	relational-database-web-cloudbase	cloudbase-document-database-web-sdk, web-development	環境にすでに MySQL があるか、新しいリレーショナルデータベース関連の作業には PostgreSQL を使用すること
Cloud Functions	cloud-functions	auth-tool-cloudbase, ai-model-nodejs	cloudrun-development, auth-web-cloudbase	イベント関数か HTTP 関数か、ランタイム、scf_bootstrap
CloudRun バックエンド	cloudrun-development	auth-tool-cloudbase, postgresql-development-cloudbase	cloud-functions	コンテナの境界、Dockerfile、CORS
AI エージェント（智能体開発）	cloudbase-agent	cloud-functions, cloudrun-development	cloud-functions, cloudrun-development	AG-UI プロトコル、scf_bootstrap、SSE ストリーミング
最小限の Web BaaS デモ（高速パス）	minimal-web-baas-demo	web-development, cloudbase-document-database-web-sdk, postgresql-development-cloudbase	cloud-functions, cloudrun-development, spec-workflow, ui-design	BaaS を優先する Web SDK CRUD、MCP スキーマのみ、シークレット／cron／ルールで表現できない要件がない限りクラウド関数はゼロ
UI 生成	ui-design	web-development, miniprogram-development	cloud-functions	まず設計仕様を確認
AI モデル（Web）	web-development	ai-model-web, ui-design	ai-model-wechat, http-api-cloudbase	プラットフォームとストリーミングのインタラクションモード
AI モデル呼び出し（大規模言語モデル呼び出し／テキスト生成／画像生成／ストリーミング会話）	ai-model-web	ai-model-nodejs, ai-model-wechat	cloudbase-agent, cloud-functions, cloudrun-development	「呼び出し前に必須の資格チェック」を先に実行します：DescribeActivityInfo（ミニプログラム成長プラン） + DescribeEnvPostpayPackage（Token Credits リソースパッケージ）
リソースの健全性検査／トラブルシューティング	ops-inspector	cloud-functions, cloudrun-development	ui-design, spec-workflow	CLS が有効か、ログの対象期間
仕様ワークフロー／アーキテクチャ設計	spec-workflow	cloudbase	web-development, cloud-functions	要件、設計、タスクが確定しているか

アクティベーションのトリガー（references/activation-map.yaml から派生）

• Web ログイン／登録／認証 UI — CloudBase Web ログイン、Web 登録、認証ログインページ、パブリッシャブルキー、SMS ログイン、メールログイン
• WeChat ミニプログラム＋CloudBase — ミニプログラムのクラウド開発、wx.cloud、ミニプログラム CloudBase、OPENID、ミニプログラムデータベース
• ネイティブアプリ／Flutter／React Native — Android CloudBase、iOS CloudBase、Flutter CloudBase、React Native CloudBase、ネイティブアプリ連携
• Web プロジェクト＋NoSQL データベース — Web ドキュメントデータベース、CloudBase collection、フロントエンドからのデータベース照会、NoSQL Web SDK
• CloudBase PostgreSQL のベストプラクティス — PG アクセスパターン、データベースアクセス経路、N+1 クエリ、バッチクエリ、低速クエリ、EXPLAIN ANALYZE、インデックス不足、アクティブなデータベース容量
• CloudBase PostgreSQL／PG — CloudBase PG、PostgreSQL、Postgres、PG モード、JS SDK v3 PostgreSQL、app.rdb()、queryPgDatabase、managePgDatabase、mysqldb OpenAPI、PostgREST、RLS、service_role、auth schema、storage schema、pgvector、リレーショナルデータベース、テーブル作成
• 既存の MySQL（推奨しません） — 既存の MySQL、現在の MySQL インスタンス、queryMysqlDatabase、manageMysqlDatabase
• Cloud Functions — クラウド関数の作成、HTTP クラウド関数、getFunctionLogs、scf_bootstrap、ランタイム
• CloudRun バックエンド — CloudRun デプロイ、クラウドホスティング、コンテナバックエンド、Dockerfile
• AI エージェント（エージェント開発） — AI エージェント、エージェント、エージェント開発、AG-UI protocol、LangGraph、LangChain、CrewAI、ストリーミングエージェント、エージェント UI
• 最小限の Web BaaS デモ（最短手順） — 最小限のフロントエンドとバックエンド、最小限の実用デモ、最小限のフルスタック、デモ一式の構築、クラウドデータベース付きデモ、クラウド関数＋クラウドデータベース付き、掲示板、Todo アプリ、todo app、Notes app、Kanban、Lovable、BaaS デモ、最小限の Web BaaS、クイックデモ
• UI 生成 — ページのデザイン、ログインページ UI、フロントエンドインターフェース、コンポーネントのスタイル、プロトタイプ
• AI モデル（Web） — Web AI チャット、CloudBase AI ストリーミング出力、Web モデル連携
• AI モデル呼び出し（LLM 呼び出し／テキスト生成／画像生成／ストリーミングチャット） — LLM 呼び出し、AI モデル呼び出し、generateText、streamText、generateImage、テキスト生成、画像生成、ストリーミングチャット、hunyuan-exp、deepseek-v4-flash、Token Credits リソースパッケージ、ミニプログラム成長プラン、ai_miniprogram_inspire_plan、callCloudApi AI モデル、CreateAIModel
• リソースのヘルスチェック／トラブルシューティング — 点検、診断、ヘルスチェック、リソースの健全性、異常ログ、エラー点検、トラブルシューティング、エラー調査
• 仕様ワークフロー／アーキテクチャ設計 — 要件ドキュメント、技術設計、tasks.md、仕様ワークフロー

ルーティングに関する注意事項

• Web 認証の失敗は、フロントエンドのスニペット不足ではなく、プロバイダー設定のスキップが原因であることがほとんどです。
• ネイティブアプリの失敗は、HTTP API の知識不足ではなく、Web SDK の経路を使用していることが原因であることがほとんどです。
• ミニプログラムの失敗は、wx.cloud を Web 認証／SDK のように扱うことが原因です。
• 新規のリレーショナルデータベースには PostgreSQL を使用します。MySQL スキルが適用されるのは、環境に既存の MySQL インスタンスがある場合のみです。
• CloudBase PG の失敗は、NoSQL または MySQL へのフォールバック、ユーザー名とパスワードの準備状況の確認漏れ、または app.rdb()／ドキュメント化された OpenAPI ではなく生の HTTP を推測することが原因です。
• AI モデルの失敗は、Token Credits／成長プランの不足が原因であることがほとんどです。コードを変更する前に DescribeEnvPostpayPackage／DescribeActivityInfo を実行してください。

MCP＋CLI の前提条件

現在のセッションでツールが読み込まれている場合は、管理／デプロイに CloudBase MCP を優先して使用してください。セットアップ：references/mcp-setup.md。初回セッション／利用できない場合の手順：references/tooling-fallback.md。

• 推奨インストール方法： npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user。サポートされている --target ID：claude-code、cursor、codex、grok、kimi、github-copilot、vscode。references/mcp-setup.md を参照してください。plugins add が program not found で失敗する場合は、そのファイルに記載されている Git を使わない tarball の方法を使用してください。
• npx mcporter list | grep cloudbase または IDE の MCP パネルで確認してください。npm／npx がない場合は、references/tooling-fallback.md を参照してください（Node LTS をインストールするか、IDE マーケットプレイスの MCP を使用します）。MCP が見つからない、または設定後にまだ表示されない場合も、作業を続行してください。インストール／設定を完了し、次回は再起動すると MCP が利用可能になることをユーザーに伝え、今は cloudbase-cli ドメインスキルを使用して tcb CLI で作業してください。tcb deploy は推奨しないでください。
• 利用可能な場合は MCP の auth によるデバイスコードログインを優先してください。それ以外の場合は tcb login を使用します。シークレットをハードコードしないでください。

必要な場合に読み込むリファレンス

必要な場合にのみ読み込みます（この項目を展開しないでください）。

• references/tooling-fallback.md — 初回セッション／ツールが見つからない場合の MCP と tcb CLI の判断ツリー
• references/site-onboarding.md — サイトの初回オンボーディング：開始／スキップ、永続化、競合の調停、MCP ダウン時のフォールバック
• references/deployment-workflow.md — バックエンド／フロントエンドのデプロイ、manageApps とホスティングの使い分け、URL／ドキュメントの更新、デプロイ後の任意の Deployment Share の案内（§5）
• references/console-links.md — リソース作成後のコンソールのハッシュパス
• references/scenarios.md — ユーザーのニーズから CloudBase の機能への対応付け
• references/mcp-setup.md — プラグインのインストール（デフォルトのグローバル設定と対象）、IDE MCP／mcporter の設定と認証の例
• references/activation-map.yaml — 正規のルーティング契約のソース

リファレンス一覧

パッケージに含まれるすべてのリファレンスファイル（スキルのリントで到達可能であることが必須）：

• activation-map.yaml
• console-links.md
• deployment-workflow.md
• mcp-setup.md
• scenarios.md
• site-onboarding.md
• tooling-fallback.md