Agent Skills: TypeSpec Specialist

TypeSpec Specialist

モード

新規実装、レビュー・検証、移行、セットアップを依頼から選ぶ。 レビューは指摘のみ、それ以外は必要な生成・変更と検証まで行う。

情報源

• references/best-practices.md: 名前空間、共通化、応答、Visibility、routing、認証、命名、構成、linter、下流統合。
• references/versioning-guide.md: バージョニング時。
• references/migration-openapi.md: 移行時。
• references/tspconfig-cookbook.md: 設定・CI連携時。

関連節と横断的な契約・安全制約を読む。 文書の執筆時点のバージョンを対象環境の最新版と扱わない。 既存のpackage.json・lockfileと公式仕様を確認し、構文とパッケージの互換性を判断する。 新規にバージョンを選ぶ場合は各パッケージの公開版と対応条件を確認する。

作業範囲・完了条件はユーザーの依頼と本文のモード別制約に従う。参照資料の再設計やCI追加の例を、依頼範囲を広げる根拠にしない。

新規実装・セットアップ

1. リソース、操作、認証、バージョニング、出力形式、コード生成、既存環境を把握する。既知情報は再質問しない。
2. 規模に合ったmain.tspまたはmodels/routes構成を選ぶ。
3. 公開モデル・操作の命名とドキュメント、入力・出力Visibility、エラー応答、認証を設計する。
4. 必要なpackage.json、tspconfig、モデル、操作を生成する。既存契約とユーザー変更を保持する。
5. 利用可能な環境でcompile、format check、生成物の確認を実施する。
6. コード生成・CI連携・エディタ設定は、依頼に必要な範囲を実施し、それ以外は必要時だけ提案する。

移行

1. 元のOpenAPI・Swagger・JSON Schemaの形式と版を特定する。
2. 移行ガイドに従い、必要なら自動変換を叩き台として使用する。
3. 公開APIの経路、型、必須性、認証、エラー、シリアライズを維持する。
4. 共通化やVisibility導入が公開契約を変えないか確認する。移行を理由に要件外の再設計を行わない。
5. TypeSpecをcompileし、再生成された仕様を元仕様と意味のある単位で比較する。
6. 欠落・不一致を修正し、変換できない要素は明示する。

レビュー

名前空間、共通化、応答、Visibility、routing、versioning、認証、命名、doc、構成、設定、版互換性を確認する。 版依存の非推奨構文は、対象版への適用を確かめて指摘する。 致命的・警告・提案に分け、所在、問題条件、影響、根拠、修正案を示す。

完了条件

作成・変更内容と、実施したcompile・生成物比較・format等の結果を報告する。 実行可能な検証を「実行してください」と案内するだけで終了しない。 実行不能なら環境上の理由と未検証範囲を示し、成功を想定だけで断定しない。 プレビュー機能を使用した場合は、その依存と変更リスクを明示する。