모듈 밖과 주고받는 약속을 적는다. 도메인 문서(docs/domains/)가 "무엇을 지켜야 하나"라면, 계약은 "어떻게 주고받나"다.
| 폴더 | 무엇 | 예 |
|---|---|---|
| api/ | 프론트와 외부가 부르는 HTTP API. 요청·응답·오류 코드 | POST /api/auctions/{id}/bids |
| events/ | 서버 안에서 모듈끼리 주고받는 이벤트. 언제, 무슨 내용으로 발행하고 누가 받는지 | 회원 탈퇴 → 인증이 Refresh Token 폐기 |
모든 계약 문서는 제목 바로 아래에 이 머리말을 둔다.
> 담당: 이름
>
> 상태: IMPLEMENTED
>
> 관련 코드: `backend/src/main/java/com/restless/<모듈>/api/`
>
> 마지막 확인: YYYY-MM-DD (무엇과 대조했는지)- 관련 코드: 이 문서가 설명하는 코드의 경로. 코드가 바뀌면 이 문서도 확인한다.
- 마지막 확인: 문서를 코드와 대조한 날짜와 범위. 대조하지 않았으면 날짜를 바꾸지 않는다.
| 상태 | 뜻 |
|---|---|
DRAFT |
설계 중. 바뀔 수 있다 |
DECIDED |
합의했지만 아직 구현하지 않았다 |
IMPLEMENTED |
구현했다. 문서와 코드가 다르면 코드가 현재 동작이다. 다른 점을 찾으면 담당자에게 알리고 문서를 고친다 |
한 문서 안에 상태가 섞이면 엔드포인트 표의 구현 열로 나눈다 (구현 / 미구현).
- 요청·응답·오류만 적는다. 업무 정책은
docs/domains/<도메인>/에 두고 링크한다. - 다른 문서의 내용은 복사하지 않고 링크한다. 예: 결제는 payment.md를 가리킨다.
- 새 API를 만들면 도메인 문서와 전체 엔드포인트 색인에 함께 추가한다.