인터페이스 계약 작성 방법

인터페이스 계약 문서는 승인된 Discovery와 구현 결과를 근거로 외부·내부 인터페이스의 호출 규칙을 설명한다.

저장 위치

완성된 인터페이스 계약 문서는 대상 저장소 루트 기준 docs/interface-contract.md에 저장한다. 파일이 이미 존재하면 별도 문서를 만들지 않고 이 정본 문서를 갱신한다.

이 디렉터리의 README.md와 TEMPLATE.md는 하네스의 작성 규칙과 템플릿이며 대상 저장소에 저장하는 산출물이 아니다.

TEMPLATE.md를 복사하고 섹션 순서를 유지한다.
목적, 포함·제외 범위 및 인터페이스 사용 주체를 명시한다.
계약의 H3 블록을 인터페이스 수만큼 복제하고 입력·출력·오류 행을 실제 계약 수만큼 복제한다.
모든 ${lowercase_snake_case} placeholder를 실제 값으로 교체한다. ${stable_section_id}에는 고유한 소문자 케밥 표기법을 사용한다. 인터페이스 이름이 바뀌어도 ID는 유지하며 삭제된 ID를 재사용하지 않는다.
각 인터페이스의 책임, 종류·프로토콜, 호출 대상, 버전, 호출 주체, 인증·권한을 기록한다.
입력·출력 필드와 오류 계약을 표에 기록한다. 값이 없으면 없음으로 기록한다.
기존 호출 방식, 버전 변경·폐기, 재시도·중복 처리 및 순서 보장에 대한 호환성 계약을 기록한다.
실제 구현과 일치하는 호출 예시와 정상·실패·경계 계약의 검증 방법을 기록한다. 예시에는 실제 credential이나 민감정보를 포함하지 않는다.

근거 없이 인터페이스나 동작을 추측하지 않는다. 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.