활용 가이드
요청·응답·인증·오류·예시가 코드와 어긋나지 않도록 API 문서를 유지하는 방법입니다.
API 문서는 코드와 가장 빨리 어긋나는 문서입니다. 파라미터 하나, 응답 필드 하나가 바뀌어도 문서를 믿고 연동한 사람은 바로 막힙니다. Specify는 엔드포인트 파라미터, 응답 필드, 요청 예시가 코드와 어긋나는지 확인하고 수정안을 준비합니다.
설정하기
API 코드가 있는 저장소 연결하기
라우트, 핸들러, 스키마 정의가 있는 저장소와 브랜치를 문서 프로젝트의 소스로 연결합니다. 스키마가 별도 저장소에 있다면 소스를 하나 더 추가합니다.
API 레퍼런스 문서 스킬 선택하기
API 레퍼런스를 만드는 문서 스킬을 선택하고, 강조할 점에 대상 독자(내부 팀, 외부 파트너 등)와 다룰 범위를 적습니다.
push 트리거 켜기
기본 브랜치에 push 시 실행을 켜서 API 변경이 반영될 때마다 수정안을 받습니다.
수정안을 검토할 때 확인할 것
| 영역 | 확인할 점 |
|---|---|
| 요청 | 경로, 메서드, 경로·쿼리 파라미터, 요청 본문 스키마와 필수 여부 |
| 응답 | 상태 코드별 응답 필드, 타입, nullable 여부, 페이지네이션 형식 |
| 인증 | 필요한 인증 방식, 권한 범위, 토큰 전달 위치 |
| 오류 | 오류 코드와 메시지, 재시도 가능 여부 |
| 예시 | 요청·응답 예시가 새 스키마와 일치하는지 |
| 호환성 | 필드 삭제·이름 변경처럼 기존 연동을 깨는 변경인지, 마이그레이션 안내가 필요한지 |
기존 연동을 깨는 변경은 자동 수정만으로 충분하지 않을 수 있습니다. 변경 이력과 마이그레이션 안내가 필요한지 사람이 판단해 보완하세요.
코딩 에이전트와 함께 쓰기
Specify MCP를 연결하면 Claude Code나 Codex가 API를 수정하는 동안 워크스페이스의 API 문서를 직접 참고할 수 있습니다. 문서와 코드를 같은 맥락에서 다루게 됩니다.