# AIと一緒に開発する

KOS Developersは、人間が読むドキュメントとAIエージェントが読みやすいドキュメントの両方を提供します。AIを使う場合は、全ドキュメントを最初から一括で取得させるのではなく、まずドキュメントマップを読み、必要なページだけを確認させてください。

## 推奨方法

AIエージェントがskillのインストールに対応している場合は、次のコマンドでKOS Developers skillsを追加します。

```sh
npx skills add https://developers.kos-solution.com
```

インストール可能かだけ確認する場合は、次のように一覧を確認できます。

```sh
npx skills add https://developers.kos-solution.com --list
```

追加されるskillは3つです。共通skillは言語とプロダクト経路を選び、OpenAPI skillはAPI契約と認証を確認し、KOS Connect skillはウィジェット導入、appId、クライアント制約を確認します。これらのskillはAPIを代わりに呼び出すツールではなく、`llms.txt`、個別のMarkdown文書、必要に応じて`openapi.yaml`を確認させるためのドキュメント探索手順です。

## skillをインストールできない場合

AIには次の順序でドキュメントを読ませてください。

1. まず`/ja/skill.md`または`/ja/.well-known/agent-skills/kos-developers/SKILL.md`を読みます。
2. ユーザーの言語に合う`llms.txt`を読みます。
3. `llms.txt`の索引から必要なMarkdownページだけを取得します。
4. OpenAPIの正確なリクエスト、レスポンス、schema、error variantが必要な場合だけ`openapi.yaml`を追加で確認します。
5. 複数文書にまたがる検索が本当に必要な場合だけ`docs.zip`を使います。すでに取得済みのファイルがある場合は、`docs-manifest.json`または`docs.zip.sha256`を比較し、変更がある場合だけ再取得してください。

| 目的 | パス |
| --- | --- |
| 全体ドキュメントマップ | `/llms.txt` |
| 日本語ドキュメントマップ | `/ja/llms.txt` |
| 英語ドキュメントマップ | `/en/llms.txt` |
| 共通skill | `/ja/skill.md` |
| OpenAPI skill | `/ja/.well-known/agent-skills/kos-openapi/SKILL.md` |
| KOS Connect skill | `/ja/.well-known/agent-skills/kos-connect/SKILL.md` |
| skill discovery | `/ja/.well-known/agent-skills/index.json` |
| OpenAPI原本仕様 | `/ja/openapi.yaml` |

## 先にプロダクト経路を選ぶ

AIが良い回答をするには、まずどのプロダクト経路かを判断する必要があります。

| 経路 | 選択基準 |
| --- | --- |
| KOS Connect | クリニックサイト、キャンペーンページ、LINEに完成済みの予約導線を組み込む場合に使います。npmパッケージ、Scriptタグ、ウィジェットを開く、予約開始、言語変更、GA4/GTMイベントの質問はこの経路です。 |
| OpenAPI | KOSデータを直接取得し、自社UIとサーバーフローを実装する場合に使います。商品、カテゴリ、オプション、価格、予約枠、予約作成、患者、会計データ、リクエスト/レスポンス、error、schemaの質問はこの経路です。 |
| ガイド | 初めて連携方針を決める時や、商品メニュー、予約フローのように複数APIを組み合わせる時に先に使います。 |

外部開発会社がクリニックサイトやキャンペーンページのボタン、ウィジェット、LINE予約導線だけを組み込む場合は、通常KOS Connectから始めます。自社画面とサーバーでKOSデータを取得したり、予約/会計フローを直接実装したりする場合はOpenAPIです。この場合は、KOSを利用するクリニック、またはそのクリニックと連携するパートナー開発チームかどうか、API Keyと権限が準備されているかを先に確認する必要があります。

質問が曖昧な場合は、画面の所有者を基準に判断してください。自社画面とサーバーを作るならOpenAPI、KOSが提供する予約画面を組み込むならKOS Connectです。

## 初めて参加する外部開発者の場合

AIに実装方法を聞く前に、次の情報を先に整理してください。

- 担当範囲がクリニックサイトのボタン、ウィジェット、LINE予約導線だけか、自社画面とサーバーフローまで含むか
- 連携対象のクリニックがKOSを利用中か、外部開発会社がそのクリニックと連携するパートナー開発チームか
- KOS Connectの`appId`が必要か、OpenAPIの`API Key`と権限が必要か
- 開発環境での検証か、本番適用予定が決まっている作業か
- npmパッケージを使えるReact/TypeScript環境か、Scriptタグだけを挿入できる環境か

この情報を一緒に渡すと、AIがKOS ConnectとOpenAPIを混同せず、必要な文書と次のアクションをより正確に案内できます。

## プロンプト例

```text
KOS Developersドキュメントを基準に回答してください。
まずKOS Connect、OpenAPI、ガイドのどの経路かを判断し、
必要なMarkdown文書とopenapi.yamlだけを確認してください。
ドキュメントで確認できない内容は推測せず、最後に参照した公開URLを列挙してください。

質問:
Reactで作ったクリニックサイトの予約ボタンからKOS Connectウィジェットを開きたいです。
npmパッケージとScriptタグのどちらを使うべきで、開発/本番環境では何に注意すべきですか？
```

```text
KOS Developersドキュメントを基準に回答してください。
私たちは独自の予約UIとサーバーフローを作っています。
reserveV2のmethod/path、認証、必須request field、400 oneOf error variant、
リンクされたschema文書を確認して、実装チェックリストとして整理してください。
```

## AIに伝えるとよい情報

AIに質問する時は、実装しようとしている画面と責任範囲を一緒に伝えると精度が上がります。たとえば、クリニックサイトにKOSの予約画面を埋め込むのか、独自の予約画面とサーバーを作るのかを先に説明してください。

KOS Connectを使う場合は、使用しているフレームワーク、ウィジェットを開くボタンの位置、npmパッケージとScriptタグのどちらを使いたいか、開発/本番appIdを分けているかを伝えてください。

OpenAPIを使う場合は、自社サーバーで実装したい機能、必要なデータ、発行済みの認証情報の範囲、確認したいendpointやschema名を伝えてください。予約作成のように複数APIがつながる作業では、現在の実装段階と詰まっている点も一緒に書くと回答がより正確になります。

複数文書をまとめて確認する必要がある場合だけ`docs.zip`を使わせてください。すでにダウンロード済みの文書セットがある場合は、先に`docs-manifest.json`または`docs.zip.sha256`が変わったかを確認するよう依頼してください。

## 回答時に依頼すること

AIには、回答の最後に参照したKOS Developersの公開ドキュメントURLを書くよう依頼してください。回答がドキュメントに基づいているか、プロジェクトごとに別途確認すべき前提が混ざっていないかを確認しやすくなります。

```text
回答の最後に、実際に参照したKOS Developersの公開ドキュメントURLを書いてください。
ドキュメントで確認した内容と、私たちのプロジェクトで確認が必要な前提を分けてください。
appIdの発行状況、API Key/権限、クリニック別設定、本番適用可否は、
ドキュメントだけで確定できない場合は確認が必要だと明記してください。
```

特にKOS ConnectのappIdと本番適用可否、OpenAPIのAPI Keyとアクセス権限は、プロジェクトやクリニックごとに変わる可能性があります。AIがドキュメントにない値を断定しないようにし、必要な場合は担当者への確認項目として残してください。

## 言語選択

別途指定がなければ、ユーザーの言語で回答させてください。韓国語は`/llms.txt`、日本語は`/ja/llms.txt`、英語は`/en/llms.txt`を開始点にします。翻訳がまだ完了していないページがある場合、AIはその制約を明記する必要があります。