cap-developer

このスキルで行うこと

プロジェクトのセットアップや CDS モデリングから、宣言的アノテーションやプログラムによるイベントハンドラーまで、CAP 開発のための正確で簡潔かつ慣用的なガイダンスを提供します。

この SKILL.md はルーターです。各トピックは独立した参照ファイルに記載されており、それぞれ単独で読み込み、相互参照できます。タスクに必要なファイルだけを読んでください。

参照ファイル一覧

トピック	ファイル	読み込むタイミング
ドメインモデルとサービスプロジェクション	references/cds-modeling.md	エンティティ、アスペクト、アソシエーションをモデリングするとき、またはプロジェクションを通じて公開するとき
宣言的アノテーション（検証、制約、認可）	references/declarative.md	検証、必須／読み取り専用／計算値、@restrict／@requires を追加するとき
カスタムイベントハンドラー	references/custom-logic.md	アノテーションではルールを表現できない場合に限り、before／on／after のロジックを追加するとき
サンプルデータ／シードデータ	references/sample-data.md	CLI でテストデータを生成するとき
Node.js ランタイム固有の情報	references/nodejs.md	プロジェクトが CAP Node.js アプリの場合
Java ランタイム固有の情報	references/java.md	プロジェクトが CAP Java アプリの場合

ランタイムの選択

新しいプロジェクトでは、グローバルにインストールされた @sap/cds-dk（CLI：cds）を使用します。 必要になるまで言語の選択は保留してください。 この選択が必要になるのは、コードを追加するとき、またはアプリをデプロイするときだけです。

CDS モデルのみを扱う場合は、ランタイムを定義せずに cds w で開始できます。

ドキュメントの参照元

API やアノテーションを推測する前、また既存プロジェクトのモデルを変更する前に、信頼できる CAP ドキュメントを参照してください。利用可能なソースを使用し、URL を推測したり、API を作り出したりしないでください。

• CAP MCP サーバー（利用可能な場合は優先）。 次の用途に使用します。
  • API やアノテーションを推測する前に CAP ドキュメントを検索する
  • 既存プロジェクトに何かを追加または変更する前に、有効な CDS モデルを読み取る
• capire LLM ドキュメント（MCP サーバーが設定されていない場合の代替手段）。 公式ドキュメントには LLM に適したエントリーポイントが用意されています。場当たり的なウェブ検索ではなく、これらを使用してください。
  • https://cap.cloud.sap/docs/llms.txt — すべてのドキュメントページをまとめた索引です。適切なトピックを探すには、ここから始めてください。
  • https://cap.cloud.sap/docs/llms-full.txt — ドキュメント全体を連結したファイルです。全文が必要な場合に使用してください。
  • https://cap.cloud.sap/docs/sitemap.md — 全ページの意味的なサイトマップです。
  • URL の末尾に .md を追加すれば、任意のページを Markdown として取得できます（例：https://cap.cloud.sap/docs/get-started/bookshop.md）。または Accept: text/markdown ヘッダーを送信してください。パスを推測するのではなく、llms.txt／sitemap.md のリンクから該当するページに移動してください。
  • MCP サーバーなしで有効な CDS モデルを確認するには、cds compile <path> を使用します（例：cds compile srv --to edmx）。

CAP ドキュメントを Fiori／SAPUI5 のリファレンスとして使用しないでください。CAP と Fiori／SAPUI5 の連携に関する有用な情報は含まれていますが、これらのフレームワークの完全なリファレンスではありません。

リリースノートとバージョン表に関する注意： リリースノートやバージョン推奨表に基づくドキュメントの情報は、古くなっている可能性があります。そこに記載されているのは、必ずしも現在の状況ではなく、そのリリース時点での情報です。バージョン固有の主張（例：「推奨 Node.js バージョン」）は、過去のリリースノートの記録をそのまま信頼せず、cds version、npm view、最新の Getting Started ページなど、最新の情報源で必ず確認してください。

プロジェクトのセットアップ規則

新しいプロジェクトは、次のコマンドで開始します。

cds init <name>        # creates a subdirectory; omit <name> to init in cwd
cd <name>
cds watch              # start the dev loop (works without a runtime for pure modeling)

ランタイムがあらかじめ決まっている場合は、cds init に --java または --nodejs を渡してください（詳細はランタイム固有の参照ファイルを参照）。

• cds add sample は絶対に実行しないでください。プロジェクトに完全なデモアプリが生成されます。
• ユーザーが最小限のスターターモデルを明示的に求めた場合に限り、cds add tiny-sample を使用してください。
• cds add <feature>（例：hana、xsuaa、approuter、mta）で機能を段階的に追加してください。必要な場合（例：デプロイを求められた場合）にのみ追加します。

作業順序

1. ドメインをモデル化する → references/cds-modeling.md
2. プロジェクションを介してサービスを公開する → references/cds-modeling.md
3. まず宣言的に制約を追加する → references/declarative.md
4. アノテーションで対応できない場合に限りハンドラーを記述する → references/custom-logic.md （およびランタイムファイル references/nodejs.md または references/java.md）
5. サンプルデータを生成する → references/sample-data.md

やってはいけないこと

• 汎用サービスプロバイダーがすでに処理する機能について、ハンドラーを記述しないでください
• テナント ID、システム ID、認証情報をどこにもハードコードしないでください
• ユーザーに表示する文字列をインラインで記述せず、_i18n/ バンドルを使用してください
• cds add sample を実行しないでください

ランタイム固有の禁止事項（例：Node で cds.on('served', ...) の内部に await を記述すること）は、該当するリファレンスファイルに記載されています。