생성형 AI (Generative AI)를 사용하면 설계안, 기술 선정, 비교표, 초안 작성이 매우 빨라집니다.

반면, AI가 내놓은 안을 그대로 채택하면 "왜 그런 판단을 했는가"가 모호해지기 쉽습니다.

그래서 도움이 되는 것이 ADR (Architecture Decision Record) 입니다.

ADR은 중요한 아키텍처상의 의사결정에 대해 배경, 결정 내용, 결과를 가볍게 기록하는 수법입니다. Thoughtworks도 중요한 아키텍처 판단을 컨텍스트 및 결과와 함께 기록하여 소스 관리(Source Control)에 두는 것을 권장하고 있습니다. (Thoughtworks)

상정 독자: AI를 개발, 설계, 기술 선정에 사용하기 시작한 엔지니어, PM, 테크 리드, 정보 시스템 담당자.

• AI를 사용하여 설계안이나 기술 선정의 초안을 만들고 있는 사람

• 기술 선정의 이유가 팀 내에 남지 않아 곤란했던 경험이 있는 사람

• "왜 이 설계로 했는가"를 나중에 설명할 수 있게 하고 싶은 사람

• ADR에 대해 들어본 적은 있지만, 어떻게 사용해야 할지 망설여지는 사람

• AI 활용과 거버넌스(Governance)의 균형을 맞추고 싶은 사람

• ADR의 기본적인 사고방식

• AI와 ADR을 조합했을 때의 장점

• AI에게 맡겨도 되는 부분, 인간이 판단해야 할 부분

• ADR의 심플한 템플릿

• AI를 사용하여 ADR을 작성 및 리뷰하는 흐름

• AI 활용 시 발생하기 쉬운 함정과 대책

이 기사에서는 특정 클라우드나 라이브러리에 의존하지 않습니다.

ADR은 도구보다 의사결정을 남기는 습관이 중요합니다. Microsoft의 Azure Well-Architected Framework에서도 ADR은 의사결정, 정당화 이유, 영향을 문서화하기 위한 산출물로 설명되어 있습니다. (Microsoft Learn)

AI와 ADR의 관계는 다음과 같이 정리할 수 있습니다.

포인트는 AI는 의사결정자가 아니라, 의사결정을 지원하는 존재로 다루는 것입니다.

AI에는 다음과 같은 작업이 적합합니다.

• 선택지 도출
• 비교 관점 정리
• 장점·단점의 초기 정리
• ADR 초안 작성
• 누락 체크
• 상정 리스크 도출

반면, 다음의 판단은 인간이 책임을 가져야 합니다.

• 사업상의 우선순위
• 보안·법무·컴플라이언스 (Compliance) 판단
• 비용 허용도
• 팀의 스킬이나 운용 체제
• 최종적인 채택·불채택 판단

ADR은 Architecture Decision Record의 약자입니다.

직역하면 "아키텍처상의 의사결정 기록"입니다.

대략 말하자면, ADR은 다음 질문에 답하기 위한 문서입니다.

왜 그 설계·기술·방침을 선택했는가?

예를 들어, 다음과 같은 판단을 기록합니다.

• 왜 REST API가 아니라 GraphQL을 채택했는가
• 왜 RDB가 아니라 문서형 DB (Document DB)를 사용하는가
• 왜 마이크로서비스 (Microservices)화 하지 않는가
• 왜 RAG 구성을 채택하는가
• 왜 특정 LLM API가 아니라 프라이빗 LLM을 사용하는가
• 왜 온프레미스 (On-premise)가 아니라 클라우드를 사용하는가

ADR의 대표적인 형식에서는 Status, Context, Decision, Consequences 등을 기록합니다. Michael Nygard의 원문에서도 상태, 배경, 결정, 결과를 기술하는 구성을 제시하고 있습니다. (Michael Nygard)

AI를 사용하면 설계안을 내놓는 속도는 올라갑니다.

하지만 속도가 올라갈수록 다음과 같은 문제도 발생하기 쉽습니다.

• AI가 내놓은 안을 충분히 검증하지 않고 채택해 버린다
• 판단 이유가 채팅 이력 속에 묻혀버린다
• 나중에 보는 사람이 "왜 이렇게 했는지"를 이해할 수 없다
• 여러 안의 비교 과정이 남지 않는다
• AI의 답변에 포함된 전제 오류를 알아차리기 어렵다

