AI가 설계 결정을 자꾸 잊는다면, ADRs4AI에 남길 기록

“무엇을 쓴다” 옆에 “왜 골랐다”를 남긴다

AI와 개발을 이어 갈 때 남길 것은 최종 코드만이 아니다. 어떤 문제에서 출발했고, 무엇을 검토했으며, 누가 왜 그 선택을 승인했는지가 다음 설계 판단에 필요하다. ADRs4AI는 이 내용을 Git으로 관리하는 문서로 남겨 세션이나 모델이 바뀌어도 다시 읽을 수 있게 한다.

기존의 아키텍처 결정 기록인 ADR을 확장해, 결정을 내리는 과정의 질문과 답까지 보존한다. 채팅을 통째로 보관하는 방식과 달리, 나중에 이어갈 논점과 사람의 판단을 문서에서 찾을 수 있게 하는 데 초점이 있다.

가령 CSV 내보내기를 서버에서 처리하기로 했다고 가정하자. 기록이 “서버에서 생성한다”로 끝나면, 다음 작업자는 브라우저에서 만들자는 제안을 다시 할 수 있다. 당시 파일 크기와 권한 요구 때문에 서버 처리를 골랐다는 이유까지 있으면 새 요구가 그 선택을 바꿀 만큼 달라졌는지 논의할 수 있다. 이는 기록 방식을 설명하기 위한 가상 예다.

AI가 추천한 것과 사람이 결정한 것을 섞지 않는다

공식 양식은 날짜·상태·참여자를 적고, 질문에 대한 추천과 사람의 답을 나눈다. “AI가 이렇게 하자고 했다”는 문장을 곧바로 팀의 승인으로 바꾸지 않는 구조다.

질문은 QST:, 답은 ANS:로 표시한다. 추천에는 모델과 날짜 등을 남기며, 문서의 상태와 개별 질문의 상태도 관리한다. 확신 수준은 작성자가 밝히는 판단의 근거이지 검증된 성공 확률이 아니다.

기존 프로젝트에도 결정 하나부터 적용할 수 있다

템플릿 저장소는 새 프로젝트를 시작하거나 필요한 파일을 기존 저장소에 가져오는 방식을 제공한다. 복잡한 논의용 ADR, 간단한 결정용 MADR, 정리 전 생각을 담는 seed 양식이 나뉘어 있다.

처음에는 아직 결론을 내리지 못한 작은 설계 문제 하나면 된다. 요구와 걱정을 seed에 적고, AI가 이를 논점별 기록과 질문으로 나누게 한 다음 사람이 답한다. 시작 안내도 처음부터 큰 자동화 체계를 구축하기보다 템플릿·seed·첫 질문에 대한 답을 출발점으로 제시한다.

예전 결정을 보존하는 목적은 변경을 막는 데 있지 않다. 새 요구로 판단이 달라졌다면, 어떤 조건이 바뀌었고 무엇으로 대체했는지를 남기는 편이 다음 사람에게 도움이 된다. “예전에도 같은 선택을 했다”와 “그때는 맞았지만 지금은 조건이 달라졌다”는 다른 정보다.

VS Code 확장은 기록을 찾고 답하는 수고를 줄인다

ADRs for AI 확장은 열린 질문을 사이드바에 모으고 그 자리에서 답을 입력하게 한다. 기본 편집 기능에는 별도 서버·계정·API 키가 필요하지 않으며, 문서는 기본적으로 docs/adr/에 남는다. 확장을 지워도 Markdown 기록은 읽을 수 있다.

답을 제출할 때마다 자동으로 커밋하는 기능은 기본값이 꺼져 있다. 입력한 답이 파일에 남는 것과 Git 이력으로 확정되는 것은 구별해야 한다.

다음 세션이 해당 기록을 읽도록 작업 지침과 연결하고, 사람이 답한 내용이 정확히 반영됐는지 살피는 일은 남는다. 도입 효과를 판단할 첫 기준도 기록 개수보다 단순하다. 다음 작업에서 이전 선택의 이유와 아직 남은 질문을 바로 찾아 이어갈 수 있는가다.