AI로 개발하기
ChatGPT, Claude, Cursor 같은 AI 도구에 카플랫 문서를 연결해 연동 코드를 작성하는 방법을 설명합니다.
카플랫 개발자 센터는 AI 도구가 읽기 좋은 형태의 문서를 함께 제공합니다. AI에게 아래 자원을 알려주면, 학습 데이터에 없는 카플랫 API도 최신 명세를 기준으로 정확하게 답변하고 코드를 작성할 수 있습니다.
AI를 위한 카플랫 자원
| 자원 | 주소 | 용도 |
|---|---|---|
| llms.txt | /llms.txt | 개발자 센터 전체 구조와 문서 링크를 정리한 인덱스입니다. 처음 연결할 때 가장 먼저 알려주세요. |
| llms-full.txt | /llms-full.txt | 모든 가이드와 API 레퍼런스를 한 파일로 합친 문서입니다. 파일을 첨부하거나 컨텍스트에 통째로 넣을 때 사용합니다. |
| 가이드 마크다운 | /guides/{문서}.md | 가이드 주소 끝에 .md를 붙이면 마크다운 원본을 받을 수 있습니다. 예: /guides/reservation.md |
| API 레퍼런스 마크다운 | /reference.md | 모든 엔드포인트의 파라미터, 요청·응답 필드, 예시를 담은 문서입니다. |
| OpenAPI 명세 | /openapi.json | OpenAPI 3.0 원본입니다. 요청·응답 타입이나 API 클라이언트 코드를 생성할 때 사용합니다. |
참고: 모든 자원은 개발자 센터 문서가 갱신되면 함께 갱신됩니다. 오래된 사본을 프로젝트에 저장해 두었다면 주기적으로 다시 받아주세요.
사용 방법
채팅형 AI (ChatGPT, Claude 등)
웹 검색이나 URL 읽기를 지원하는 AI라면 llms.txt 주소를 프롬프트에 함께 적고, 문서를 읽은 뒤 답하도록 요청하세요. AI가 문서를 실제로 읽었는지는 도구마다 다르므로, 참조한 문서와 확인하지 못한 내용을 답변에 표시하게 하면 결과를 검증하기 쉽습니다.
text
Loading...
URL을 읽지 못하는 환경이라면 llms-full.txt를 내려받아 파일로 첨부하세요.
AI 코딩 도구 (Claude Code, Cursor, Codex 등)
- 문서 등록: 도구의 문서 소스 기능(예: Cursor의
@Docs)에llms.txt주소를 등록해 두면, 대화에서 카플랫 문서를 지정해 참조하도록 요청할 수 있습니다. - 프로젝트에 명세 저장:
openapi.json을 프로젝트에 저장해 두고 AI에게 해당 파일을 기준으로 타입과 클라이언트 코드를 만들도록 요청하세요. - 에이전트 지침 파일:
AGENTS.md나CLAUDE.md같은 지침 파일에 아래 내용을 추가해 두면, 카플랫 관련 작업에서 문서를 먼저 읽도록 안내할 수 있습니다. 지침을 따르는지는 도구마다 다르므로, 결과에 참조한 문서가 표시되는지 확인하세요.
markdown
Loading...
프롬프트 예시
코드 작성
- "카플랫 예약 정보 등록 콜백 이벤트를 받는 Spring Boot 컨트롤러를 만들어줘."
- "openapi.json의
/developer/v1/경로를 호출하는 TypeScript 클라이언트를 만들어줘./events/경로는 고객사 서버가 수신하는 콜백이므로 별도로 다뤄줘." - "차량 정비 일정이 생기면 카플랫 스케줄을 등록하고, 정비가 끝나면 삭제하는 코드를 작성해줘."
에러 디버깅
- "카플랫 API 호출 시
E001에러가 나는데 원인과 해결 방법을 알려줘." - "배차 완료 API가 409 응답을 주는데 어떤 상태에서 호출해야 해?"
문서 조회
- "예약 상태 흐름을 정리하고, 각 상태에서 호출할 수 있는 API를 표로 만들어줘."
- "콜백 이벤트 종류와 각 이벤트의 요청 필드를 비교해줘."
주의사항
- API 키를 AI에 입력하지 마세요. 코드에는 환경 변수 같은 자리표시자를 쓰고, 실제 키는 직접 설정하세요.
- 테스트 서버에서 먼저 검증하세요. AI가 만든 코드는
https://test-api-partners.carplat.co.kr에서 충분히 확인한 뒤 운영 서버https://api-partners.carplat.co.kr로 전환하세요. - 결과를 문서와 대조하세요. AI는 틀린 답변을 할 수 있습니다. 상태 전이 조건이나 필드 필수 여부·길이 제한처럼 중요한 내용은 가이드와 API 레퍼런스에서 다시 확인하세요. 필드 제약의 최종 기준은
openapi.json입니다.