d01 - 클린 아키텍처 개념과 이점

부록 A · 클린 아키텍처 — 개념·정의·목적과 AI 시대의 이점

심화 reading (3교시 보충 자료) 3교시가 "손으로 적용하는 법"이라면, 이 부록은 "왜 그렇게 하는가"의 배경과, 이 과정의 두 주제(AI 에이전트·바이브 코딩)에 주는 이점을 깊이 있게 정리합니다.

 

---

1. 클린 아키텍처란 무엇인가 — 개념과 정의

클린 아키텍처(Clean Architecture) 는 로버트 C. 마틴(Robert C. Martin, 통칭 'Uncle Bob')이 2012년 블로그 글과 2017년 동명의 저서에서 정리한 소프트웨어 구조 설계 원칙입니다. 그는 새로운 패턴을 발명했다기보다, 그 전부터 있던 여러 아키텍처 — 육각형 아키텍처(Hexagonal, Ports & Adapters), 양파 아키텍처(Onion), BCE, DCI 등 — 가 공통적으로 말하는 하나의 핵심을 통합·일반화했습니다.

그 하나의 핵심은 다음 한 문장으로 압축됩니다.

"세부사항(프레임워크·DB·UI·외부 서비스)에 비즈니스 규칙이 의존하게 하지 말고, 그 반대로 만들어라."

 

즉 클린 아키텍처는 코드를 동심원으로 된 계층으로 나누고, 모든 의존성이 바깥에서 안쪽(핵심)으로만 향하도록 강제하는 설계 방식입니다. 안쪽에는 "거의 바뀌지 않는 비즈니스 규칙"을, 바깥에는 "자주 바뀌는 기술적 세부사항"을 둡니다.

정책(Policy)과 세부사항(Detail)의 분리

마틴은 모든 소프트웨어를 정책과 세부사항 두 가지로 봅니다.

• 정책(Policy): 그 소프트웨어가 존재하는 이유 — 비즈니스 규칙과 절차. (예: "매출액 = 수량 × 단가", "잘못된 행은 제외하고 보고한다")
• 세부사항(Detail): 정책을 세상과 연결하는 수단. DB가 PostgreSQL인지 SQLite인지, 화면이 웹인지 CLI인지, AI 모델이 무엇인지 — 이런 것은 정책 입장에서 '어쩌다 그렇게 된 결정' 일 뿐입니다.

마틴의 유명한 표현으로 "데이터베이스는 세부사항이다", "웹은 세부사항이다", "프레임워크는 세부사항이다" 가 있습니다. 핵심 비즈니스 규칙은 이런 세부사항을 몰라야 하고, 따라서 세부사항이 바뀌어도 흔들리지 않아야 한다는 뜻입니다.

---

2. 클린 아키텍처의 목적 — 왜 이렇게 하는가

마틴은 소프트웨어 아키텍처의 목표를 명확히 규정합니다.

"아키텍처의 목표는 시스템을 만들고 유지하는 데 드는 인력(비용)을 최소화하는 것이다."

 

즉 아키텍처는 "멋진 그림"이 아니라 경제적 목적을 가집니다. 잘 설계된 구조는 다음을 가능하게 해 비용을 낮춥니다.

1. 변경 비용 최소화 — 요구사항은 반드시 바뀝니다. 좋은 구조는 변경이 국소적으로만 영향을 미치게 합니다. 한 곳을 고쳐도 시스템 전체가 무너지지 않습니다.
2. 결정의 지연(Deferring decisions) — 마틴은 "좋은 아키텍처는 중요한 결정을 최대한 미룰 수 있게 한다"고 말합니다. DB·프레임워크·외부 서비스 선택 같은 결정을 나중으로 미루고, 핵심 로직을 먼저 만들 수 있습니다. 미룬 결정은 더 많은 정보를 가진 상태에서 더 잘 내릴 수 있습니다.
3. 독립성(Independence) — 클린 아키텍처가 추구하는 시스템은 다음으로부터 독립적입니다.
   • 프레임워크 독립: 특정 프레임워크에 갇히지 않는다.
   • 테스트 가능: UI·DB·웹서버 없이 비즈니스 규칙을 테스트할 수 있다.
   • UI 독립: 화면을 통째로 바꿔도 규칙은 그대로.
   • DB 독립: 데이터 저장소를 바꿔도 규칙은 그대로.
   • 외부 세계 독립: 비즈니스 규칙은 바깥세상을 전혀 모른다.

