Claude Code, Codex, 또는 Cursor를 몇 차례 이상 사용해 보셨다면, 이런 상황을 겪어보셨을 것입니다. 동일한 아키텍처 결정(Architectural decision)을 3주 동안 세 번이나 설명해야 하는 상황 말이죠. 왜냐하면 처음 그 결정을 내릴 때 도움을 주었던 AI 어시스턴트가 그 대화에 대한 기억을 더 이상 가지고 있지 않기 때문입니다. 6주 뒤의 당신 또한 마찬가지고요.

이것은 사실 AI의 문제는 아닙니다. 이것은 '기록(Paper trail)'의 문제입니다. AI 어시스턴트가 존재하기 전에도 존재했던 문제이지만, AI 지원 개발(AI-assisted development)이 이를 더 악화시킵니다. 이제 결정들이 몇 번의 긴 세션 대신 수십 번의 짧고 단절된 세션에 걸쳐 내려지고 다시 만들어지기 때문입니다.

대부분의 1인 개발자와 소규모 팀은 이를 아무런 조치 없이 해결하려 합니다. 그 대안인 아키텍처 검토 위원회(Architecture review boards)와 변경 제어 티켓(Change-control tickets)을 포함한 완전한 엔터프라이즈 엔지니어링 프로세스를 도입하는 것은 1인 또는 3인 팀에게는 매우 불균형한 방식입니다. 우리에게 부족한 것은 그 중간 단계의 무언가입니다. 매일 실제로 사용할 수 있을 만큼 가벼우면서도, 당신의 기억(그리고 AI의 기억)이 초기화되어도 살아남을 수 있을 만큼 구조화된 무언가 말이죠.

실제로 중요한 네 가지 요소

실제 세션에서 몇 달 동안 이를 실행해 본 결과, 결국 네 가지 산출물(Artifacts)로 귀결됩니다.

아키텍처 결정 기록 (Architecture Decision Records, ADRs). 실제 결정 하나당 하나의 파일을 작성합니다: 문제가 무엇이었는지, 어떤 선택지들이 있었는지, 무엇을 선택했는지, 왜 선택했는지, 그리고 어떤 상황에서 이 결정을 재검토하게 될 것인지 기록합니다. 핵심은 형식이 아니라, '거절된(Rejected)' 선택지들과 그 이유를 기록하는 규율에 있습니다. 그래야만 "왜 그냥 X를 하지 않았나요?"라는 질문에 "기억이 안 나요"가 아닌 답변을 내놓을 수 있습니다.

세션 보고서 (Session reports). 각 작업 세션이 끝날 때 작성하는 짧은 로그입니다. 무엇이 완료되었는지, 무엇이 결정되었는지, 무엇이 여전히 미결 상태인지, 그리고 결정적으로, 다음 세션을 여는 사람이 누구든(사람이든 AI든) 현재 상황이 정확히 어디까지 와 있는지 알려주는 몇 문장의 기록입니다. 이것은 네 가지 중 가장 레버리지가 높은(Highest-leverage) 산출물입니다. 이것은 매 세션이 시작될 때마다

의사결정 레지스터 (Decision register). 모든 ADR(Architecture Decision Record)을 인덱싱하는 하나의 실행 가능한 테이블입니다 — 상태, 날짜, 한 줄 요약 포함. "인증 토큰 만료에 대해 무엇을 결정했는가?"라는 질문에 수십 개의 파일을 검색(grepping)하는 대신, 단 하나의 테이블을 훑어보는 것만으로 답할 수 있어야 합니다.

엔지니어링 플레이북 (Engineering playbook). 아이디어, 설계, 승인, 구현, 리뷰, 완료로 이어지는 작업이 실제로 어떻게 진행되는지 정의하는 짧은 문서입니다. 이를 통해 AI 협업자가 매 세션마다 다른 방식을 즉흥적으로 만들어내는 대신, 따라야 할 프로세스를 갖게 됩니다.

특히 AI 어시스턴트와 함께할 때 이것이 더 잘 작동하는 이유

AI 코딩 어시스턴트(AI coding assistants)는 구조화된 컨텍스트(structured context)를 제공하면 그것을 사용하는 데는 이례적으로 뛰어나지만, 스스로 그것을 유지하는 데는 이례적으로 서툽니다. 새로운 Claude Code 또는 Codex 세션을 시작하기 전에, 마지막 세션 보고서와 의사결정 레지스터를 가리켜 주면, AI는 당신이 10분 동안 다시 설명해야 했을 내용을 30초 만에 파악합니다. 그리고 당신이 이미 시도했다가 거절한 솔루션을 다시 제안하는 일을 멈추게 됩니다.

주의해야 할 실패 모드는 그 반대입니다. 이것을 단순 잡무로 취급하여 사소한 선택마다 ADR을 작성하는 것입니다. 모든 것이 ADR이 된다면, 그 무엇도 ADR로서 눈에 띄지 않게 됩니다. 결정의 비용이 되돌리기 어렵거나, 진정으로 합리적인 두 가지 옵션이 존재했거나, 혹은 미래의 세션(당신의 세션이든 AI의 세션이든)에서 "왜 이런 방식으로 했는가"라고 물을 가능성이 있을 때만 작성하세요. 그렇지 않다면 건너뛰십시오.

시작하기

이를 위해 특별한 도구가 필요하지는 않습니다 — 네 개의 마크다운(markdown) 파일과 폴더 컨벤션(folder convention)이 시스템의 전부이며, 이는 도구에 구애받지 않습니다 (Claude Code, Codex, Cursor를 사용하든 아무것도 사용하지 않든 동일하게 작동합니다). 오늘 오후에 바로 이 네 가지 산출물의 초안을 직접 만들어 볼 수도 있습니다. 만약 빈 페이지에서 직접 초안을 잡는 대신, 수개월간의 실제 사용을 통해 이미 다듬어진 템플릿부터 시작하고 싶다면, 제가 AI Engineering Governance Kit에 패키징해 두었습니다. 어느 쪽이든 — 네 가지 산출물을 선택하고, 오늘 첫 번째 것을 작성한 뒤, 한 달 뒤에도 그것이 여전히 가치를 증명하는지 확인해 보십시오.