23 lines
1.9 KiB
Markdown
23 lines
1.9 KiB
Markdown
# 인터페이스 계약 작성 방법
|
|
|
|
인터페이스 계약 문서는 승인된 Discovery와 구현 결과를 근거로 외부·내부 인터페이스의 호출 규칙을 설명한다.
|
|
|
|
## 저장 위치
|
|
|
|
완성된 인터페이스 계약 문서는 대상 저장소 루트 기준 `docs/interface-contract.md`에 저장한다. 파일이 이미 존재하면 별도 문서를 만들지 않고 이 정본 문서를 갱신한다.
|
|
|
|
이 디렉터리의 [`README.md`](README.md)와 [`TEMPLATE.md`](TEMPLATE.md)는 하네스의 작성 규칙과 템플릿이며 대상 저장소에 저장하는 산출물이 아니다.
|
|
|
|
## 작성 방법
|
|
|
|
1. [`TEMPLATE.md`](TEMPLATE.md)를 복사하고 섹션 순서를 유지한다.
|
|
2. 목적, 포함·제외 범위 및 인터페이스 사용 주체를 명시한다.
|
|
3. `계약`의 H3 블록을 인터페이스 수만큼 복제하고 입력·출력·오류 행을 실제 계약 수만큼 복제한다.
|
|
4. 모든 `${lowercase_snake_case}` placeholder를 실제 값으로 교체한다. `${stable_section_id}`에는 고유한 소문자 케밥 표기법을 사용한다. 인터페이스 이름이 바뀌어도 ID는 유지하며 삭제된 ID를 재사용하지 않는다.
|
|
5. 각 인터페이스의 책임, 종류·프로토콜, 호출 대상, 버전, 호출 주체, 인증·권한을 기록한다.
|
|
6. 입력·출력 필드와 오류 계약을 표에 기록한다. 값이 없으면 `없음`으로 기록한다.
|
|
7. 기존 호출 방식, 버전 변경·폐기, 재시도·중복 처리 및 순서 보장에 대한 호환성 계약을 기록한다.
|
|
8. 실제 구현과 일치하는 호출 예시와 정상·실패·경계 계약의 검증 방법을 기록한다. 예시에는 실제 credential이나 민감정보를 포함하지 않는다.
|
|
|
|
근거 없이 인터페이스나 동작을 추측하지 않는다. 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.
|