🎯 한 줄 요약: 클린 아키텍처의 목적은 "변화에 드는 비용을 낮추는 것"이고, 그 수단은 "핵심(정책)을 세부사항으로부터 격리하는 것"입니다.

보너스 개념 — "스크리밍 아키텍처(Screaming Architecture)"

마틴은 좋은 구조라면 폴더 구조만 봐도 "이 시스템이 무엇을 하는 시스템인지"가 소리쳐야(scream) 한다고 말합니다. 예를 들어 폴더 이름이 Spring, React, MySQL이면 사용한 기술만 보일 뿐 무엇을 하는 앱인지 알 수 없습니다. 반면 usecases/analyze_sales.py, domain/SalesRecord 같은 구조는 "매출을 분석하는 시스템"임을 스스로 드러냅니다. 본 과정의 폴더 구조가 정확히 이 원칙을 따릅니다.

---

3. 핵심 원리 요약 (3교시와 연결)

세부 적용은 3교시에서 다루므로, 여기서는 네 가지 기둥만 정리합니다.

기둥	내용
4계층	(안쪽부터 바깥쪽 순 나열) Entities(엔티티) / Use Cases(유스케이스) / Interface Adapters(어댑터) / Frameworks & Drivers(인프라). 안쪽일수록 핵심·불변, 바깥일수록 세부사항·교체 대상.
의존성 규칙	소스 코드 의존성은 오직 안쪽으로만 향한다: Frameworks & Drivers → Interface Adapters → Use Cases → Entities. 안쪽은 바깥을 절대 모른다.
경계(Boundary)와 DIP	안쪽이 바깥 기능을 써야 할 때는, 안쪽이 추상 인터페이스(포트) 를 정의하고 바깥이 그것을 구현(어댑터) 한다. 그래서 의존 방향과 제어 흐름 방향이 갈라진다(의존성 역전).
정책 vs 세부사항	비즈니스 규칙(정책)은 안쪽, 기술 선택(세부사항)은 바깥.

📝 용어 참고: "포트/어댑터"라는 짝 명칭의 원조는 Hexagonal Architecture입니다(3교시 용어 노트 참조). Clean Architecture는 같은 개념을 "Interface Adapters 계층 + Input/Output Port"로 부르며, 둘은 의존성 역전을 공유하는 형제지간입니다.

---

4. AI 에이전트 시스템 개발에서 주는 이점

AI 에이전트 시스템에는 일반 앱과 다른 고유한 어려움이 있습니다. 클린 아키텍처는 이 어려움 하나하나에 정확히 대응합니다.

(1) 비결정성(non-determinism)을 경계에 가둔다

LLM 호출은 같은 입력에도 다른 출력을 낼 수 있고, 실패하거나, 느리거나, 비용이 듭니다. 이런 "예측 불가능한 부분"을 코드 곳곳에 흩어 두면 시스템 전체가 불안정해집니다.

클린 아키텍처는 LLM·외부 도구를 가장 바깥(어댑터/게이트웨이) 에 격리합니다. 그 결과 안쪽(유스케이스·도메인)은 완전히 결정적(deterministic) 으로 유지됩니다. 본 과정의 원칙 "숫자는 코드, 해석은 LLM" 이 바로 이 격리입니다 — 틀리면 안 되는 계산은 안쪽 결정적 코드가, 확률적 추론은 바깥 LLM 어댑터가 담당합니다.

 

(2) 빠르게 바뀌는 모델·도구를 갈아끼운다

AI 생태계는 월 단위로 바뀝니다. 모델이 교체되고, 가격이 바뀌고, 프롬프트 전략이 바뀝니다. 클린 아키텍처에서 LLM은 "세부사항" 이므로, 모델을 바꿔도 어댑터 한 곳(또는 주입 설정)만 수정하면 됩니다. 분석·리포트·화면 로직은 한 줄도 바뀌지 않습니다(13교시의 어댑터 교체 실습이 이 점을 직접 보여 줍니다).

 

(3) 토큰·네트워크 없이 테스트한다

