# AI와 함께 개발하기

KOS Developers는 사람이 읽는 문서와 AI 에이전트가 읽는 문서를 함께 제공합니다. AI를 사용할 때는 전체 문서를 한 번에 내려받게 하기보다, 먼저 문서 지도를 읽고 필요한 페이지만 확인하게 해야 합니다.

## 가장 권장하는 방법

AI 에이전트가 skill 설치를 지원한다면 다음 명령으로 KOS Developers skills를 설치하세요.

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

설치 여부만 확인하려면 다음처럼 조회할 수 있습니다.

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

설치되는 skill은 세 가지입니다. 공통 skill은 언어와 제품 경로를 고르고, OpenAPI skill은 API 계약과 인증을 확인하며, KOS Connect skill은 위젯 설치와 appId, 클라이언트 제약을 확인합니다. 이 skill들은 API를 대신 호출하는 도구가 아니라 `llms.txt`, 개별 Markdown 문서, 필요한 경우 `openapi.yaml`을 확인하도록 안내하는 문서 탐색 절차입니다.

## skill을 설치하지 못하는 경우

AI에게 아래 순서로 문서를 읽게 하세요.

1. 먼저 `/skill.md` 또는 `/.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 | `/skill.md` |
| OpenAPI skill | `/.well-known/agent-skills/kos-openapi/SKILL.md` |
| KOS Connect skill | `/.well-known/agent-skills/kos-connect/SKILL.md` |
| skill discovery | `/.well-known/agent-skills/index.json` |
| OpenAPI 원본 스펙 | `/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가 그 한계를 명시해야 합니다.