"왜 예전 개발자는 이 라이브러리를 썼을까?" 코드는 '어떻게'를 설명하지만, '왜'를 설명하지는 못합니다. 그 빈칸을 채우는 것이 ADR입니다.
1. ADR(Architecture Decision Record)이란?
ADR은 프로젝트의 중요한 아키텍처 결정(예: 전역 상태 관리로 Redux 대신 Zustand를 선택한 이유, 모노레포 도입 결정 등)과 그 배경, 대안, 결과를 기록한 짧은 문서입니다. 문제는 바쁜 개발자들이 코드를 짜기도 바빠서 문서화를 자꾸 미룬다는 점입니다. 결국 문서는 레거시가 되고, 컨텍스트는 증발합니다.
2. Gemini CLI가 ADR을 쓰는 방식
100만 토큰을 가진 Gemini CLI는 수천 개의 커밋 로그, PR 디스커션(GitHub MCP 연동 시), 그리고 실제 소스 코드의 의존성 변화를 한 번에 읽어들일 수 있습니다. 이를 바탕으로 과거의 결정 과정을 역추적하여 문서를 생성합니다.
gemini "@src/store @package.json 우리 프로젝트가 Redux에서 Zustand로 전환한 이유와 과정, 그리고 이로 인해 얻은 성능/코드량 이점을 분석해서 docs/adr/0005-migrate-to-zustand.md 파일로 작성해줘. 형식은 MADR(Markdown ADR) 포맷을 따라."3. 주기적인 아키텍처 감사 (Architecture Audit)
codebase_investigator 서브 에이전트를 정기적으로 실행하여, 문서(ADR)와 실제 코드 구현 간의 괴리(Drift)를 찾아냅니다.
<instruction>
`docs/adr/` 폴더의 모든 아키텍처 결정 문서들을 읽으세요.
그다음, `src/` 폴더의 실제 구현 코드를 분석하세요.
문서에 명시된 규칙(예: "모든 API 호출은 fetch-wrapper를 통한다")이 실제 코드에서 위반되고 있는 사례가 있다면 찾아내어 보고하세요.
</instruction>4. GEMINI.md와 ADR의 선순환 구조
ADR은 사람이 읽기 위한 문서입니다. 하지만 이 ADR의 요약본을 GEMINI.md에 주입하면, AI 에이전트가 코드를 짤 때 과거의 실수를 반복하지 않게 하는 가장 강력한 가드레일이 됩니다.
- 에이전트: 코드를 분석해 상세한 ADR 문서를 생성 (
docs/adr/0006-use-tailwind.md) - 인간: 생성된 ADR을 리뷰하고 승인
- 에이전트: 방금 생성된 ADR의 핵심 교훈을 추출하여
GEMINI.md의## Architecture Rules섹션에 한 줄로 자동 추가 (- 스타일링은 항상 Tailwind를 사용하며 외부 CSS 파일은 허용하지 않음. (Ref: ADR-0006))
이 루프가 완성되면, 코드가 발전할수록 프로젝트의 지식(Memory)도 스스로 팽창하고 진화하게 됩니다.
다음에 읽으면 좋은 글
- 이 자동화를 CI 환경에서 매달 실행하도록 스케줄링하기: Gemini GitHub Actions
- 대형 컨텍스트를 다루는 또 다른 방법: Gemini Effective Prompting