putio-sdk-dev

put.io SDK の開発

対象リポジトリ固有のガイダンスを適用した後、put.io SDK の規約に従ってください。

共通のデフォルト

• 各 SDK は内部向けの互換レイヤーではなく、公開パッケージとして扱ってください。
• TypeScript は、最も機能が豊富なリファレンスにとどまらず、put.io API 全体に対応する標準クライアントとして扱ってください。
• すべての公開インターフェースを、ドメインを中心とした、強い型付けでホスト言語になじむ設計にしてください。
• リクエスト、レスポンス、型付きエラーの各コントラクトをまとめて更新してください。
• 決定性のあるテストに加え、実際の API の挙動が重要な場合は安全なライブテストで動作を検証してください。
• 製品での利用が正当化される場合に限り、Swift と Kotlin の対象範囲を TypeScript より狭くしてください。

情報源の優先順位

情報源の内容が食い違う場合は、ローカルのバックエンドの挙動とテスト、現行のファーストパーティアプリでの利用、保守されている SDK、アーカイブ済みクライアント、公開済み API ドキュメントの順に優先してください。

まず対象リポジトリ内にある情報源を確認してください。バックエンドやファーストパーティの利用者に関する情報は、権限があり、利用可能な場合に限って追加してください。

実際のアプリでの利用と検証済みのバックエンドの挙動によって正当化される場合に限り、SDK のインターフェースを拡張してください。

開始

必要なものだけを確認してください。

• git ls-files '*AGENTS.md' '*SKILL.md' でネストされたガイダンスを確認します。
• README.md、AGENTS.md、または docs/* で標準の検証コマンドとライブテストコマンドを確認します。
• スコープのルール、共通のエンジニアリング原則、検証ポリシーについてはSDK のビジョンを確認してください。製品の方向性は、put.io の Notion ワークスペースにある Frontend ハブ（ページ：Products）に記載されています。
• 型付き境界、エラーのマッピング、ページネーション、ライブテストの構成についてはパターンを確認してください。
• TypeScript、Swift、Kotlin 固有のガイダンスについては言語別の注意事項を確認してください。
• 公開、署名、リリース、または配布可能なバイナリのビルドを行う場合は、リリースのセキュリティを確認してください。

対象リポジトリのガイダンス、リポジトリ内の該当するスキル、リポジトリ標準の検証コマンド、および配布やサプライチェーンのポリシーは、この共通スキルより優先されます。

ワークフロー

1. 対象の名前空間と、共通のトランスポートまたはクライアントランタイムを調べます。
2. コントラクトを拡張または変更する前に、バックエンドの挙動、バックエンドのテスト、現行アプリでの利用を確認します。
3. 型付きリクエスト入力、レスポンスの解析、操作固有のエラーマッピングをまとめて更新します。
4. リクエストの構成、解析、エラー、公開クライアントのコントラクトを対象とする、決定性のあるテストを追加または更新します。
5. 本番環境での挙動が重要で、かつインターフェースを元に戻せる場合は、安全なライブ検証を追加または更新します。
6. リポジトリが複数のインターフェース形式を公開している場合は、複数の公開クライアント間で整合性を保ちます。
7. 影響を受けるコントラクトとその依存先について、所有者がドキュメントに記載したチェックを実行します。該当する場合は、インストール済みパッケージと下流の利用者による検証も含めてください。必須の場合、共通の入力が変更された場合、または対象を絞ったテストで十分に確認できない場合は、標準の全チェックを実行します。
8. 公開インターフェースを変更した場合は、パッケージ向けドキュメントとリリースノートを更新します。

エンドポイントの変更

エンドポイントを新規追加または変更する場合は、まず追跡対象のソース、テスト、フィクスチャ、利用者に関するパスを特定してください。存在するパスだけを検索します。

git ls-files -z -- \
  ':(glob)**/src/**' \
  ':(glob)**/test/**' \
  ':(glob)**/tests/**' \
  ':(glob)**/Tests/**' \
  ':(glob)**/Sources/**' \
  ':(glob)**/docs/**' \
  ':(glob)**/fixtures/**' \
  ':(glob)**/Package.swift' \
  ':(glob)**/build.gradle' \
  ':(glob)**/package.json' |
  xargs -0 rg -n "route_name|endpoint_path|field_name" -- || true

バックエンド、フィクスチャ、またはファーストパーティの利用者のチェックアウトから同じ検索を繰り返すのは、その情報源が利用可能で、かつ権限がある場合に限ります。

次に、以下の順序で SDK を更新します。

1. リクエスト入力の型またはクエリモデル
2. レスポンスパーサーまたはネイティブのデコードモデル
3. 操作固有のエラーマッピング
4. 公開クライアントのメソッドまたは名前空間のエクスポート
5. リクエスト、レスポンス、エラーの挙動を対象とするユニットテスト
6. エンドポイントの挙動をローカルで検証できない場合の安全なライブテスト
7. 公開インターフェースを変更した場合の README、API ドキュメント、リリースノート

検証

対象リポジトリで文書化されているコマンドを使用してください。この共通スキルを根拠に、Vite+、Gradle、または Make のエントリーポイントを推測してはいけません。

SDK リポジトリには、次の両方を用意する必要があります。

• CI とローカルでの反復作業に安全な、デフォルトの決定的なユニットテストの実行方法
• 実際の API を検証する、別途文書化されたライブテストの実行方法

いずれかのレイヤーが欠けている場合は、より弱い検証方法を黙って受け入れるのではなく、文書化または修正すべきリポジトリの課題として扱ってください。

ランタイムを検証する際は、リポジトリで文書化されているライブテストのエントリーポイントを優先し、そのリポジトリのテストドキュメントに記載された共有アカウントの安全ルールに従ってください。

境界

• 古い SDK だけに頼らず、最新のドキュメント、ソースコード、フィクスチャ、またはライブプローブを使ってバックエンドの契約を検証してください。
• 変更に関係するユニット、フィクスチャ、ライブの各レイヤーを実行した場合にのみ、検証を完全に行ったと主張してください。
• 共有アカウントを使ったライブテストのカバレッジは、非破壊的なものにしてください。
• main へのマージは、そこから開始されるリリース CI を含め、デリバリーに当たります。公開、手動でのリリース作成、カバレッジしきい値の変更、元に戻せないライブ書き込みを行う前に、確認してください。
• 文書化された理由が変更を正当化しない限り、命名、パリティ、型安全性を維持してください。
• リポジトリ固有の実装ガイダンスは、そのリポジトリの AGENTS.md または docs/* に記載してください。
• 一般的な SDK 作業、エンドユーザー向けアプリケーションコード、CLI を利用する側の操作は、このスキルの対象外です。