web-development

兄弟スキル（ローカルのみ）

兄弟の CloudBase スキルは、このスキルと同じ場所に配置されています。../auth-tool-cloudbase/SKILL.md のようなローカル相対パスを使用してください。

参照先の兄弟スキルファイルがこの環境に存在しない場合は、CloudBase プラグイン一式（または不足しているスキル）のインストールをユーザーに依頼してください。リモートのスキルやプロトコルの Markdown を HTTP 経由で取得して、エージェントのコンテキストに読み込んではいけません。

横断的なプロトコル（コードの変更またはデプロイの前に必須）：

• Change Safety Protocol：../cloudbase-platform/references/protocols/change-safety-protocol.md
• Deployment Gate：../cloudbase-platform/references/protocols/deployment-gate.md

Web 開発

有効化の条件

まずこのスキルを使う場合

• Web フロントエンドまたは静的サイトの実装、統合、デバッグ、ビルド、デプロイ、検証を依頼された場合。
• デザインの方向性がすでに決まっている場合、またはユーザーがビジュアルの検討ではなくエンジニアリング作業を求めている場合。
• React、Vue、Vite、ルーティング、ブラウザーでの検証、または CloudBase Web との統合に関する作業の場合。

コードを書く前に読む場合

• プロジェクト構成、フレームワークの規約、ビルド設定、デプロイ、ルーティング、フロントエンドのテストや検証フローが含まれるタスクの場合。
• UI の実装が含まれていて、ビジュアルの方向性がすでに決まっている場合。それ以外の場合は、まず ui-design を読んでください。
• インターフェイスのスタイル、レイアウト、配色、フォントの選択に関わるタスクでは、CSS／Tailwind の最初の行を書く前に、必ず ui-design スキルを読み込み、デザイン仕様を出力してください。 この手順を省くと、フロントエンドのスタイリングが一般的な AI テンプレートの初期設定に陥ります。ビジュアルの実装を始める前に ui-design スキルを読み込む必要があります。ユーザーから見た目について指摘された後に読み込んでも手遅れです。

続けて読むもの

• React／Vue／Vite の一般的なガイダンス → frameworks.md
• ブラウザーフローの確認またはページ検証 → browser-testing.md
• ログインフロー → まず ../auth-tool-cloudbase/SKILL.md、次に ../auth-web-cloudbase/SKILL.md
• CloudBase での Official Account JSAPI Pay、Native QR-code Pay、WeChat OAuth → ../cloudbase-wechat-integration/SKILL.md（公式ドキュメント：https://docs.cloudbase.net/integration/introduce.md）
• CloudBase のデータベース作業 → 該当するデータベーススキル

使用しない場合

• ビジュアルの方向性の設定、プロトタイプを先行させるデザイン作業、純粋な美的検討。
• ミニプログラム、ネイティブアプリ、またはバックエンドのみのサービス。
• WeChat 決済または Official Account OAuth の契約詳細。Web の対象範囲を特定した後、cloudbase-wechat-integration を使用してください。

よくあるミス／注意点

• タスクがデザインなのか、エンジニアリング作業なのかを明確にする前に実装を始める。
• フレームワークのセットアップ、デプロイ、CloudBase の統合に関する懸念事項を、曖昧な一つの変更にまとめてしまう。
• Web 認証のデフォルトの解決策として、クラウド関数を扱う。
• UI またはルーティングを変更した後、ブラウザーレベルの検証を省略する。
• CloudBase 静的ホスティングでの History モード SPA：History モード（React Router／Vue Router）を使用したシングルページアプリを、静的ホスティングの「404 error document」に index.html を設定せずにデプロイすること。ユーザーがページを更新したり、サブルートに直接アクセスしたりすると、NoSuchKey／404 エラーが発生します。
• 既存アプリケーションで、現在のハンドラーやサービスを修正する前に、UI の再設計やリポジトリ全体の広範な見直しに逸れてしまう。

