AI 에이전트로 개발하기
코딩 에이전트에게 이 문서를 읽혀 연동을 만들 때 건넬 주소 · 지시문 · 지켜야 할 규칙을 모았습니다.
업데이트됨 10.13 — AI 에이전트용 마크다운 원문 · llms.txt이 쪽은
연동 코드를 코딩 에이전트에게 맡길 때, 에이전트가 이 문서를 빠짐없이 읽고 지어낸 필드 · 키 · 코드값 없이 만들게 하는 방법입니다. 에이전트에게 아래 주소와 지시문을 건네면 됩니다.
건넬 주소
| 주소 | 내용 |
|---|---|
https://developers.mallstory.co.kr/llms.txt | 문서 전체 목록 — 쪽마다 한 줄 설명과 주소. 에이전트가 처음 읽는 곳입니다 |
https://developers.mallstory.co.kr/docs/{쪽}.md | 쪽의 마크다운 원문 — 구현 규칙 · 필드 · 코드값 · 실제 요청 예시가 한 파일에 있습니다. 표 · 탭이 섞인 HTML 보다 빠짐없이 읽힙니다 |
https://developers.mallstory.co.kr/docs/{쪽} | 원문이 아직 없는 쪽은 이 HTML 쪽을 읽게 합니다 |
https://api.mallstory.kr | API 주소. 이 문서를 연 환경(개발 · 운영)의 주소입니다 |
마크다운 원문이 있는 쪽
다른 쪽도 차례로 원문을 엽니다. 열리면 llms.txt 의 그 쪽 줄에 원문 주소가 붙습니다.
지시문
에이전트의 첫 요청에 붙여 넣습니다. 마지막 줄의 "만들 것" 만 바꿉니다.
text에이전트에게 건넬 지시문
너는 Mall Story Open API 로 쇼핑몰 연동을 만든다.
1. 먼저 https://developers.mallstory.co.kr/llms.txt 를 읽고 필요한 문서를 고른다. 문서에 "마크다운 원문"(.md) 주소가 있으면 HTML 대신 그것을 읽는다.
2. 요청 · 응답 필드는 snake_case 다. 문서의 필드 표에 없는 필드를 만들지 않는다.
3. 정해진 값만 받는 필드는 문서의 "코드값" 표의 값만 쓴다.
4. category_id · template_id 같은 키는 지어내지 않는다. 목록 API 로 그 쇼핑몰에서 읽은 값을 쓴다.
5. 이미지는 이미지 업로드 API 로 먼저 올리고, 응답의 file_id 만 본문에 넣는다.
6. 등록 · 수정 전에 그 문서의 "구현 규칙"(필수 · 조건부 필수 · 상한)을 확인하고, 서버가 바꿔 저장하는 값은 응답으로 다시 읽는다.
7. 오류는 {code, message, request_id} 다. code 로 분기하고, message 는 사용자에게 그대로 보여 줄 수 있다. 실패하면 응답의 request_id(X-Request-Id)를 로그에 남긴다.
8. client_secret · access token · refresh token 은 서버 환경 변수에만 둔다. 코드 · 로그 · 브라우저에 넣지 않는다.
9. 401 이면 refresh token 으로 갱신하고, 403 InsufficientScope 면 필요한 권한으로 다시 동의를 받는다. 429 면 Retry-After 초만큼 기다렸다 다시 보낸다(분당 한도 — X-RateLimit-Remaining 을 보고 속도를 맞춘다).
10. 이미 만든 연동을 고칠 때는 https://developers.mallstory.co.kr/docs/changelog.md 에서 지난번 이후 바뀐 것(특히 "호환 깨짐")을 먼저 읽는다.
API 주소: https://api.mallstory.kr
만들 것: (여기에 만들 기능을 적는다 — 예: 우리 상품 데이터를 Mall Story 상품으로 등록하는 서버 작업)