첫 글에서는 사람과 AI가 읽을 맥락을 나눴고, 두 번째 글에서는 넘길 정보의 범위를 다뤘다. 필요한 정보만 골랐더라도 줄글로 길게 적으면 내용이 잘 읽히지 않고, 사람과 AI가 조건과 결과를 각자 다르게 해석할 여지가 생긴다.
표와 시퀀스를 사용하는 이유는 사람과 AI가 조건과 흐름을 명확하게 파악하도록 하기 위해서다.
문장만으로는 관계가 고정되지 않는다
인증 상태에 따라 응답이 달라지는 API 계약을 다음과 같이 적을 수 있다.
인증 정보가 유효하면 상세 정보를 반환한다. 만료된 인증 정보로 요청하면
401과AUTH_EXPIRED를 반환하고, 인증 정보가 없으면401과AUTH_REQUIRED를 반환한다.
각 문장은 틀리지 않지만 조건과 HTTP 상태, 오류 코드의 대응 관계가 문장 안에 섞여 있다. 사람은 세 가지 경우를 머릿속에서 다시 나눠야 하고, AI도 어느 조건이 어느 응답과 연결되는지 문장 사이의 관계를 해석해야 한다.
조건과 결과는 표로 적는다
같은 계약을 표로 정리하면 하나의 조건과 결과가 한 행에 놓인다.
| 인증 상태 | HTTP 상태 | 오류 코드 | 응답 |
|---|---|---|---|
| 유효 | 200 | 없음 | 상세 정보 |
| 만료 | 401 | AUTH_EXPIRED | 오류 |
| 없음 | 401 | AUTH_REQUIRED | 오류 |
사람은 경우마다 문장을 다시 나눌 필요가 없고, AI에는 조건과 결과의 대응 관계가 열과 행으로 명시된다. 상태가 추가되거나 오류 코드가 바뀌면 수정할 위치도 분명하다.
전체 흐름은 시퀀스 다이어그램으로 보여 준다
표는 조건별 결과를 비교하기 쉽지만, 응답을 받은 뒤 어떤 요청이나 동작이 이어지는지는 보여 주지 않는다. 시퀀스 다이어그램은 최초 요청부터 오류 응답, 재시도나 로그아웃 같은 후속 동작까지 하나의 흐름으로 보여 준다. 아래 다이어그램에는 Mermaid를 사용했다.
만료 응답 뒤에는 토큰 재발급과 상세 조회 재시도가 이어지고, 인증 정보가 없는 경우에는 로그아웃으로 끝난다. 시퀀스 다이어그램에서는 API 응답뿐 아니라 그다음에 이어지는 흐름까지 확인할 수 있다.
모든 내용을 표와 시퀀스로 바꾸지는 않는다
모든 내용을 표와 시퀀스 다이어그램으로 바꿀 필요는 없다. 전달할 내용에 맞는 형식을 사용한다.
| 전달할 내용 | 형식 |
|---|---|
| 하나의 사실 | 짧은 문장 |
| 여러 항목을 나열하거나 비교할 내용 | 표 |
| 요청과 후속 동작이 이어지는 흐름 | 시퀀스 다이어그램 |
표와 시퀀스 다이어그램은 문서를 읽기 쉽게 만들고, 조건과 흐름을 명확하게 보여 준다. 사람과 AI가 내용을 다르게 해석해 생기는 오해도 막을 수 있다.
정리
핸드오프 문서에서는 표와 시퀀스 다이어그램을 다음과 같이 활용한다.
- 여러 항목을 한눈에 확인해야 할 때는 표로 정리한다.
- 순서와 분기, 후속 동작이 이어지는 전체 흐름은 시퀀스 다이어그램으로 보여 준다.