에이전트 로직을 매번 실제 LLM으로 테스트하면 느리고, 돈이 들고, 인터넷이 없으면 실패합니다. 포트/어댑터 구조 덕분에 LLM을 가짜(Fake) 로 대체해, 에이전트의 의사결정·조율 로직만 빠르고 결정적으로, 공짜로, 오프라인에서 검증할 수 있습니다. AI 시스템에서 이 테스트 가능성은 선택이 아니라 필수입니다.

 

(4) "에이전트 = 도구 사용의 조율"이라는 본질과 맞아떨어진다

에이전트 시스템의 본질은 "여러 도구·단계를 순서대로 호출해 목표를 달성하는 것" 입니다. 이는 클린 아키텍처의 유스케이스 계층(조율자) 과 어댑터(도구) 의 관계와 정확히 일치합니다.

• 조율 로직(무엇을·어떤 순서로) → 유스케이스
• 실제 도구(검색·계산·차트·LLM·DB) → 포트 뒤의 어댑터

복잡한 에이전트 루프(도구 선택·재시도·다단계 추론)로 발전하더라도, 조율은 안쪽에, 도구는 바깥에 두는 원칙은 그대로 유지됩니다.

 

(5) 결정적 코드와 확률적 추론의 경계를 명확히 한다

신뢰할 수 있는 AI 시스템의 핵심은 "무엇을 코드에 맡기고 무엇을 모델에 맡길지"의 경계를 잘 긋는 것입니다. 클린 아키텍처는 이 경계에 자연스러운 자리를 제공합니다 — 비즈니스적으로 정확해야 하는 계산·규칙은 유스케이스/도메인에, 판단·해석·생성은 LLM 게이트웨이에. 경계가 코드 구조로 드러나므로, "어디까지가 검증된 결정적 영역인가"를 한눈에 알 수 있습니다.

 

(6) 안전성·관측성·거버넌스를 한곳에 모은다

LLM에 보내는 데이터(민감정보 필터링), 비용·토큰 로깅, 호출 제한, 가드레일 같은 안전·운영 장치를 어댑터/인프라 경계에 집중시킬 수 있습니다. "우리가 모델에 무엇을 보내는가"가 한 지점에 모여 있어 감사(audit)와 통제가 쉬워집니다. 본 과정에서 "프롬프트에 원본 CSV가 아니라 계산된 요약만 넣는다"는 결정이 게이트웨이 한곳에서 강제되는 것이 그 예입니다.

 

(7) 새 능력(도구·데이터 출처)을 안전하게 확장한다

에이전트에 새 도구나 새 데이터 출처를 붙이는 일은 새 어댑터 하나를 추가하는 일로 좁혀집니다. 기존 핵심을 건드리지 않으므로, 능력을 늘려도 시스템이 불안정해지지 않습니다(13교시 JSON 어댑터 추가가 그 예).

🤖 종합: AI 에이전트는 "불확실하고 자주 바뀌는 바깥(모델·도구)" 과 "정확해야 하는 안쪽(규칙·계산)" 이 공존하는 시스템입니다. 클린 아키텍처는 이 둘을 분리·연결하는 가장 적합한 골격을 제공합니다.

---

5. AI 코딩 에이전트(바이브 코딩)를 이용한 개발에서 주는 이점

이번엔 "AI에게 코드를 짓게 하는 개발" 자체에 클린 아키텍처가 주는 이점입니다. (GitHub Copilot 등 AI 코딩 에이전트 활용 — 12·13교시)

 

(1) 작고 명확한 단위 = 위임하기 좋은 작업

클린 아키텍처는 시스템을 작고 책임이 또렷한 단위(유스케이스 하나, 어댑터 하나)로 나눕니다. 이런 단위는 AI에게 위임하기에 이상적인 크기입니다. "이 포트를 구현하는 어댑터를 만들어 줘"는 범위가 명확하고 검증 가능한 지시입니다. 반대로 "앱 전체를 만들어 줘"는 범위가 모호해 실패합니다.

 

(2) 검증 가능성 = AI 결과를 믿을 근거

각 계층이 독립적으로 테스트 가능하므로, AI가 생성한 코드를 테스트로 즉시 검증할 수 있습니다. 이것이 이 과정의 핵심 명제 "판단할 수 있어야 위임할 수 있다" 의 기술적 토대입니다. 테스트라는 채점 기준이 있어야 AI에게 안심하고 타이핑을 맡길 수 있습니다.

 

