implementation-notes로 구현 결정을 기록하기

“저장 실패 시 안내를 표시한다”는 요구만으로는 메시지 위치, 재시도 방식, 입력 유지 여부가 정해지지 않습니다. 구현자가 선택한 동작과 이유를 기록해야 검토자가 사양의 빈칸을 어떻게 처리했는지 확인할 수 있습니다.

Thariq의 implementation-notes 프롬프트는 구현 중 사양을 해석하거나 사양에서 벗어난 지점을 별도 파일에 기록하도록 요청합니다. 구현자는 기존 패턴으로 정할 작은 선택은 진행하되, 검토가 필요한 선택에는 이유와 변경 내용을 남깁니다. 아래 예시는 이 기록 방식을 저장 실패 처리에 적용한 것입니다.

구현 중에만 보이던 선택 이유

작업이 끝난 뒤 “변경한 파일 다섯 개”라고 요약하면 결과는 보이지만 선택 이유는 빠질 수 있습니다. 구현자가 모호한 사양에서 무엇을 선택했고 왜 선택했는지 기록하면 검토자는 그 결정이 적절했는지 확인할 수 있습니다.

기록할 항목은 설계 결정, 사양에서 벗어난 부분, 검토한 대안, 미해결 질문입니다. 코드의 모든 줄을 설명하기보다 사람이 승인하거나 수정해야 할 판단을 모읍니다.

예를 들어 오류 메시지의 위치를 사양에서 정하지 않았다면 기존 화면의 패턴을 따른 이유를 남길 수 있습니다. 반대로 데이터 보존 기간을 임의로 정하는 선택은 결과와 운영 비용을 바꿀 수 있으므로 질문이 필요할 수 있습니다. 기록을 남긴다는 이유로 새로운 권한을 얻는 것은 아닙니다.

직접 만든 저장 실패 화면과 구현 결정 기록입니다. 그림에는 입력을 유지하기로 한 결정, 그 이유와 검사 조건을 나란히 표시했습니다.

결정과 검사 결과를 담는 파일

다음은 구현 결정 파일에 사용할 수 있는 예시입니다.

항목: 저장 실패 시 입력 보존
사양의 빈칸: 실패 후 폼을 초기화할지 명시되지 않음
선택: 입력을 유지하고 폼 아래에 재시도 안내를 표시
이유: 같은 내용을 다시 입력하지 않고 재시도할 수 있음
관련 위치: 저장 처리 함수와 오류 안내 컴포넌트
확인: 저장 실패를 재현해 입력이 유지되는지 검사

결정 기록에는 사양의 빈칸, 선택한 동작, 선택 이유, 확인 방법을 함께 씁니다. 검사를 실행하지 않았다면 “확인 예정”으로 남기고, 실행했다면 실제 결과와 근거 위치를 기록합니다.

프로젝트에 결정 기록 양식이 있다면 그대로 사용합니다. HTML과 Markdown 중 어떤 형식을 쓰든 관련 코드의 위치와 검사 결과를 함께 적으면 검토자가 선택 이유를 대조할 수 있습니다.

진행할 선택과 질문할 선택

사양에 따라 구현해주세요.
기존 패턴으로 정할 수 있는 작은 선택은 진행해주세요.
사양을 해석한 부분과 의도적으로 달라진 부분은
implementation-notes.md에 이유와 확인 결과를 기록해주세요.
데이터 구조, 외부 전송, 비용이 달라지는 결정은 먼저 확인해주세요.

작업 요청에는 진행해도 되는 선택과 먼저 확인할 선택을 함께 적습니다. 이미 합의한 승인 기준이 있다면 그 기준을 참조합니다.

바뀐 구현에 맞춘 결정 기록

구현이 바뀌면 기록도 갱신해야 합니다. 채택하지 않은 대안을 현재 동작처럼 남기면 다음 작업자가 잘못된 전제로 시작할 수 있습니다. 최종 결정, 이유, 검증 상태를 분명하게 두고 과거 시도는 필요한 경우에만 보조 정보로 남깁니다.

구현자는 중요한 결정을 작업 메모뿐 아니라 관련 문서나 코드에도 반영합니다. 사용자에게 보이는 동작은 사용법에, 코드가 유지해야 할 조건은 테스트나 적절한 주석에 남길 수 있습니다.

저장 실패 처리가 바뀌었다면 검토자는 해당 diff와 결정 기록을 함께 읽습니다. “입력 보존”을 선택했다는 기록과 저장 실패 시 실제 값이 남는지 검사한 결과를 대조합니다.

최종 검토에서는 현재 코드, 결정 기록, 검사 결과가 같은 동작을 설명하는지 확인합니다. 구현이 바뀌었다면 이유와 검증 상태도 갱신해야 다음 작업자가 오래된 결정으로 판단하지 않습니다.