AI 시대의 개발 방법론 - TDD와 Clean Architecture로 Claude를 200% 활용하기
📺 원본 영상: 내년도 솔크일 형님들을 위한 코팩의 선물. 만능 Claude Skills 무료로 뿌립니다
🎙️ 채널: 코드팩토리
📅 정리 일자: 2025-01-11
⚠️ Note: 본 리포트는 영상의 음성을 텍스트로 변환(STT)하여 정리한 것입니다. 화면에 표시된 자료(차트, 코드, 슬라이드 등)는 포함되지 않을 수 있습니다.
개요
AI 개발 도구가 보편화된 지금, 단순히 AI에게 코드를 작성하게 하는 것만으로는 충분하지 않다. 진짜 중요한 것은 AI가 일관성 있고 유지보수 가능한 코드를 생성하도록 구조화된 워크플로우를 제공하는 것이다. 코드팩토리는 이번 영상에서 크리스마스 선물로 Claude Skills 기반의 “Feature Planner”를 공개하며, Test-Driven Development(TDD)와 Clean Architecture라는 두 가지 핵심 방법론이 AI 시대에 왜 더욱 빛을 발하는지 설명한다. 이 두 방법론은 과거 사람이 코딩할 때의 단점을 AI가 상쇄시키고, 장점만을 극대화할 수 있는 최적의 조합이다.
TDD(Test-Driven Development) - AI 시대에 다시 주목받는 이유
TDD의 3단계 사이클과 그 의미
Test-Driven Development는 말 그대로 테스트 코드를 먼저 작성하고 개발을 진행하는 방법론이다. 단순히 “테스트를 먼저 쓴다”는 것이 아니라, 체계적인 3단계 페이즈(Phase)로 나눠 작업을 진행한다는 점이 핵심이다.
Red Phase는 첫 번째 단계로, 실제 구현 코드가 존재하지 않는 상태에서 테스트 코드를 먼저 작성한다. 예를 들어 A + B라는 함수를 만들어야 한다면, 이 함수가 성공할 수 있는 케이스와 실패할 수 있는 케이스를 모두 테스트 코드로 먼저 정의하는 것이다. 당연히 실제 코드가 없기 때문에 모든 테스트는 실패(Failed)하게 되고, 이 때문에 “Red” Phase라는 이름이 붙었다.
Green Phase는 두 번째 단계로, Red Phase에서 작성한 테스트를 통과시키는 것만을 목표로 구현 코드를 작성한다. 이 단계에서는 코드의 품질이나 완성도보다는 “일단 테스트가 통과하는가”가 중요하다. 대충 작성하더라도 테스트만 통과하면 되기 때문에, 빠르게 기능의 뼈대를 완성할 수 있다. 테스트가 모두 성공(Pass)하면서 “Green” Phase가 된다.
Refactor Phase는 마지막 단계로, Green Phase에서 대충 작성했던 코드의 품질을 끌어올리는 작업이다. 변수명을 명확하게 바꾸거나, 로직을 더 읽기 쉽게 개선하거나, 중복 코드를 제거하는 등의 리팩터링을 진행한다. 이미 테스트가 통과하고 있는 상태이기 때문에, 리팩터링 과정에서 실수로 기능이 깨지더라도 테스트를 통해 즉시 확인할 수 있다.
AI 개발에서 TDD가 가지는 특별한 의미
과거에는 TDD의 가장 큰 단점이 “시간이 오래 걸린다”는 것이었다. 테스트 코드를 추가로 작성해야 하고, 3개의 Phase를 순차적으로 거쳐야 하며, 여러 단계를 반복해야 하기 때문이다. 그러나 AI 시대에는 이 단점이 완전히 상쇄된다. AI는 코드를 굉장히 빠르게 작성할 수 있기 때문에, TDD의 시간 소요 문제가 더 이상 문제가 되지 않는다.
오히려 TDD는 AI 개발에서 Context의 지속성이라는 결정적인 장점을 제공한다. Red Phase에서 모든 테스트 코드를 먼저 작성해두면, 이 테스트 코드 자체가 “이 기능이 어떻게 동작해야 하는지”에 대한 명확한 문서이자 Context가 된다. 만약 개발 도중 세션이 끊기거나 Context가 사라지더라도, 이미 작성된 테스트 코드를 기반으로 AI는 Implementation 코드를 어떻게 작성해야 하는지 쉽게 파악할 수 있다.
더 나아가, 나중에 대규모 리팩터링을 하거나 새로운 기능을 추가할 때도 Red Phase의 테스트 코드들이 “어떤 것을 수정해도 되고, 어떤 것을 수정하면 안 되는지”에 대한 가이드라인 역할을 한다. AI에게 이런 명확한 Context를 제공함으로써, 일관성 있고 안정적인 코드를 지속적으로 생성할 수 있게 되는 것이다.
강연자는 TDD를 사용하는 것만으로도 AI를 굉장히 효율적으로 활용할 수 있다고 강조하며, AI의 장점(빠른 코드 작성)이 TDD의 단점(시간 소요)을 완전히 상쇄하고, 오히려 장점만을 극대화할 수 있는 최적의 조합이라고 설명했다.
Clean Architecture - 컨텍스트 효율을 극대화하는 설계 전략
Layered Architecture의 한계와 Clean Architecture의 등장
일반적으로 쇼핑몰 같은 애플리케이션을 만들 때, 많은 개발자들이 Layered Architecture를 사용한다. Layered Architecture는 위에서 아래로 계층이 순차적으로 의존하는 구조로, 빠르게 초기 개발을 시작할 수 있다는 장점이 있다. 그러나 이 구조는 위에서부터 아래까지 모든 계층이 서로 강하게 결합되어 있기 때문에, 작은 코드 수정이 전체 시스템에 큰 영향(Implication)을 미칠 수 있다. 특히 큰 프로젝트에서는 어떤 하나의 기능을 변경할 때 필요한 Context가 굉장히 넓어지고, 코드의 복잡도가 기하급수적으로 증가한다.
이러한 문제를 해결하기 위해 등장한 것이 Clean Architecture다. Clean Architecture는 Hexagonal Architecture, Port and Adapter Pattern 등 비슷한 형태의 여러 아키텍처 패턴들을 통합적으로 정리한 개념이다. Clean Architecture의 핵심은 Domain 모델을 중심에 두고, 외부에서 안쪽으로 의존하게 만드는 것이다.
Layered Architecture는 상위 레이어가 하위 레이어에 의존하는 구조였다면, Clean Architecture는 반대로 외부 레이어(Infrastructure, Presentation)가 내부의 Domain 레이어에 의존한다. 이렇게 하면 외부 요소(데이터베이스, UI, 외부 API 등)가 변경되더라도, 가장 중요한 비즈니스 로직이 담긴 Domain 레이어는 영향을 받지 않도록 설계할 수 있다.
💡 [영상 참조] 강연자는 이 시점에서 Layered Architecture와 Clean Architecture의 의존성 방향을 비교하는 다이어그램을 참조합니다. 상세 내용은 원본 영상을 확인하세요.
강연자는 이를 코드 레벨에서 구현하기 위해 Dependency Inversion(의존성 역전)과 IoC Container(제어의 역전 컨테이너) 같은 기법들이 사용된다고 언급했지만, 이는 하루 종일 설명해도 VIBE 코딩 수준에서 완전히 이해하기 어렵기 때문에, 단순히 “Clean Architecture라는 키워드를 사용하면 된다”는 정도로만 이해하면 충분하다고 덧붙였다.
AI 개발에서 Clean Architecture가 가지는 의미
AI 시대에 Clean Architecture가 중요한 이유는 Context 관리의 효율성 때문이다. Layered Architecture에서는 어떤 하나의 코드를 수정했을 때 그 영향 범위를 확인하기 위해, AI가 전체 코드베이스를 다 살펴봐야 한다. 모든 계층이 서로 연결되어 있고, 호출 사이클이 복잡하게 얽혀 있기 때문이다.
반면 Clean Architecture는 Domain 영역을 중심으로 의존성이 한 번 끊긴다. 외부 레이어가 Domain에 의존하지만, Domain은 외부를 알지 못한다. 이런 구조 덕분에 Context를 나눠서 작업하더라도 굉장히 높은 완성도의 코드를 생성할 수 있다. 아무리 큰 프로젝트라도 Context를 효율적으로 소비하면서, 마치 레고 블록을 쌓아가는 느낌으로 코딩할 수 있게 된다.
강연자는 특히 “VIBE 코딩 초보”들이 가장 많이 겪는 문제로 두 가지를 꼽았다. 첫째는 Context가 부족하다는 것이고, 둘째는 뭔가 하나를 바꾸면 다른 것들이 다 깨져버린다는 것이다. 이럴 때 Clean Architecture를 사용하면 굉장히 높은 만족도를 얻을 수 있다고 강조했다.
Feature Planner - TDD와 Clean Architecture를 자동화하는 Claude Skill
Feature Planner의 구조와 설계 철학
강연자가 공개한 Claude Skill의 이름은 Feature Planner다. 이 Skill은 새로운 기능을 계획하고 구현할 때 TDD와 Clean Architecture 방법론을 자동으로 적용해주는 도구다. 약 300줄 분량의 프롬프트로 구성되어 있으며, 크게 세 가지 핵심 요소를 담고 있다.
첫째, Test-Driven Development 워크플로우다. Red Phase, Green Phase, Refactor Phase를 어떤 순서로, 어떤 기준으로 진행해야 하는지 구체적으로 명시되어 있다. 단순히 “테스트를 먼저 작성하라”는 추상적인 지시가 아니라, 각 Phase에서 어떤 작업을 해야 하고, 어떤 Quality Gate를 통과해야 다음 단계로 넘어갈 수 있는지까지 상세하게 정의되어 있다.
둘째, 폴더 구조와 아키텍처 가이드다. Feature Planner는 프로젝트의 폴더 구조를 미리 정의하고, 각 계획 문서를 특정 패턴에 따라 관리할 수 있도록 설정되어 있다. 아키텍처 부분은 의도적으로 추상적으로 남겨두었는데, 이는 Clean Architecture뿐만 아니라 다른 아키텍처를 사용하고 싶은 경우도 있을 수 있기 때문이다. 사용자가 “Clean Architecture로 플랜해줘”라고 명령하면 자동으로 Clean Architecture 구조가 적용된다.
셋째, User Approval 메커니즘이다. Claude Opus 4.5에 새로 추가된 기능으로, AI가 확신하지 못하는 부분이 있으면 사용자에게 질문을 던진다. 어떤 기술 스택을 사용할지, 어떤 구조를 선택할지 등 중요한 결정 사항들은 반드시 사용자가 직접 선택하도록 설계되어 있다. 따라서 대충 프롬프트를 입력하더라도, 꼭 필요한 결정 사항은 Claude가 물어보게 된다.
Quality Gate Standards와 Progress Check
Feature Planner의 가장 중요한 부분 중 하나는 Quality Gate Standards다. 다음 작업으로 넘어가기 전에 반드시 체크해야 할 항목들이 체크리스트 형태로 정리되어 있다. 예를 들어 빌드가 성공했는지, 린트 에러가 없는지, 모든 테스트가 통과했는지 등을 확인한 후에만 다음 Phase로 진행할 수 있다. 만약 에러가 발생하면 리팩터링을 진행하도록 명시되어 있다.
또한 Progress Check 시스템도 구축되어 있다. 각 Phase별로 예상 시간, 현재 상태(대기 중/작업 중/완료), 그리고 작업 체크박스가 제공된다. 모든 체크박스를 완료한 후에야 다음 Phase로 넘어갈 수 있도록 Instruction이 작성되어 있어, AI가 중간 단계를 건너뛰는 일이 없도록 방지한다.
Rollback Strategy와 테스트 분류
만약 작업 도중 문제가 발생했을 때를 대비한 Rollback Strategy도 포함되어 있다. 어떤 시점으로 돌아가야 하는지, 어떤 기준으로 작업을 되돌려야 하는지에 대한 가이드라인이 제공된다.
테스트는 세 가지 카테고리로 분류된다. Unit Test(개별 함수나 메서드 단위 테스트), Integration Test(여러 컴포넌트 간 상호작용 테스트), End-to-End Test(전체 시스템 플로우 테스트)로 나뉘며, 각각을 어떤 기준으로 작성해야 하는지 예제와 함께 상세하게 설명되어 있다.
PlanTemplate.md와 Context 최적화
Feature Planner의 또 다른 강점은 PlanTemplate.md 파일을 활용한 Context 최적화다. Claude Skills의 특징 중 하나는 다른 문서를 링크로 연결했을 때, 해당 문서가 항상 Context를 차지하는 것이 아니라 진짜 필요할 때만 Context를 소비한다는 점이다. PlanTemplate.md는 계획 문서의 기본 구조를 정의하고 있으며, Feature Planner Skill을 실행하면 이 템플릿을 기반으로 Markdown 파일이 자동 생성된다.
템플릿에는 어떤 Phase들을 구현해야 하는지, Quality Gate를 어떻게 체크해야 하는지, 각 단계별로 어떤 작업이 필요한지 등이 모두 포함되어 있다. 따라서 한 번 계획 문서가 생성되면, 그 안에 모든 Context가 담겨 있어 여러 세션에 걸쳐 작업하더라도 일관성을 유지할 수 있다.
실전 활용 예시 - 쇼핑몰 사이트 개발 계획
Feature Planner 실행 과정
강연자는 실제 사용 예시로 쇼핑몰 사이트 개발을 계획하는 과정을 시연했다. 명령어는 굉장히 간단하다.
Feature Planner 스킬을 사용해서 Clean Architecture 구조를 사용해서 쇼핑몰 사이트를 계획해줘. 한글로 작성해줘.
이 한 줄만 입력하면, Claude는 자동으로 Feature Planner Skill을 실행하고, 사전에 정의된 폴더 위치에 계획 문서를 생성한다. 강연자는 영어에 자신 있다면 영어로 작성하는 것이 더 효율적이라고 조언했지만, 가독성을 위해 한글로 요청했다.
💡 참고: 강연자는 처음에 Clean Architecture 지시를 깜빡하고 명령을 실행했다가, “Yes C” 명령으로 취소한 후 다시 입력했다고 언급했다.
생성된 계획 문서의 구조
생성된 계획 문서는 매우 체계적으로 구성되어 있다. 문서의 제목은 “쇼핑몰 사이트 개발”이며, 상단에는 생성 일자와 마지막 업데이트 일자가 표시된다. 예상 소요 시간도 기록되는데, 이는 작업을 시작하면서 AI가 자동으로 채워 넣는다.
현재 상태(Status)는 “In Progress”로 표시되며, 작업이 완료되면 “Done”으로 변경된다. Critical Instruction 섹션에는 각 단계 완료 후 반드시 체크박스를 체크하고, 모든 품질 게이트 검증 명령어를 실행하도록 명시되어 있다. 이런 지시들이 자동으로 생성되기 때문에, 사용자는 별도로 신경 쓸 필요가 없다.
개요(Overview) 섹션에는 이 프로젝트가 어떤 것들을 구현할지, 모든 Phase가 완료되었을 때 어떤 상태를 성공으로 판단할지에 대한 기준이 명시된다. 만약 이 기준을 통과하지 못하면 다시 이전 단계로 돌아가 작업을 재진행하게 된다.
Clean Architecture 적용 결과
Architecture Decision 섹션에서는 Clean Architecture가 자동으로 적용된 것을 확인할 수 있다. 폴더 구조는 대략적으로 Domain, Application, Infrastructure, Presentation 레이어로 구성된다. 이 네 가지 폴더가 존재하면 Clean Architecture가 제대로 적용되었다고 볼 수 있다.
의존성 규칙(Dependency Rules)도 명시되어 있다. Domain 레이어를 중심으로 위아래 모든 레이어가 Domain에 의존하는 구조다. 화살표가 Domain을 향하고 있으면 제대로 설정된 것이다. 이런 구조 덕분에 외부 레이어의 변경이 Domain 로직에 영향을 미치지 않게 된다.
Phase별 상세 계획
계획 문서의 핵심은 Phase별 상세 구현 계획이다. 각 Phase는 예상 시간, 현재 상태(대기 중/작업 중/완료), 그리고 구체적인 작업 내용으로 구성된다.
Phase 1은 프로젝트 초기화 단계다. 흥미로운 점은 Red Phase가 생략되고 바로 Green Phase로 시작한다는 것이다. 프로젝트 초기화는 테스트 코드를 작성할 수 없기 때문에, AI가 스스로 판단해서 Green Phase만 진행하도록 계획을 수정한다. 이 Phase에서는 프로젝트 구조 설정, 의존성 설치, 기본 설정 파일 작성 등이 순서대로 나열된다.
Phase 2로 넘어가기 전에는 Quality Gate를 통과해야 한다. 빌드가 성공했는지, 린트 에러가 없는지, 테스트가 통과했는지 등을 확인한다. Next.js가 아닌 다른 프레임워크를 사용하더라도, AI가 자동으로 리서치해서 해당 프레임워크의 빌드 명령어, 린트 명령어, 테스트 명령어를 찾아 반영한다.
Phase 2부터는 실제 코드 작성이 시작된다. Clean Architecture이기 때문에 Domain 계층을 가장 먼저 구현한다. 여기서 TDD의 진가가 발휘된다. Red Phase에서는 먼저 테스트 코드를 작성한다. 어디에 작성할지, 어떤 테스트 케이스를 다룰지가 모두 문서에 명시되어 있다.
이렇게 모든 것이 문서화되어 있으면, 중간에 세션이 끊기거나 Context가 부족해지더라도 문제없다. 하나의 계획 문서 안에 모든 Context가 담겨 있기 때문에, 언제든지 돌아와서 “작업하던 거 그대로 이어서 해줘”라고 하면 AI가 정확히 이어서 작업할 수 있다.
Red Phase가 끝나면 Green Phase로 넘어가 위에서 작성한 테스트를 모두 통과시키는 Implementation 코드를 작성한다. 그 다음 Refactor Phase에서 코드 품질을 높인다. 모든 작업이 끝나면 체크박스를 체크하고, Quality Gate를 다시 확인한다. 테스트가 모두 통과하는지, 코드 커버리지가 90% 이상인지(이 수치는 사용자가 조정 가능) 등을 검증한다.
사용자가 수동으로 체크해야 하는 항목들도 포함되어 있다. 예를 들어 “실제로 기능이 의도한 대로 동작하는가”와 같은 주관적 판단이 필요한 부분들이다.
Phase 3부터는 동일한 패턴이 반복된다. Red Phase → Green Phase → Refactor Phase 사이클을 거치며, 보통 하나의 기능을 구현하는 데 7개에서 11개 정도의 Phase가 생성된다. 강연자의 예시에서는 7개의 Phase가 만들어졌다.
실제 개발 시 활용 방법
명령어 하나로 시작하는 개발
계획 문서가 생성되고 나면, 실제 개발은 굉장히 간단하다. 계획 문서를 @ 기호로 태그하고, “첫 번째 Phase를 구현해줘”라고 명령하기만 하면 된다.
@plan-shopping-mall.md 첫 번째 Phase를 구현해줘
이미 계획 문서 안에 어떻게 구현해야 하는지, 어떻게 Quality Gate를 체크해야 하는지, 어떤 식으로 Progress를 관리해야 하는지가 모두 작성되어 있기 때문에, AI는 이 Context를 바탕으로 알아서 구현을 시작한다.
Context의 지속성과 재사용성
이런 Implementation Plans는 모두 TDD와 Clean Architecture를 기반으로 작성되어 있다. 따라서 Context를 효율적으로 사용하면서도, 여러 세션에 걸쳐 문맥을 이어갈 수 있다는 장점이 있다. 어제 작업하던 것을 오늘 이어서 하더라도, 일주일 뒤에 다시 돌아와도, 계획 문서만 있으면 언제든지 정확히 같은 Context에서 작업을 재개할 수 있다.
또한 프로젝트가 커질수록 여러 개의 Feature Plan이 생성될 것이다. 강연자는 이를 체계적으로 관리하기 위해 특정 폴더 패턴을 사용하도록 설정했다고 언급했다. 여러 계획 문서들이 일관된 형식으로 저장되기 때문에, 나중에 찾아보거나 비교하기도 쉽다.
마무리 - AI 시대의 개발자가 갖춰야 할 것
방법론의 중요성이 더욱 커지는 이유
과거에는 TDD와 Clean Architecture가 “이상적이지만 현실적으로 적용하기 어렵다”는 평가를 받았다. 시간이 오래 걸리고, 초기 설계 비용이 높으며, 팀원들의 이해도가 필요했기 때문이다. 그러나 AI 시대에는 이 모든 단점이 사라지고, 오히려 장점만 극대화된다.
AI는 빠르게 코드를 작성하기 때문에 TDD의 시간 소요 문제를 해결하고, Clean Architecture의 명확한 구조 덕분에 Context를 효율적으로 관리할 수 있다. 특히 “VIBE 코딩 초보”들이 겪는 두 가지 문제—Context 부족과 코드 변경 시 예상치 못한 사이드 이펙트—를 동시에 해결할 수 있는 최적의 조합이다.
크리스마스 선물, 그리고 지속적인 학습
강연자는 이 Feature Planner Skill을 GitHub 레포지토리로 공유한다고 밝혔다. 크리스마스를 맞아 무료로 배포하는 이 도구를 통해, 많은 개발자들이 AI를 더 효율적으로 활용하고, 더 나은 코드를 작성할 수 있기를 바란다고 전했다.
또한 TDD와 Clean Architecture는 각각 10시간 이상의 강의 분량이 나올 정도로 깊은 주제이기 때문에, 관심 있는 사람들은 꼭 깊게 배워볼 것을 권장했다. 제대로 배우고 나면 코딩 인생이 바뀔 것이라고 강조하며, 이번 영상은 그 시작점이 될 수 있다고 덧붙였다.
마지막으로 강연자는 구독, 좋아요, 알림 설정을 부탁하며, 모두에게 즐거운 크리스마스가 되길 바란다는 인사로 영상을 마무리했다.
📚 출처 및 참고
| 구분 | 내용 |
|---|---|
| 원본 영상 | 내년도 솔크일 형님들을 위한 코팩의 선물. 만능 Claude Skills 무료로 뿌립니다 |
| 채널 | 코드팩토리 |
| 리포트 작성 | 2025-01-11 |
| 작성 방식 | YouTube 영상 STT 변환 후 에디팅 |
💬 본 리포트는 영상 내용을 바탕으로 재구성되었습니다. Feature Planner Skill의 실제 코드와 상세한 사용법은 원본 영상과 강연자가 공유하는 GitHub 레포지토리를 참조해 주세요.