(3) 규칙이 '강제 가능한 제약'이 된다

클린 아키텍처의 의존성 규칙은 구체적이고 검사 가능한 제약입니다 — "도메인은 외부 라이브러리를 import 하지 않는다". 이 제약은

• copilot-instructions.md에 적어 AI가 따르게 할 수 있고,
• 아키텍처 테스트(test_architecture.py)로 어기면 자동으로 깨지게 할 수 있습니다.

AI는 모호한 지시("좋은 코드를 짜라")보다 구체적 제약을 훨씬 잘 지킵니다. 클린 아키텍처는 그 구체적 제약을 풍부하게 제공합니다.

 

(4) 국소적 변경 = 작은 컨텍스트 = 낮은 위험

변경이 한 계층에 국한되므로, AI는 시스템의 작은 일부만 보고 수정하면 됩니다. AI에게 넘기는 컨텍스트가 작을수록 엉뚱한 곳을 건드리거나 환각으로 광범위한 수정을 하는 위험이 줄어듭니다. "어디를 고쳐야 하는지"가 구조로 명확하기 때문입니다.

 

(5) 회귀 안전망 = 빠른 속도의 전제

테스트가 있으면 AI의 변경을 자신 있게 수용할 수 있고, AI가 무언가를 깨뜨리면 pytest가 즉시 알려 줍니다. 테스트라는 안전망이 없으면 AI의 속도는 곧 위험입니다. 클린 아키텍처의 테스트 가능성은 바이브 코딩이 "빠르되 무너지지 않게" 하는 전제 조건입니다.

 

(6) 일관성·재현성

표준 구조 + 규칙서 + 프롬프트 템플릿이 결합되면, 세션이 달라도, 팀원이 달라도 AI가 일관된 형태의 코드를 냅니다. "무엇을 어디에 둘지"를 AI가 알기 때문입니다. 결과물의 편차가 줄어 리뷰·유지보수가 쉬워집니다.

 

(7) 사람과 AI의 역할 분담이 명확해진다

클린 아키텍처는 사람이 책임질 결정(경계 설계, 무엇을 어디에 둘지, 무엇을 테스트할지)과 AI에게 맡길 작업(경계 안에서의 구현·타이핑)의 분할선을 구조로 드러냅니다. 사람은 운전(아키텍처·검증), AI는 가속(반복 구현)이라는 분담이 자연스럽게 성립합니다.

⚡ 종합: 바이브 코딩의 위험은 "AI가 이해 못 할 코드를 빠르게 양산하는 것"입니다. 클린 아키텍처는 작은 단위·검증 가능성·강제 가능한 규칙으로 이 위험을 제거해, 바이브 코딩을 무모함이 아니라 가속으로 바꿉니다. 구조가 먼저, 속도는 그 위에서.

---

6. 한 장 요약

질문	답
클린 아키텍처란?	의존성을 안쪽(핵심)으로만 향하게 해, 비즈니스 규칙을 기술 세부사항으로부터 격리하는 설계
목적은?	변화에 드는 비용을 낮추는 것 (변경의 국소화, 결정의 지연, 프레임워크·UI·DB로부터의 독립)
AI 에이전트 개발에 왜 좋은가?	비결정적·자주 바뀌는 모델·도구를 바깥에 격리하고, 정확해야 하는 계산·규칙을 안쪽에 보호하며, 토큰 없이 테스트할 수 있게 한다
AI 코딩 에이전트 개발에 왜 좋은가?	작은 단위로 위임하고, 테스트로 검증하며, 규칙을 강제해 — AI의 속도를 안전하게 만든다
한 문장으로	"핵심을 세부로부터 지켜라. 그러면 바뀌는 세상(모델·도구·프레임워크) 속에서도 시스템이 견딘다."

---

더 읽을거리

• 본문 적용: 03_클린아키텍처_핵심이해.md (4계층·의존성 규칙·DIP를 손으로 적용)
• 구조 설계: 04_AI에이전트_구조설계.md (도메인·포트 뼈대)
• 바이브 코딩: 12_바이브코딩_도입과_재현.md, 13_바이브코딩_확장.md