add-resource

リソースの追加

最初にルールを読み込んでください。 .plain ファイルを読んだり、編集したり、書き込んだりする前に、load-plain-reference スキルを呼び出し、そこから案内されるルールファイルを読んでください。この会話ですでに load-plain-reference が実行されている場合に限り、この手順を省略できます。

リンクされたリソースとは、.plain 仕様内で Markdown リンク構文を使って参照される外部ファイルです。ファイルの内容は仕様とともにレンダラーに渡され、コード生成に追加のコンテキストを提供します。

ワークフロー

1. リソースファイルを特定するか、作成します。 プロジェクト内に配置してください。慣例的な場所は resources/ ディレクトリですが、.plain ファイルと同じ場所である必要はありません。
2. 仕様の適切な箇所に Markdown リンクを追加します。
3. ファイルパスが .plain ファイルの場所からの相対パスであることを確認します。
4. ファイルを読み直し、リンク構文とパスが正しいことを確認します。

形式

仕様内の任意のセクションで、標準的な Markdown リンク構文を使用します。

***definitions***
- :AuthData: is the authentication data structure.
  - Its format is defined in the [auth schema](resources/auth_schema.json).

***implementation reqs***
- When transforming :BackupData:, use the JOLT transform.
  - The transform is defined in [backup_transform.jolt](resources/backup_transform.jolt).

***functional specs***

# expose-api
An API conforming to the [API specification](resources/api_spec.yaml) is exposed.

パスのルール

• パスは、レンダラーの実行場所ではなく、レンダラーに渡された .plain ファイルを含むディレクトリを基準に解決されます。
• インポートされたモジュールや必須モジュール内のリンクも同様です。リンクは、そのモジュール自体が置かれているディレクトリではなく、同じディレクトリを基準に解決されます。
• その場所で解決できないパスは、次に（設定されている場合）template-dir ディレクトリで検索され、最後にレンダラー組み込みのテンプレートライブラリで検索されます。
• 相対パスは親ディレクトリをたどってもかまいません。実際にディスク上に存在するテキストファイルに解決される限り、[resource](../../resources/resource.md) は有効です。
• 外部 URL は使用できません。ローカルファイルのみを参照してください。
• フォルダーパスは使用できません。参照先はディレクトリではなくファイルである必要があります。
• テキストベースのファイルのみサポートされています。

リンク先のリソースは、ディスク上に存在する単一のテキストファイルでなければなりません

リンク先のリソースは、必ず参照先のパスにディスク上で存在する単一のファイルであり、かつそのファイルの内容はテキスト形式でなければなりません。レンダラーはリンク先ファイルのバイト列を読み取り、仕様とともにモデルに渡します。ディレクトリ、リモート URL、バイナリデータはこの前提を崩します。これは .plain ファイルの作成時に起こり得る、最も深刻なミスのひとつです。仕様自体は有効に見えても、レンダラーがリンクを無視したり、ファイルを読み込めなかったり、解釈できないバイト列にモデルのコンテキストウィンドウを浪費したりします。

リンク先のリソースにしてはならないものは、次の3つです。