특히 위험한 것은 AI의 답변이 그럴싸해 보인다는 점입니다.

AI는 그럴듯한 비교표나 아키텍처 안을 빠르게 만들 수 있습니다.

하지만 그 안이 자사의 제약, 기존 시스템, 팀 체제, 예산, 보안 요구사항에 맞다는 보장은 없습니다.

그래서 ADR을 사용합니다.

ADR에 담아냄으로써, AI가 내놓은 안을 다음과 같이 검증할 수 있습니다.

즉 ADR은 AI 활용에 있어서 **판단의 로그 (Log)**가 됩니다.

AI와 ADR을 조합할 때는 실무상의 한 예로서, 역할을 명확히 나누면 운용하기 쉬워집니다.

AI는 "생각할 재료"를 늘리는 데 능숙합니다.

인간은 "현실적인 제약 사항을 고려하여 결정하는" 역할을 담당합니다.

이 분담을 모호하게 하면, AI에게 판단을 통째로 떠넘기게 됩니다.

반대로 분담을 명확히 하면, AI는 매우 강력한 설계 보조 도구가 됩니다.

우선은 심플한 ADR부터 시작하는 것을 추천합니다.

# ADR-001: <결정의 제목>
## Status
Proposed / Accepted / Deprecated / Superseded
...

보다 구조화된 템플릿을 사용하고 싶다면, MADR (Markdown Architectural Decision Records)도 후보가 될 수 있습니다. MADR는 아키텍처상 중요한 의사결정을 Markdown으로 구조적으로 기록하기 위한 템플릿으로 제공됩니다. (Architectural Decision Records)

AI를 사용할 경우, 갑자기 "ADR을 써줘"라고 요청하기보다 단계를 나누는 것이 정확도를 높일 수 있습니다.

먼저, AI에게 판단을 시키는 것이 아니라 과제를 정리하게 합니다.

다음 상황을 바탕으로, 기술적 판단에서 정리해야 할 논점(Issues)을 도출해 주세요.
상황:
- 사내 문서 검색을 개선하고 싶다
...

여기서는 AI에게 "정답"을 내게 하는 것이 아니라, 논점을 늘리는 것을 목적으로 합니다.

다음으로, 여러 안을 비교하게 합니다.

다음 선택지들을 보안, 비용, 구현 난이도, 운영 부하, 확장성 관점에서 비교해 주세요.
선택지:
1. 기존 검색 방식을 유지하며 개선한다
...

이 단계에서는 AI의 비교 결과를 무비판적으로 수용하지 않는 것이 중요합니다.

AI가 내놓은 비교표는 리뷰를 위한 재료입니다.

AI의 출력을 바탕으로 팀에서 판단합니다.

확인해야 할 관점은 다음과 같습니다.

• 자사의 보안 요구사항에 부합하는가
• 운영할 수 있는 인력이 있는가
• 장애 발생 시 대응 가능한가
• 비용이 허용 범위 내인가
• 향후 확장에 견딜 수 있는가
• 지금 해야 할 판단인가, 아니면 미룰 수 있는가

여기서 중요한 것은 정답을 고르는 것이 아니라, 현 시점의 제약 조건 하에서 타당한 판단을 하는 것입니다.

판단이 확정되면, AI에게 ADR 초안을 작성하게 합니다.

다음 정보를 바탕으로 ADR 초안을 Markdown 형식으로 작성해 주세요.
결정:
- 사내 문서 검색에 RAG 구성을 채택한다
...

마지막으로, AI에게 ADR을 리뷰하게 합니다.

다음 ADR을 리뷰해 주세요.
관점:
- 배경과 결정이 대응하고 있는가
...

AI를 통한 리뷰는 누락된 부분을 찾아내는 데 유효합니다.

단, 최종 승인은 팀 내 책임자가 수행합니다.

다음은 AI 활용을 전제로 한 ADR 샘플입니다.

# ADR-001: 사내 문서 검색에 RAG 구성 채택
## Status
Accepted
...

이렇게 작성해 두면, 나중에 보는 사람이 "왜 RAG를 채택했는지", "어떤 리스크를 수용했는지"를 이해할 수 있습니다.

AI와 ADR을 잘 조합하려면 다음과 같은 운용 방식이 유효합니다.

특히 추천하는 방식은 Pull Request와 ADR을 연결하는 운용입니다.