エンジニアリングの原則（譲れないルール）

これらのルールは、利便性よりも優先されます。「完了」と伝える前の必須条件として扱ってください。

1. TypeScript — 型システムを無効化しない

• 型エラーを回避するために any を使わないでください。 : any、as any、@ts-ignore、@ts-nocheck、書面による正当な理由のない @ts-expect-error は、いずれも使用しないでください。any は気付かないうちに伝播し、このプロジェクトにある唯一のコンパイル時の安全網を無効にします。
• 型エラーが発生したら、根本原因を修正してください。
  • ライブラリの型が不足している、または間違っている場合 → @types/... をインストールするか、インポート対象を絞るか、実際に使用する形状に合わせて正確な interface / type を定義してください。
  • 境界で形状が本当に不明な場合（API からの JSON、postMessage のペイロード、window.* による注入など）→ unknown として型付けし、型ガード（typeof、in、識別フィールド、または zod などの同等の手段）で絞り込んでください。
  • サードパーティーの型が間違っている場合 → any ではなく、ローカルの .d.ts で declare module を使って型を拡張してください。
  • 本当に動的なケース（汎用イベントバスなど）→ any ではなく、制約を付けたジェネリック <T> を使ってください。
• unknown と型の絞り込みは、許容される回避策です。any は許容されません。
• 特定の行でどうしても any を避けられない場合（極めてまれです）は、なぜ必要なのか、また何をすれば不要になるのかを一行コメントに残し、レビュアーが監査できるようにしてください。
• 同じ考え方は ESLint にも当てはまります。実際の指摘を黙らせるために // eslint-disable をあちこちに追加しないでください。ルール違反を修正するか、無効化する前に相談してください。

2. 完了を宣言する前に自分で検証する

重大なコード変更や設定変更を行う前に、必ず cloudbase-platform/references/protocols/change-safety-protocol.md の変更安全性プロトコル（影響の宣言 → ユーザーの確認 → 編集後の検証）に従ってください。 静的ホスティングへの公開やカスタムドメインの作業を行う前には、必ず cloudbase-platform/references/protocols/deployment-gate.md のチェックを完了してください。

証拠を示さずに「実装しました」「修正しました」「動作するはずです」と述べることは認められません。完了を宣言する前に、実際にチェックを実行し、その結果を報告してください。

静的解析／ビルド層（該当する場合は常に実施）：

• tsc --noEmit（または vue-tsc --noEmit）が問題なく通ること — エラーがゼロで、追加した診断の抑制もゼロであること。
• 変更したファイルに対して eslint / プロジェクトのリンターが通ること。
• プロジェクトのビルドコマンド（npm run build / pnpm build / vite build）が、今回追加した新たな警告なしで完了すること。
• 対象箇所をカバーするユニットテストがプロジェクトにある場合、そのテストが通ること。

実行時／ブラウザー層（レンダリング、ルーティング、フォーム、認証、または非同期フローに影響する変更では必ず実施）：

• agent-browser ツールを使って実際にページを開き、ユーザーから見えるフローを再現してください。具体的な手順については browser-testing.md に従ってください。
• 次の点を確認してください。対象ルートが読み込まれること、修正したとする操作が主張どおりに動作すること、新たなコンソールエラーが発生していないこと、変更した隣接ルートにリグレッションがないこと。
• 確認した内容（ルート、操作、期待される結果、実際の結果）を記録してください。

両方の層を通過した後に限り、タスクが完了したと述べることができます。どちらかの層をローカルで実行できない場合（認証情報が使えない、バックエンドがない、有料 API であるなど）は、そのことを明確に述べ、未検証の手順を正確に列挙してください。曖昧に済ませないでください。

3. 失敗を取り繕わない

