앞 글에서는 사람에게 보여 줄 맥락과 AI가 이어서 읽을 맥락을 나눈 이유를 다뤘다. 이번 글에서는 그 맥락에 무엇을 넣고, 무엇은 다음 작업자의 판단으로 남겼는지 이야기하려 한다.

기준이 필요해진 것은 서버의 API 변경을 클라이언트 작업으로 넘길 때였다. 상대가 작업을 시작할 수 있는 정보는 충분히 주어야 했지만, 내가 아는 내용을 모두 적거나 구현 방법까지 정해 주는 것은 오히려 핸드오프를 흐렸다.

많이 적었지만 다음 작업은 선명해지지 않았다

인증 상태에 따라 클라이언트의 동작이 달라지는 API 계약을 정리한 적이 있다. 서버에서는 새로운 상태를 구분해 응답하도록 바뀌었고, 클라이언트에서도 그 응답을 별도로 처리해야 했다.

처음 만든 핸드오프에는 서버가 조건을 검사하는 순서와 내부 처리 방식, 구현하면서 검토한 대안과 판단 과정까지 담았다. 이슈와 PR, 댓글에 있던 설명도 빠뜨릴까 걱정돼 다시 옮겨 적었다. 문서는 길어졌지만 클라이언트가 알아야 할 변경 사항과 작업 목표는 여러 설명 사이에 흩어졌다.

받는 쪽에서는 자신이 처리할 응답을 찾으려면 서버의 구현 과정부터 따라가야 했다. “이전과 달라진 응답이 무엇이고, 클라이언트에서는 무엇을 처리해야 하나요?”라는 질문이 다시 나왔다. 정보가 부족해서가 아니라 필요한 정보가 가려져서 생긴 질문이었다.

상대의 다음 판단에 필요한 정보만 남겼다

핸드오프에는 “만료된 인증 정보로 요청하면 서버가 401과 AUTH_EXPIRED를 반환한다”는 계약을 먼저 적었다. 인증 정보가 유효한 요청과 다른 인증 오류의 응답은 바뀌지 않았다는 범위도 함께 밝혔다. 클라이언트에는 AUTH_EXPIRED를 다른 인증 실패와 구분해 처리해야 한다는 목표와 이를 확인할 시나리오만 남겼다.

사람이 읽는 핸드오프에서는 응답 계약을 이해하는 데 필요하지 않은 서버 내부의 검증 순서와 구현 과정을 뺐다. 상세한 판단 근거는 이슈와 PR에 남겼다.

후속 작업을 AI로 이어 갈 때는 클라이언트 작업의 목표와 해당 이슈·PR 링크만 건넸다. AI는 이슈와 PR의 본문과 댓글을 읽으며 필요한 맥락을 자연스럽게 얻었고, 같은 설명을 다시 붙일 필요가 없었다.

정리한 뒤에는 서버의 내부 동작을 따라가지 않아도 변경된 계약과 후속 작업이 바로 보였다. 이전보다 문서는 짧아졌고, 무엇을 처리해야 하는지 다시 묻는 일도 줄었다.

먼저 정해 둔 해법은 상대의 생각을 가두기 쉽다

정보를 골라낸 뒤에는 어디까지 구체적으로 적을지도 정해야 했다. 클라이언트가 AUTH_EXPIRED를 다른 인증 실패와 구분해 처리해야 한다는 목표까지는 서버 변경으로 생긴 후속 작업이므로 분명히 전달했다.

서버와 클라이언트 코드를 하나의 작업공간에 연 모노레포1 환경에서는 서버 작업 세션의 AI가 클라이언트 코드에도 접근한다. AI는 클라이언트의 오류 처리 모듈에서 수정할 위치를 짚고, 새 분기에서 특정 화면으로 이동시키는 구현까지 제안했다. 바로 실행할 만큼 구체적이어서 처음에는 친절한 핸드오프라고 생각했다.

하지만 클라이언트의 전체 흐름과 상태 관리 방식, 비슷한 상황을 처리하는 화면은 클라이언트 작업에서 다시 살펴봐야 할 맥락이다. 서버 작업 세션에서 제시한 해법이 문서에 남으면 후속 작업은 그 제안을 기본값으로 받아들이기 쉽다. 더 나은 방법이 있어도 이미 정해진 안에서 벗어나는 이유부터 설명해야 한다. 도움을 주려고 덧붙인 구현안은 오히려 후속 작업의 출발점을 한 방향으로 좁힐 위험이 있다.

그래서 서버에서 확인한 응답 조건과 후속 작업의 목표까지만 남겼다. 화면을 어떻게 구성할지, 어느 파일을 수정할지, 어떤 상태 구조를 사용할지는 클라이언트 작업 세션이 코드를 읽고 결정하도록 뒀다.

제안 / 합의한 결과를 구분해 적었다

상대의 영역을 대신 정하지 않는다고 해서 의견까지 감출 필요는 없었다. 클라이언트 쪽에서 처리 방향을 물으면 내가 본 선택지와 장단점을 답했다. 다만 핸드오프에는 확정된 사실처럼 적지 않고, 검토할 제안이라고 표시했다. 의견과 확정된 계약을 나눠야 무엇을 참고하고 무엇을 전제로 삼을지가 선명해진다.

반대로 어느 한쪽의 선택으로 남겨 둘 수 없는 문제도 있다. 예를 들어 AUTH_EXPIRED를 별도 오류 코드로 둘지는 서버의 응답 계약과 클라이언트의 분기 방식에 모두 영향을 준다. 이런 문제는 한쪽에서 정해 넘기지 않고 함께 결정했다. 합의한 결과는 어느 한쪽의 권고가 아니라, 양쪽 작업이 따라야 할 계약으로 남겼다.

정리

그 뒤로 핸드오프를 쓸 때는 다음을 주의했다.

  • 상대에게 필요한 정보만 넘긴다.
  • 세부 정보는 관련 이슈나 PR에 모으고, 핸드오프에서는 링크로 연결한다.
  • 화면, 수정 파일, 상태 구조처럼 상대가 정할 해법은 미리 정하지 않는다.

좋은 핸드오프는 정보를 많이 넘기는 문서가 아니라, 작업을 이어받은 사람이 필요한 맥락을 바로 찾을 수 있는 문서라고 생각한다.

무엇을 넘길지 정한 뒤에는, 선별한 정보를 한눈에 파악할 수 있는 문서 형태를 고민했다. 이 고민은 핸드오프 문서에 표와 시퀀스를 사용하는 이유에서 이어진다.

Footnotes

  1. 서버와 클라이언트처럼 여러 프로젝트의 코드를 하나의 저장소에서 함께 관리하는 방식이다. ↩