docs/adr/
001-use-rag-for-internal-search.md
002-use-managed-vector-database.md
...

Git으로 관리해 두면 코드 변경과 설계 판단의 이력을 가까운 곳에 남길 수 있습니다. adr-tools와 같이 ADR을 커맨드 라인에서 관리하기 위한 도구도 존재합니다. (GitHub)

AI의 문장은 정돈되어 보입니다.

하지만 정돈되어 있는 것과 올바른 것은 별개입니다.

대책

• AI의 출력은 초안으로 취급한다
• 자사의 제약 사항을 반드시 추가한다
• 판단자 및 리뷰자를 명확히 한다
• 불분명한 점은 "불분명"이라고 적는다

ADR은 품의서나 홍보 자료가 아닙니다.

채택한 기술의 장점만 적으면, 나중에 판단을 재검토할 수 없게 됩니다.

대책

• 단점을 반드시 적는다
• 채택하지 않은 선택지도 적는다
• "무엇을 포기했는지"를 명시한다

하나의 ADR에 여러 판단을 몰아넣으면 나중에 읽기 어려워집니다.

나쁜 예:

AI 검색 기반, 클라우드, DB, 인증, 모니터링 방식을 한꺼번에 결정함

좋은 예:

ADR-001: 사내 검색에 RAG (Retrieval-Augmented Generation) 구성을 채택한다
ADR-002: 벡터 DB (Vector DB)로 매니지드 서비스 (Managed Service)를 이용한다
ADR-003: 답변 생성 전에 문서 권한 체크를 수행한다
...

대책

• 1 ADR = 하나의 의사결정으로 한다
• 망설여진다면 분할한다
• 나중에 교체하기 쉬운 입도 (Granularity)로 한다

ADR은 의사결정의 이력입니다.

과거의 판단을 직접 계속해서 고쳐 쓰면, 당시의 판단 이유가 사라져 버립니다.

대책

• 판단이 바뀌면 새로운 ADR을 만든다
• 오래된 ADR은 Deprecated (사용 중단) 또는 Superseded (대체됨) 상태로 만든다
• 신구 ADR을 상호 링크한다

예시:

## Status
Superseded by ADR-007

"AI가 그렇게 말했으니까"라는 이유는 설계 판단에 대한 설명이 되지 않습니다.

대책

• ADR 내에 AI 이용 여부를 작성한다
• AI가 내놓은 안을 누가 리뷰했는지 남긴다
• 최종 판단자를 명확히 한다
• 중요한 판단에서는 인간의 리뷰를 필수적으로 한다

기재 예시:

## AI Usage
본 ADR의 초기 안 작성에 생성형 AI를 사용하였다.
최종 판단은 아키텍트 및 개발 팀에서 리뷰하고 승인하였다.

AI 시대의 설계에서는 답을 빠르게 내는 것뿐만 아니라, 왜 그 답을 선택했는지를 남기는 것이 중요합니다.

이 기사의 요점은 다음과 같습니다.

• ADR은 아키텍처상의 의사결정을 남기는 경량 문서이다
• AI는 선택지 도출이나 초안 작성에 유효하다
• 최종 판단은 인간이 책임을 진다
• ADR에는 배경, 선택지, 결정, 이유, 결과를 작성한다
• AI의 출력을 그대로 채택하지 말고, 제약 사항이나 리스크를 명기한다
• 판단이 바뀌면 과거의 ADR을 고쳐 쓰는 것이 아니라 새로운 ADR을 만든다

우선, 다음의 한 가지만이라도 시작하면 효과가 있습니다.

다음에 큰 기술 선정을 할 때, ADR을 딱 한 장만 써본다

AI로 설계안을 내고, ADR로 판단을 남긴다.

이 조합은 개발 속도와 설명 책임 (Accountability)을 양립하기 위한 현실적인 접근 방식입니다.

• Thoughtworks: Lightweight Architecture Decision Records (Thoughtworks)
• Microsoft: Maintain an architecture decision record (Microsoft Learn)
• MADR: Markdown Architectural Decision Records (Architectural Decision Records)
• adr-tools: Command-line tools for working with Architecture Decision Records (GitHub)

면책 사항: 본 기사는 필자가 확인한 시점의 정보에 기반한 참고 정보이며, 정확성·완전성·최신성을 보장하지 않습니다. 이용으로 인해 발생하는 어떠한 손해에 대해서도 필자는 책임을 지지 않습니다.