• エラーを消すために、壊れたロジックを try { ... } catch {} で囲まないでください。
• CI を通すために、失敗するテストを削除したりスキップしたりしないでください。テストを修正するか、テストが実際に間違っている理由を説明し、正当な理由を添えて変更してください。
• 「コードがコンパイルできる」ことを理由にタスクを完了扱いにしないでください。コンパイルは最低限の基準であり、目標ではありません。

このスキルを使用する場合

次のような Web エンジニアリング作業でこのスキルを使用します。

• React または Vue のページやコンポーネントを実装する
• Vite ベースのフロントエンドプロジェクトをセットアップまたは保守する
• ルーティング、データ読み込み、フォーム、ビルド設定を扱う
• ブラウザーでの検証やスモークテストを実施する
• プロジェクトで CloudBase の機能が必要な場合に、CloudBase Web SDK と静的ホスティングを統合する

次の場合は使用しないでください。

• UI の方針やビジュアルシステムの設計のみを行う場合。ui-design を使用してください
• ミニプログラムを開発する場合。miniprogram-development を使用してください
• バックエンドサービスを実装する場合。cloudrun-development または cloud-functions を使用してください

このスキルの使用方法（コーディングエージェント向け）

1. 作業対象を明確にする

   • タスクがフレームワークのセットアップ、ページの実装、デバッグ、デプロイ、検証、CloudBase の統合のどれに当たるかを確認します。
   • 関係のないバックエンドの変更にまで広げず、実際の Web アプリの作業範囲に限定します。
   • ワークスペースが TODO を含む既存のアプリケーションの場合は、新規構築ではなく、対象を絞った修正タスクとして扱います。

