# API 및 인터페이스 설계 (api-and-interface-design)

> 계약 우선, 일관된 오류 처리, 경계 검증, 추가 방식 확장으로 안정적이고 잘못 쓰기 어려운 API 와 인터페이스를 설계합니다.

- 카테고리: [아키텍처 설계](https://www.myskills.tools/ko/categories/architecture/)
- 출처: 커뮤니티 · Addy Osmani
- 저장소: https://github.com/addyosmani/agent-skills/tree/main/skills/api-and-interface-design (commit 63128d0)
- SKILL.md: https://github.com/addyosmani/agent-skills/blob/main/skills/api-and-interface-design/SKILL.md
- 설치 명령: `npx skills add addyosmani/agent-skills --skill api-and-interface-design`
- 라이선스: MIT
- 호환 도구: Claude Code, Codex, Cursor, Copilot, Gemini CLI
- 권한: read-repo ✓, write-files ✓, shell ✗, network ✗
- 상태: 스캔 통과
- 규칙 스캔으로 모든 위험을 찾을 수는 없습니다. 설치 전에 이 스킬의 SKILL.md를 읽고 권한을 확인하세요.

## 핵심 규칙

하이럼의 법칙에 따라 관찰 가능한 모든 동작은 누군가 의존하게 되므로, 무엇을 노출할지 신중히 정합니다.

## 실행 단계

1. **계약 먼저** — 구현 전에 타입이 지정된 입출력 인터페이스를 정의하며, 계약이 곧 명세입니다.
2. **오류와 검증 통일** — 모든 엔드포인트에 같은 오류 형식을 쓰고 입력 검증은 시스템 경계에서만 하며, 외부 API 응답은 항상 신뢰하지 않습니다.
3. **확장을 고려한 설계** — 새 필드는 선택 사항으로 추가하고 타입 변경이나 삭제는 하지 않으며, 단일 버전 원칙, 일관된 이름, 목록 엔드포인트 페이지네이션을 지킵니다.
4. **멱등 키 준수** — 멱등 키는 시도가 아닌 의도에서 만들고, 고유 제약으로 원자적으로 확보하며, 같은 키에 다른 본문이면 명확히 실패시키고, 보존 기간은 가장 긴 재시도 경로에 맞춥니다.
5. **체크리스트 검증** — 모든 엔드포인트에 타입이 있는 입출력이 있고, 오류 형식이 일관되며, 변경이 하위 호환되고, 타입이나 문서가 구현과 함께 커밋되었는지 확인합니다.

## 권한 설명 (SKILL.md 기준)

| 기능 | 필요 여부 | 설명 |
|---|---|---|
| 파일 쓰기 | 필요 | 인터페이스 타입, 스키마 정의, API 처리 코드와 함께하는 문서를 작성합니다. |
| 명령 실행 | 필요 없음 | 명령 실행을 요구하지 않습니다. |
| 네트워크 송신 | 필요 없음 | 네트워크에 접근하지 않습니다. |

## SKILL.md 프런트매터(YAML)

```yaml
---
name: api-and-interface-design
description: Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
---
```

홈: https://www.myskills.tools/ko/ · URL: https://www.myskills.tools/ko/skills/api-and-interface-design/