1. フォルダー／ディレクトリ。 [integrations](src/integrations/)、[schemas](resources/schemas/)、[host project](../host_project/) はすべて無効です。レンダラーはディレクトリを取り込めません。ディレクトリ内のコンテンツ全体が関連する場合は、その中で最も代表的な単一のファイル（README.md、サンプルのソースファイル、ディレクトリ直下のマニフェストなど）を選び、そのファイルにリンクしてください。
2. URL／外部の場所。 [Stripe docs](https://stripe.com/docs/api)、[OpenAPI spec](https://example.com/openapi.json)、および http://／https://／ftp://／git://／s3://／gs:// を含むリンク先はすべて該当します。リンク先のリソースにできるのはローカルファイルのみです。URLの内容が仕様に不可欠な場合は、一度取得してレスポンスを resources/ 配下のテキストファイル（例：resources/stripe-docs-snapshot.md、resources/example-openapi.yaml）に保存し、そのファイルにリンクしてください。
3. バイナリファイル。 PNG、JPG、JPEG、GIF、BMP、TIFF、WebP、ICO、PDF、DOCX、XLSX、PPTX、ZIP、TAR、GZ、MP3、MP4、WAV、コンパイル済みバイナリ（.exe、.so、.dylib、.class、.wasm）、およびそれ以外の生データを人が読めるテキストとして解釈できないファイルが該当します。バイナリの内容はレンダラーが有意義に処理できません。スクリーンショット、PDF仕様書、パッケージ化された成果物にリンクしても、コンテキストが膨らむだけで何の役にも立ちません。バイナリアセットの情報が不可欠な場合は、まずテキスト形式に書き起こしてください。たとえば、UIのスクリーンショットは Markdown の説明文または resources/ 配下の構造化された YAML ワイヤーフレームに、PDF仕様書は Markdown の抜粋または元の JSON Schema／OpenAPI に、アーキテクチャ図は Markdown ファイル内の Mermaid ブロックに変換します。

Markdownリンクのリンク先が / で終わる場合、:// を含む場合、ディレクトリを指す場合、またはバイナリ拡張子（上記の一覧を参照）のファイルを指す場合は、処理を中止してください。リンク先のリソースにはできません。まず resources/ 配下のテキストファイルに変換してから、その変換後のファイルにリンクしてください。

.plain コンテンツには URL やフォルダーパスを記載しないでください

上記の制約は、Markdown のリンク構文だけに関するものではありません。URL（http://、https://、ftp://、git://、s3:// などの文字列）やフォルダーパス（src/integrations/、../host_project/、末尾が / のもの、ディレクトリを指すもの）は、リンク先としてだけでなく、コンセプトの本文、機能仕様のテキスト、実装要件など、.plain コンテンツ内のどこにも記載してはいけません。URL やフォルダーを文章に記載するのは、よくある重大な間違いです。その理由は次のとおりです。

• レンダラーは URL をたどったり、フォルダーを開いたりできません。文章中の URL やフォルダー参照は、見た目には意味があるようでもコード生成には何の役にも立たない、幽霊のような依存関係です。さらに、後続の読者（そして将来の自分）は、レンダラーが参照先のコンテンツを使ったと思い込み、仕様と実態にずれが生じます。
• 解決方法は常に同じです。外部のコンテンツが必要なら、それを取得する（またはディレクトリから代表となるファイルを1つ選ぶ）か、resources/ の下にテキストファイルとして保存し、通常のリンク済みリソースとして参照します。コンセプトや仕様では、URL やフォルダーパスの文字列ではなく、リンクされたファイルを通じてコンテンツを示します。

唯一の例外は、生成されるソフトウェアが実行時に値として使用する URL やパスです（例：インテグレーションが呼び出すベース URL、データベース接続パス、CLI 引数の値）。これらは外部参照ではなく設定値なので、生成コードに必要な情報として仕様に含めます。判断の目安は、「レンダラーはこの URL やフォルダー内のデータを読み取ることで役に立つか」です。答えが「はい」なら、テキストファイルとして保存してそのファイルをリンクします。「いいえ」（実行時の値である）なら、仕様内にテキストとして記載できます。

リンク済みリソースとして使用できるもの

• プロジェクト内にある単一のファイル。.plain ファイルからの相対パスで指定できます（親ディレクトリへの移動（../）も可能です。一般的には resources/ を使用します）。
• レンダラーが全体を読み取れるテキストベースのファイル。JSON、YAML、XML、HTML、Markdown、プレーンテキスト、CSV、TSV、各種言語のソースコード（.py、.js、.ts、.go、.java、.rb、.rs、.kt、.swift、.c、.cpp、.cs など）、シェルスクリプト、SQL、JSON Schema、OpenAPI、AsyncAPI、Protobuf の .proto、GraphQL SDL、.jolt、.env.example、.toml、.ini、.proto、Dockerfile など。

よくあるリソースの種類

種類	一般的な配置場所	用途
JSON Schema	resources/*.json	データ構造の契約の定義
OpenAPI / Swagger 仕様	resources/*.yaml	API エンドポイントの定義
データ変換	resources/*.jolt	データ変換ルール
テストフィクスチャ	resources/*.json、resources/*.csv	テスト用のサンプルデータ
設定例	resources/*.yaml	参照用の設定

リソースを使用する場合

• 情報が細かすぎる、または構造が複雑すぎて仕様の本文に記載できない場合（例：完全な JSON Schema）。
• 同じデータを複数の仕様やセクションで参照する場合。
• リソースが業界標準の形式（OpenAPI、JSON Schema）で、レンダラーが直接解釈できる場合。

リソースを使用しない場合

• 情報が短く、仕様の本文に記載できる場合。
• ファイルが生成コードである場合（それらは resources/ ではなく plain_modules/ に配置します）。

検証チェックリスト

• リソースファイルが指定されたパスに存在する
• 対象はディレクトリではなく、ディスク上のファイルである（パスが / で終わらず、フォルダーとして解決されない）
• 対象は URL ではなくローカルパスである（対象に :// が含まれない。http://、https://、ftp://、git://、s3://、gs:// なども含まない）
• 対象はテキストベースのファイルである（.png、.jpg、.jpeg、.gif、.bmp、.tiff、.webp、.ico、.pdf、.docx、.xlsx、.pptx、.zip、.tar、.gz、.mp3、.mp4、.wav、.exe、.so、.dylib、.class、.wasm などのバイナリ拡張子ではない）
• 周囲の .plain コンテンツに URL やフォルダーパスが含まれていない（リンク先にも本文にも含まれない）。ただし、生成されたソフトウェアが実行時の値として使用する URL／パスは除く
• パスは絶対パスではなく、.plain ファイルからの相対パスである
• パスは .plain ファイルを基準とした実在するテキストファイルに解決される（../ による遡りは許可される）
• Markdown のリンク構文が正しい：[表示テキスト](relative/path)
• リソースの内容が関連性を持ち、仕様の記述を超える価値を追加している