2. フレームワークとビルドの規約に従う

   • 既存のプロジェクトスタックがある場合は、それを優先します。
   • 新規作業では、リポジトリまたはユーザーの制約で別の指定がない限り、Vite をデフォルトのバンドラーとして扱います。
   • リポジトリですでに別の規約が使われていない限り、再利用可能なアプリコードは src に、ビルド出力は dist に配置します。
   • 構成が固定された既存のアプリケーションでは、広範なドキュメントを読む前に、処理の流れを担う既存ファイルを確認します。対象は src/lib/backend.*、src/lib/auth.*、src/lib/*service.*、ルートガード、送信ボタンに紐づくページハンドラーです。

3. コードを読むだけでなく、ブラウザーで検証する

   • 操作、ルーティング、描画、回帰の確認には、browser-testing.md の agent-browser ワークフローを使用します。
   • フロントエンドの作業完了を宣言する前に、変更した処理を対象に軽量なスモークテストを実施します。

4. CloudBase は統合が必要な場合のみ扱う

   • プロジェクトで CloudBase プラットフォームの機能が実際に必要な場合に限り、CloudBase Web SDK と静的ホスティングのガイダンスを使用します。
   • ログインやプロバイダーの準備状況については、ここで処理の流れを説明し直すのではなく、auth-tool-cloudbase と auth-web-cloudbase を再利用します。

基本的なワークフロー

1. 適切なエンジニアリングの進め方を選ぶ

• React／Vue の機能開発：アプリケーション既存のコンポーネント、ルーティング、状態管理の規約に沿って実装します
• 新しい Web アプリ：リポジトリですでに別のツールチェーンが標準化されていない限り、Vite を優先します
• デバッグと回帰対応：ブラウザーで再現し、特定のページまたは操作に絞り込んでから修正します
• CloudBase の統合：基本となるフロントエンドの進め方を明確にしてから、Web SDK、認証、データ、静的ホスティングを組み込みます

2. プロジェクトの実情に沿って実装する

• リポジトリのパッケージマネージャー、スクリプト、Lint／テストの規約に従います
• ユーザーから明示的に依頼されない限り、フレームワークの書き換えは避けます
• タスクを満たすために必要な、最小限のページ、コンポーネント、設定の変更を優先します
• TODO を含むアプリでは、並行するヘルパー、サンプルページ、独立したプロトタイプを作るのではなく、既存の実装を直接完成させます

3. 変更した処理を明示的に検証する

• 利用可能な場合は、関連するローカルのビルド／Lint／型チェック／テストコマンドを実行します。tsc --noEmit がエラーなく完了し、プロジェクトのビルドが成功することは最低条件であり、正しさの証明ではありません。
• ユーザーに見える機能（ルーティング、フォーム、描画、認証、非同期処理）では、agent-browser を使って、該当するページまたは処理をブラウザーで開きます。コードを読むだけでは十分な根拠になりません。上記のエンジニアリング憲章を参照してください。
• 確認した内容を記録します。ルート、操作、期待される結果、実際の結果、残っている問題を記載してください。

CloudBase Web 統合

このセクションは、Web プロジェクトで CloudBase プラットフォームの機能が必要な場合にのみ使用してください。

Web SDK のルール

• React、Vue、Vite などのバンドラーを使うプロジェクトでは、npm によるインストールを優先します：npm install @cloudbase/js-sdk
• CDN は、静的 HTML ページ、簡単なデモ、埋め込みスニペット、または README の例に限って使用します：https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js
• ドキュメントに記載された CloudBase Web SDK API のみを使用し、メソッドやオプションを創作しないでください
• 呼び出しごとに再初期化せず、app または auth インスタンスを共有してください
• ユーザーが環境エイリアス、ニックネーム、その他の略称のみを指定した場合は、SDK の初期化コード、コンソールリンク、設定ファイルを記述する前に、正式な完全形式の EnvId に解決してください。エイリアスのような短縮形を cloudbase.init({ env }) に直接渡さないでください。

認証の境界

• 認証には CloudBase SDK の組み込み機能を使用する必要があります
• Web のログイン処理をクラウド関数に移さないでください
• プロバイダーの利用準備、ログイン方法の設定、または公開可能キーの問題については、auth-tool-cloudbase と auth-web-cloudbase に案内してください

静的ホスティングのデフォルト設定

• デプロイ先のパスを明示してください。「静的ホスティングにデプロイする」とだけ記述しないでください。 初めてフロントエンドをデプロイする場合は manageApps({ action: "deployApp", ... }) を使用します。各アプリには専用のサブドメインが割り当てられ、バージョン履歴が保持されます（queryApps({ action: "getAppVersion" }) でリリースを一覧表示し、manageApps({ action: "deleteAppVersion" }) でリリースを削除できます）。これによりロールバックが可能になります。ホスティング（共有ドメインのパス）を通じて最初にデプロイしたプロジェクトでは、引き続き manageHosting({ action: "upload", ... }) を使用します。tcb deploy に切り替えないでください。

• デプロイ前にビルドしてください

• 静的ホスティングとの互換性を高めるため、相対アセットパスを優先してください

• プロジェクトにサーバー側のルート書き換えがない場合は、デフォルトでハッシュルーティングを使用してください

• ユーザーがルートパスを指定していない場合は、デフォルトでサイトのルートに直接デプロイしないでください

• SPA ルーティング（History モード）：React Router / Vue Router を History モード（ハッシュモードではない）で使用する場合は、CloudBase 静的ホスティングの 「404 error document」 に index.html を設定してください。そうしないと、静的ホスティングはそのパスのファイルを探し、SPA がルーティングを処理するために index.html へフォールバックしないため、再読み込みやサブルートへの直接アクセスで NoSuchKey / 404 エラーが返されます。

  MCP ツールを使って設定してください：

  manageHosting({ action: "setWebsiteDocument", indexDocument: "index.html", errorDocument: "index.html" })
  

  次に、以下を使って確認してください：

  queryHosting({ action: "websiteConfig" })
  

CloudBase クイックスタート

// npm install @cloudbase/js-sdk
import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-full-env-id", // Canonical full CloudBase environment ID resolved from queryEnv or the console
});

const auth = app.auth