putio-frontend-dev

put.io フロントエンド開発

対象リポジトリ固有のガイダンスとコードの前例に従ったうえで、put.io 共通のフロントエンドエンジニアリングのデフォルトを適用します。

はじめに

1. git ls-files '*AGENTS.md' '*SKILL.md' を使ってネストされたガイダンスを一覧表示し、変更対象の領域に関する README.md とドキュメントを読みます。対象リポジトリのガイダンス、プロジェクト固有のスキル、コードの前例が、このスキルより優先されます。
2. リポジトリの種類、技術スタック、検証のエントリーポイント、デリバリー対象、実行時の検証手段を特定します。
3. タスクに必要な参照資料だけを選びます。

参照資料の一覧

• 機能コード、解析、状態、エラー、フォーム、スタイル設定、テスト： フロントエンドのデフォルト
• README、CONTRIBUTING、セキュリティ報告、エージェント向けドキュメント： トップレベルのドキュメント
• パッケージとアプリの CI、検証、公開、デプロイ、リリースの形態： デリバリーモデル
• TypeScript のパッケージとアプリのセットアップ： TypeScript のデフォルト
• マシンツール、ピアクローン、エージェントのワークツリー、準備状況の確認： 環境のセットアップ
• ローカル開発用シークレットと CI の認証情報の境界： シークレット
• シークレットを扱うリリース、署名、公開、デプロイ： リリースのセキュリティ
• ブラウザー、ネイティブ、TV、エミュレーター、シミュレーター、デバイスでの検証： テストハーネス
• 共有テストアカウントでのブラウザー認証： テストハーネスのパターン
• CLI を利用したハーネスの検出、認証、読み取り、書き込み： CLI ハーネスの仕様

Markdown のリンクは、このスキルバンドル内を移動します。参照資料に示されているその他のパス（.github/pull_request_template.md など）は、対象リポジトリで作成または確認するファイルを指します。

リポジトリ

• repos.json には put.io のリポジトリが記載されています。フロントエンドが所有するエントリーでは、owns に frontend が含まれています。
• フィールドの説明：name はローカルフォルダー、repo は GitHub リモート、path は標準のチェックアウト先、owns は担当チーム、visibility はドキュメントの公開範囲、topics は GitHub のトピック一覧（任意）、mode はチームのワークスペースツールがチェックアウトを管理するかどうかを示します。
• owns に複数のチームが記載されたエントリーは共有リポジトリです。putdotio/.github ではフロントエンド関連の作業は frontend-* ワークフロー内に、putdotio/agent-skills では putio-* スキル内にとどめます。
• ピアリポジトリは既定で ~/projects/putdotio/ の下に配置します。パスが存在しない場合は、gh repo clone <repo> <path> を実行するか、環境のセットアップにあるクローンループを使います。
• リポジトリをまたいで何かを引用する前に visibility を確認します。非公開の内容を公開リポジトリに含めないでください。
• フロントエンドの全リポジトリにまたがるタスクでは、owns に frontend を含むエントリーを順に処理します。ただし、タスクが SDK を対象とする場合を除き、sdks グループは対象外にします。各リポジトリのルートに移動し、その AGENTS.md を読み、独自の検証を実行します。

ナレッジベース

• put.io の Notion ワークスペースにあります。フロントエンドハブから、Notion MCP を使って読み取ります。
• Products、Specs、Design、Services、Delivery （デリバリーモデル、 リリースのセキュリティ、 シークレット管理）、 Decisions、Analytics、Guides が含まれています。
• 製品、仕様、リリース、シークレットに関する判断の前に読みます。
• 編集するのは Frontend のページだけです。タスクで指示されていない限り、共有データベース内の ops ガイドを含め、他のチームのページには手を加えないでください。

共通のデフォルト

