• 예상 독자: Claude Code와 같은 AI 코딩 에이전트에게 단발성 작업이 아닌 수 주~수 개월에 걸친 지속적인 개발을 맡기고 있는 사람

• 전제 환경: Claude Code v2.x 계열, Git 관리 하의 리포지토리에서 CLAUDE.md를 이용한 프로젝트 지시 구성

• 특정 제품 이야기가 아닌, 여러 세션에 걸쳐 자율 구현이 가능하며 범용적으로 사용할 수 있는 '의사결정 영속화' 패턴의 구현 메모

• 자율 에이전트는 세션이 끊길 때마다 문맥을 잃는다. 방치하면 '지난번 기각한 안'을 재제안하거나, 같은 설계를 두고 여러 번 같은 논의를 반복한다.

• 대책은 ADR(Architecture Decision Record)을 Markdown으로 순차적으로 관리하고, 모순될 때 어떤 것을 믿을지 우선순위를 명문화하는 것만으로 충분하다. 특별한 도구는 필요 없다.

• 다만 '업데이트 누락', '모순 방치', '로그 비대화'의 3가지 함정에 빠졌기 때문에 회피책까지 포함하여 작성한다.

## ADR-0042: 재시도는 지수 백오프(Exponential Backoff) + 지터(Jitter)로 통일
- 배경: 단순한 고정 간격 재시도로 429 에러가 연발했음
- 결정: base=1s, factor=2, jitter=0.3으로 통일. 호출하는 쪽에서 개별 구현하지 않음
...

순번을 매기면 나중에 Claude 자신이 'ADR-0038의 내용'처럼 참조할 수 있게 된다. 순번은 파일 내에서 단순히 증가시키기만 하면 되므로 특별한 메커니즘이 필요 없다.

여러 문서가 모순된 기술을 포함하는 것은 피하기 어렵기 때문에, Claude가 혼란스러워하지 않도록 우선순위를 CLAUDE.md에 한마디 적어두는 것이 좋다.

우선순위: 현재 위치(최근 상황을 작성한 파일) > 방침 > 과거 결정 로그

새로운 세션 시작 시

우선순위 명문화라는 사소한 메커니즘만으로 재질문이나 모순의 상당 부분을 막을 수 있었다. 로그가 늘어나면 '현재 위치'와 '이력(History)'을 분리하는 것이 효과적이다. 하나의 파일에 계속 기록하면 반드시 컨텍스트를 압박하게 된다.

기록 누락 방지 대책은 '생각날 때 적는다'가 아니라 '세션 종료 조건에 포함시키는 것'이 효과적이었다.