개발 문서 세 가지: README·결정 기록·장애 대응 절차
새 작업자가 설치하고 판단하고 복구할 수 있도록 문서별 질문과 갱신 시점을 나눕니다.
문서를 한 파일에 계속 추가하면 설치 방법, 결정 배경, 장애 대응이 섞여 필요한 내용을 찾기 어려워집니다. 독자가 지금 답하려는 질문에 따라 문서를 나누면 길이를 늘리지 않고도 도움이 되는 정보를 남길 수 있습니다.
README는 처음 실행할 사람을 위해
README에는 프로젝트 목적, 요구 버전, 설치, 설정, 실행, 검증 명령을 순서대로 둡니다. ‘평소처럼 실행’처럼 기존 담당자만 아는 표현은 피합니다. 복사 가능한 명령에는 실행 위치와 필요한 준비물을 적습니다.
새 환경에서 문서대로 따라 해 보고 빠진 단계를 기록합니다. 내부 주소나 비밀값을 본문에 넣지 않고 환경변수의 이름과 발급·설정 경로를 설명합니다. 개발 환경 복구 절차와 연결하면 같은 내용을 중복해서 유지할 필요가 줄어듭니다.
결정 기록은 선택의 조건을 남기기
다음은 작성 형식의 예제입니다. 실제 서비스의 결정이나 성과가 아닙니다.
제목: 알림 발송을 요청 처리와 분리
상황: 외부 발송 지연이 사용자 응답에 포함됨
선택: 큐에 접수하고 작업자가 발송
대안: 동기 발송에 타임아웃만 적용
이유: 사용자 요청과 발송 재시도의 수명을 분리해야 함
대가: 작업 상태 저장과 중복 처리 필요
재검토: 접수 지연 또는 복구 부담이 커질 때
선택한 기술 이름만 남기면 당시의 제약을 알 수 없습니다. 포기한 대안과 다시 볼 조건이 있어야 환경이 바뀌었을 때 판단을 이어갈 수 있습니다.
장애 대응 문서는 실행과 중단 조건
대응 문서에는 증상, 확인할 지표, 안전한 진단, 가능한 조치, 중단 조건, 복구 확인을 적습니다. 위험한 명령을 맥락 없이 붙이지 않습니다. 누가 어떤 권한으로 실행하며 실패하면 어디로 연락할지도 정합니다.
예를 들어 작업 큐가 쌓였다고 무조건 작업자 수를 늘리면 DB나 외부 서비스에 더 큰 부하를 줄 수 있습니다. 처리량, 오류, 의존 서비스 상태를 먼저 확인하도록 순서를 작성해야 합니다.
문서를 업데이트하는 시점
설치 명령이 바뀌면 README를, 선택의 조건이 바뀌면 결정 기록을, 장애에서 새로운 대응을 배웠다면 대응 문서를 고칩니다. 담당자와 마지막 검증 시점을 남기고 오래된 명령을 실제로 실행 가능한지 정기적으로 확인합니다.
완료 기준은 문서 수가 아니라 다른 사람이 과정을 재현할 수 있는지입니다. 반복되는 질문을 모아 가장 많이 막히는 지점부터 수정하고, 본문에 코드 전체를 복제하기보다 유지되는 구현과 테스트에 연결합니다.