Your Decision Log Is an Archaeological Site

Context

AI 코딩 에이전트와 인간 개발자 모두 계속 증가하는 ADR 파일 더미를 읽어야 현재 아키텍처 상태를 파악해야 했다. docs/decisions/ 디렉토리에 40개 파일이 축적되었으나 실제로 유효한 결정은 5개뿐이고 나머지는 폐기된 아이디어, 제거된 제약사항, 재논의된 결정 등 역사적 노이즈였다.

Technical Solution

• ADR 파일 시스템을 폐지하고 저장소 루트의 단일 DESIGN.md 파일로 통합: Architecture, Decisions, Constraints 3개 섹션만 유지
• DESIGN.md에 100줄 하드 캡 설정: 파일이 가득 차면 현재 유효한 결정만 남기고 더 이상 영향을 주지 않는 항목 제거
• 결정 항목을 1~2줄로 제한: 결정 내용과 그것이 여전히 필요한 이유만 포함 (예: "Redis for score caching, not DB reads: Scores change every 5 min via worker; cache hit target is <50ms")
• 비즈니스 로직 관련 결정 컨텍스트를 코드 내 인라인 주석으로 이동: 함수 구조나 캐싱 레이어의 비자명한 이유를 결정 문서 대신 코드 옆에 배치
• Git 히스토리를 결정의 감사 추적으로 활용: 커밋 메시지에 변경 사유를 기록하고 git blame으로 특정 코드 변경과 결정 연결

Impact

아티클에서 정량적 수치를 제시하지 않음. 단, 새 입사자나 일주일 후 복귀한 개발자가 DESIGN.md를 2분 내에 읽고 현재 코드 형태가 왜 그렇게 설계되었는지 이해할 수 있는 것을 성공 지표로 제시.

Key Takeaway

아키텍처 결정 기록은 감시 가능성과 사용성 사이의 트레이드오프에서 감시 가능성을 우선시했으나, 실제로는 활용도가 낮은 누적 문서보다 현재 유효한 결정만 간결하게 유지하면서 Git 히스토리로 역사를 추적하는 것이 소규모 팀과 개인 프로젝트에 더 효과적이다.