> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contentcare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI エージェント連携

> Claude Code、Cursor、Codex に貼り付けるだけで、BIZ MORI API 連携に必要なすべてのルールが伝わります

## このプロンプトをコピーしてください

コピーしてエージェントに貼り付け、`<...>` の部分だけ埋めてください — サービス、スタック、実際の作業内容です。それ以外はそのままで構いません。

このプロンプトは意図的に短くしてあります。API 仕様をそのまま書き写す代わりに、エージェントが自力ではやらない3つのことだけを指示します。**コードを書く前にドキュメントを読んでリスクを報告させ**、**出荷してはいけないミスを明確に禁止し**（confirm ステップの省略、Webhook 署名の未検証、API キーのハードコーディング）、最後に**連携が実際に動作することを証明させます** — 動作すると主張するだけで終わらせないためです。

```text wrap theme={null}
BIZ MORI API を統合してください。

ドキュメント:    https://docs.contentcare.ai
全文ドキュメント: https://docs.contentcare.ai/llms-full.txt          <- ガイド全文（プレーンテキスト）
OpenAPI:      https://docs.contentcare.ai/api-reference/openapi.yaml  <- 正式なスキーマ
ベース URL:    https://api.bizmori.com
認証:         Authorization: Bearer $BIZMORI_API_KEY  （環境変数から読み込むこと。ハードコーディングやログ出力は禁止）
サービス:      <Anti-AI | Watermark Embed | Watermark Extract | AI Detection>
スタック:      <例: TypeScript + Express, Python + FastAPI>
作業内容:      <実装してほしい内容>

コードを書く前に、上記の2つのファイルを両方取得してください:
- llms-full.txt: ガイドを読むため — 該当サービスのクイックスタートに加えて、Webhook と
  エラーコードのページも読むこと。
- openapi.yaml: 正確なリクエスト/レスポンススキーマのため。ガイドにはフィールド定義が
  含まれていないので、フィールド名・型・enum 値・必須/任意の区分はすべて仕様から
  取得すること。コードサンプルだけからフィールドを推測してはならない。
その後、実装方針と、リスクや曖昧な点があれば教えてください。エンドポイント・フィールド・
パラメータを勝手に作り出さないこと — 仕様に存在しない場合は、推測せずにそう伝えること。
仕様上 deprecated と示されているエンドポイントは使用せず、指定されている代替を使うこと。

以下はドキュメントで明確に定められている項目であり、実装を誤りやすい部分でもあります。
思い込みで進めず、必ず一つずつ確認してください — これらを省略したコードを出荷しないこと:
- 注文は非同期（ASYNCHRONOUS）であり、confirm ステップはサービスごとに異なる。アップロード後に
  confirm 呼び出しが必要なサービスもあれば、confirm エンドポイント自体が存在せず、呼び出しては
  ならないサービスもある。フローを書く前に、該当サービスがどちらに当たるか確認すること。
- Webhook の署名は、生のリクエストボディ（RAW request body）に対して、定数時間（constant time）
  で検証しなければならない。
- プリサインド URL（アップロード/ダウンロード用）には有効期限があり、それを再発行するエンドポイント
  が存在する。
- 注文作成には冪等性キー（idempotency key）を指定する。リトライ時は同じキーを再利用すること。

実装が終わったら、動作すると主張するだけでなく、必ず検証すること:
1. テスト画像を使って実際にエンドツーエンドで注文を実行し、`complete` に到達することを見せること。
2. 実際に取得した結果（ダウンロードしたファイル、または detection フィールド）を見せること。
3. 自分の差分（diff）に対してハードコーディングされたキーやログに出力されたトークンがないか grep し、
   その出力を見せること。
4. Webhook レシーバーを実装した場合は、不正な署名を送信して 401 が返ることを見せること。
上記のいずれかを実行できなかった場合は、動作したと主張せず、正直にその旨を伝えること。
```

> [!NOTE]
>
> プロンプト本文はあえて英語で書かれています。コーディングエージェントは英語の
> 指示で最も安定して動作し、エンドポイント名やフィールド名と表記を一致させる
> ためです。冒頭の `My task` の項目は日本語で作業内容を書いても問題なく
> 動作します。

## エディタで使う

**Claude Code**

一回限りの作業であれば、そのままセッションに貼り付ければ十分です。

すべてのセッションで自動的に読み込ませたい場合は、プロンプトを `.claude/bizmori-api.md` として保存し、`CLAUDE.md` から import してください。

```markdown CLAUDE.md theme={null}
@.claude/bizmori-api.md
```

Claude Code は起動時に import されたファイルを読み込むため、リクエストする前にすでに指示がコンテキストへ入っています。

**Cursor**