• 外部入力は境界で解析し、検証済みの契約から型を導出します。
• バグの影響を受けやすいフローは、明示的な状態と網羅的な遷移でモデル化します。
• 想定されるエラーは型付けして対処可能にし、予期しないエラーの影響を限定して、無関係な UI を空白にしないようにします。
• エフェクトはアダプターと末端に置き、レンダーツリーを純粋に保ちます。
• 契約を弱める型の抜け道は避けます。
• ユーザー名、パスワード、現在有効なワンタイムパスワードコードは、公式の put.io ウェブサイトでのみ受け付けます。長期間有効な TOTP シードは、現在のコードを生成する認可済みのシークレットプロバイダー内に保持します。CLI、モバイル、TV、拡張機能、ハーネスなどのクライアントは、OAuth またはデバイスリンクフローを通じてアカウント認証をウェブサイトに委任し、結果として得られるコードまたはトークンのみを扱う必要があります。
• ビルド、検証、デプロイ、スモークテストのロジックは、CI が呼び出すリポジトリ管理のコマンドに置き、ワークフロー YAML は薄く保ちます。確立済みのタスクグラフを維持し、新しいレーンを作成する場合は、単一の verify エントリーポイントを使用します。
• 検証完了後に限り、信頼された main または検証済みのリリース参照からデリバリーします。
• main へのマージまたはプッシュはデリバリーであり、CI がそこから開始するデプロイや公開も含まれます。手動でのデプロイまたは公開の実行、シークレットやプロバイダーの変更、リポジトリの Forge 外部（ストア、プロバイダーのコンソール、共有アカウント）への書き込み、フォースプッシュの前には確認を求めます。
• プルリクエストの本文は、変更内容に見合うだけの短さにします。結果、実際のリスク、未検証のまま残った内容を記載します。各本文には文章ではなく、視覚的な補助資料を含めます。UI にはレビュー済みのスクリーンショットまたは短い録画、フローには Mermaid 図、数値には表、API には短いコードサンプルを使用します。テスト件数、コマンドログ、レビュー履歴は記載しません。
• 一見して分かりにくいコード規約は最も近い AGENTS.md に記録し、ユーザー向け、コントリビューター向け、配布向け、セキュリティ関連のドキュメントは、それぞれの正式な配置場所に置きます。

検証

• 影響を受ける動作とその依存先について、所有者が文書化したチェックを選択します。所有者のポリシーで求められる場合、共有入力が変更された場合、または対象を絞ったカバレッジに確信が持てない場合は、正式なゲートをすべて実行します。境界が重要な場合は、インストール済みパッケージ、下流の利用者、ブラウザー、デバイスについて、それぞれ個別に検証します。
• 実際のブラウザー、アプリ、シミュレーター、エミュレーター、またはデバイスの画面がある場合は、ユーザーに見える動作をそこで確認します。
• UI 作業を完了とする前に、初回ロード、読み込み中、エラー、空の各状態、小さな画面、選択、フォーカス、ハイドレーション、競合などのインタラクション状態を確認します。何が問題に見えるかをユーザーに尋ねるのではなく、自分で結果を確認します。
• ソース、入力、環境が有効な間は、合格済みの検証結果を再利用します。新しいターンや引き継ぎがあっただけでは、再実行は必要ありません。実行できない検証と、その具体的な阻害要因を明記します。コマンドを調べても、実環境での操作が許可されたことにはなりません。
• 検証コマンドでランタイムを起動する前に、クリーンアップ処理を設定し、対象そのものが起動したかどうかを記録します。終了時には必ず、自身が起動した対象だけを停止し、その対象が存在しないことを確認します。既存の対象は維持します。

境界

• SDK リポジトリは、ドキュメント、検証、リリース、デリバリーの手順を含め、専用の SDK 開発ワークフローに従います。
• putio CLI をファイル、ダウンロード、転送、認証、ストレージの利用者として操作する場合は、CLI の利用者向けガイダンスに従います。フロントエンドのハーネスでは、インストール済み CLI を CLI harness contract に従って使用します。
• リポジトリのポリシー、汎用的な GitHub Actions の強化、ビルドツールの移行、起動可能性の修復、独立したコードレビューはこのスキルの対象外です。このスキルは、これらの作業を行う各ワークフローに put.io フロントエンドのドメインガイダンスを提供します。
• マシン固有の情報、認証情報、アカウントの詳細、非公開のサポート情報は、この公開スキルに含めないでください。リポジトリレジストリには、名前、リモート、正式なパス、所有者、公開範囲、トピック、モードのみを記載します。