プロジェクトルールとして保存しておくと、連携コードを触るたびに Cursor が自動的に適用します。`.cursor/rules/bizmori-api.mdc` ファイルを作成してください。

```markdown theme={null}
---
description: BIZ MORI API integration contract
globs: ["**/*bizmori*", "**/api/**"]
---

（ここにプロンプトを貼り付けてください）
```

一回限りの作業であれば、`Cmd/Ctrl + L` でチャットパネルに直接貼り付けても構いません。

**Codex / その他のエージェント**

Codex をはじめとするほとんどのコーディングエージェントは、リポジトリルートの `AGENTS.md` を読み込みます。`## BIZ MORI API` という見出しの下にプロンプトを貼り付けておけば、実行のたびに自動的に参照されます。

規約ファイルを持たないエージェントの場合は、会話の最初のメッセージとしてプロンプトを貼り付けてください。

## エージェントにライブドキュメントを渡す

上記のプロンプトが短くて済む理由はここにあります。このドキュメントは機械可読な形式でも公開されているため、エージェントはプロンプトが書かれた時点の内容ではなく、**リクエストするその瞬間の最新スペック**を自ら取得します。

| リソース | URL | 用途 |
| - | - | - |
| OpenAPI スペック | `https://docs.contentcare.ai/api-reference/openapi.yaml` | 正確なリクエスト/レスポンススキーマ — フィールド名、型、enum、必須かどうか。型付きクライアントの生成にも使用 |
| フルドキュメント | `https://docs.contentcare.ai/llms-full.txt` | ガイド全体を1つのプレーンテキストファイルに — フロー、Webhook 検証、エラーコード |
| ドキュメントインデックス | `https://docs.contentcare.ai/llms.txt` | すべてを一度に読み込ませるのではなく、必要なドキュメントだけを探させたいとき |
| 個別ページの Markdown | ページ URL の末尾に `.md` を付加 | 特定のガイド1つだけをコンテキストに入れたいとき |

> [!WARNING]
>
> どちらも必要であり、互いを代替するものではありません。`llms-full.txt` には
> ガイドは含まれますが、**フィールド定義は含まれません** — パラメータ表は
> OpenAPI スペックからレンダリングされるものであり、プレーンテキストには
> 引き継がれないためです。`llms-full.txt` だけを渡されたエージェントは、
> コードサンプルからリクエストボディを逆算し、残りは推測することになります。
> プロンプトが両方のファイルを取得させるのはこのためです。

## デプロイ前に確認すること

> [!WARNING]
>
> デプロイ前に、以下の4点は必ず確認してください。最も頻繁に発生するミスです。

> **API キーがハードコーディングされていないか**
>
> キーは必ず環境変数またはシークレットマネージャーから読み込む必要があり、
> ソースコードに直接書かれていてはいけません。差分の中で `Bearer ` や
> キーらしきリテラルを検索し、キーがログに残っていないことを確認してください。

> **サービスごとの confirm ステップが正しいか**
>
> Anti-AI（アップロードモード）と AI Detection は confirm 呼び出しが必要です。
> Watermark Embed と Watermark Extract は不要で、呼び出すと失敗します。
> Anti-AI を URL モードのみで使う場合も confirm は呼び出しません。

> **Webhook 署名を raw body で検証しているか**
>
> HMAC は元のリクエストバイト列（raw body）で計算する必要があります。
> JSON パーサーが先に実行され、オブジェクトを再シリアライズすると署名が
> 一致しなくなり、エージェントが検証をスキップする形で「修正」しようと
> することがあります。比較は必ず定数時間（constant-time）で行う必要が
> あります。

> **Presigned URL の期限切れを処理しているか**
>
> アップロード用 URL は1時間、[v3 のダウンロード用 URL](https://docs.contentcare.ai/ja/api-reference/orders/download-order-v3.md) は最大1時間
> 有効です。時間のかかるバッチ処理の場合、期限切れのアップロード用 URL を再利用せず、
> [URL 再発行](https://docs.contentcare.ai/ja/api-reference/orders/refresh-urls.md)エンドポイントを呼び出し、
> ダウンロード用 URL はダウンロードの直前に改めてリクエストする必要があります。

## 次のステップ

> **[クイックスタート](https://docs.contentcare.ai/ja/quickstart.md)**
>
> 自動化する前に、まず自分の手でフローを一通り試してみましょう。

> **[API リファレンス](https://docs.contentcare.ai/ja/api-reference/introduction.md)**
>
> すべてのエンドポイントの基準となるスペックです。

> **[Webhook](https://docs.contentcare.ai/ja/webhooks.md)**
>
> 署名検証とイベントペイロードの詳細な説明です。

> **[エラーコード](https://docs.contentcare.ai/ja/errors.md)**
>
> エージェントのエラー処理がカバーすべきすべてのコードです。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.