AI 코딩 및 에이전트를 위한 최고의 코드베이스 아키텍처 (Aider, Claude Code, Cursor)

IndyDevDan 구독자 43,800명

요약

이 영상은 AI 코딩 도구와 에이전트가 코드를 생성하는 시대에 대비하여, 코드베이스를 어떻게 최적화할 것인지 논의한다. 토큰 효율성을 극대화하고, AI 도구가 빠르게 이해하고 실행할 수 있도록 여러 아키텍처 패턴—아토믹 컴포저블, 레이어드, 수직 슬라이스, 파이프라인, 그리고 싱글 파일 에이전트—의 장단점을 분석한다. 각각의 구조는 재사용성, 모듈화, 테스트 용이성 등에서 차이를 보이며, AI 도구들의 컨텍스트 관리와 실행 효율성을 개선하는 데 초점을 맞춘다. 마지막으로 향후 AI 코딩 환경에서 효과적으로 경쟁할 수 있는 디자인 패턴과 접근법에 대해 전망과 실전 팁을 제시합니다.

주요 키워드

AI 코딩 코드베이스 아키텍처 토큰 효율성 아토믹 컴포저블 레이어드 아키텍처 수직 슬라이스 파이프라인 싱글 파일 에이전트 컨텍스트 관리 에이전트 개발

하이라이트

🔑 AI 코딩 시대의 도래와 함께, 코드베이스를 토큰 효율적으로 설계해야 한다는 점을 강조합니다.
⚡️ 아토믹 컴포저블 아키텍처는 작은 단위(아톰, 분자, 유기체, 멤브레인)로 구성되어 재사용성과 테스트 용이성이 높으나, 수정 시 체인 반응 문제가 발생할 수 있음을 지적합니다.
🌟 레이어드 아키텍처는 명확한 관심사의 분리를 제공하지만, AI 도구가 여러 디렉터리와 파일을 동시에 로드해야 하는 단점이 있습니다.
📌 수직 슬라이스 아키텍처는 기능별로 코드를 분리해 컨텍스트 프라이밍을 단순하게 만들어, 토큰 절감과 빠른 코드 분석에 유리합니다.
🚀 파이프라인 및 싱글 파일 에이전트 설계는 순차 처리와 간결한 구조를 통해 AI 에이전트 개발에 최적의 환경을 제공한다고 설명합니다.
🔑 전체적으로, 코드를 AI 도구가 쉽게 파악할 수 있도록 구조화하는 것이 장기적으로 개발 효율과 비용 절감에 큰 영향을 미친다는 메시지를 전달합니다.

용어 설명

아토믹 컴포저블 아키텍처

작은 단위(아톰, 분자, 유기체, 멤브레인)로 구성하여 재사용성과 테스트 용이성을 높이는 구조. UI 컴포넌트부터 전체 시스템까지 다양한 수준에서 적용됨.

레이어드 아키텍처

기능별 폴더와 디렉터리(예: API, 모델, 비즈니스 로직 등)를 통해 관심사를 분리하여 코드를 구성하는 전통적인 아키텍처.

수직 슬라이스 아키텍처

기능별(또는 특징별)로 코드를 조직하여 관련된 모든 파일과 모듈을 하나의 슬라이스로 관리, 컨텍스트 프라이밍과 토큰 효율성을 높임.

파이프라인 아키텍처

기능 또는 데이터 처리 단계가 순차적으로 연결되어 각 단계에서 데이터를 처리하는 방식으로, 주로 데이터 파이프라인 및 ML Ops에 활용됨.

싱글 파일 에이전트

에이전트의 모든 기능을 한 파일 내에 집약하여 단일 컨텍스트 프라임팅으로 빠르게 실행할 수 있도록 하는 구조.

컨텍스트 관리

AI 도구가 코드를 실행할 때 필요한 정보를 최적화하여 토큰 사용을 줄이고, 효율적으로 코드를 분석 및 실행하게 만드는 설계 원칙.

[00:00:00] 서론 및 중요성

AI 코딩 도구가 곧 코드를 작성하게 될 미래를 대비하여 최적의 코드베이스 아키텍처 설계가 필요함을 소개합니다. 토큰 효율성과 AI 도구의 컨텍스트 관리의 중요성을 강조합니다.

[00:02:09] 아토믹 컴포저블 아키텍처

아톰, 분자, 유기체, 멤브레인 등의 작은 단위로 구성된 아키텍처의 구조와 재사용성, 테스트 용이성 등 장점을 설명합니다. 단, 하위 단위 수정 시 연쇄적 영향 문제를 지적합니다.

[02:09] 원자적 조합 아키텍처는 재사용성이 높고 관심사가 명확히 분리되어 있어, AI 도구가 쉽게 이해할 수 있는 구조를 제공합니다.

[03:01] Brad Frost의 원자 디자인 프레임워크에서 시작된 이 개념은 이제 전체 엔지니어링 스택에서 널리 사용되고 있습니다.

[03:19] 자연의 구조처럼 작은 단위(원자)가 더 큰 단위(분자, 유기체)를 구성하는 방식으로 코드를 구성할 수 있으며, 이는 멤브레인과 생태계 수준까지 확장 가능합니다.

[03:40] 이 아키텍처의 가장 큰 장점은 테스트가 용이하다는 것입니다. pocket pick이라는 MCP 서버를 예로 들어 설명하겠습니다.

[04:00] Source 디렉토리는 깔끔한 원자적 구조를 가지고 있으며, modules는 단일 추상화 계층으로 구성되어 있고, 이는 MCP 서버의 기본 단위가 됩니다.

[04:50] 이 구조의 장점은 깔끔한 테스트 아키텍처를 제공하며, 세밀한 기능을 독립적으로 테스트할 수 있다는 것입니다. 38개의 테스트가 성공적으로 실행되는 것을 확인할 수 있습니다.

[05:40] 하지만 '새로운 기능 수정 체인 문제'라는 단점이 있습니다. 하위 레벨 원자를 수정할 때 이를 사용하는 모든 상위 구성요소들도 함께 수정해야 하는 문제가 발생합니다.

[06:13] 원자적 구성 가능한 아키텍처의 단점으로, 하나의 변경사항이 있을 때 모든 상위 레벨 구성요소를 다시 테스트해야 하는 번거로움이 있습니다.

[06:32] AI 코딩 도구에서는 작은 변경사항에도 모든 상위 계층을 업데이트해야 하며, 이는 컨텍스트 윈도우에 더 많은 정보가 필요함을 의미합니다.

[07:00] 계층형 아키텍처는 가장 널리 사용되는 패턴으로, 인터페이스 계층, API 엔드포인트, 데이터 모델, 비즈니스 로직 등 논리적으로 구성된 디렉토리 구조를 가집니다.

[00:07:05] 레이어드 아키텍처

폴더와 디렉터리를 이용한 전통적 코드 구조의 장단점을 검토합니다. 관심사 분리를 통한 명확한 역할 분담과 함께, AI 도구가 여러 파일을 읽어야 하는 점에서의 토큰 소모 문제를 논의합니다.

[07:41] PostgreSQL과 Redis 코드베이스를 예로 들어, 계층형 아키텍처의 실제 구현을 살펴볼 수 있습니다. 특히 Redis는 평면적이지만 전형적인 계층형 구조를 보여줍니다.

[08:06] 계층형 아키텍처의 주요 단점은 계층 간 임포트가 필요하고 AI 코딩 도구가 모든 영역을 처리해야 한다는 것입니다.

[08:40] 계층형 아키텍처는 빠른 기능 추가와 수정이 가능하다는 장점이 있지만, AI 코딩 도구에는 최적이 아닐 수 있습니다.

[09:07] 계층형 아키텍처 내에서 utils와 같은 원자적 구조가 가장 하위 레벨에 위치하지만, 이는 여러 모듈 간의 임포트 관계를 복잡하게 만드는 시작점이 됩니다.

[09:43] 계층형 아키텍처는 확장성과 개발 용이성 측면에서 장점이 있지만, AI 코딩 도구가 모든 디렉토리를 검토해야 하는 단점이 있습니다.

[00:10:15] 수직 슬라이스 아키텍처

기능별로 코드를 분리하여 하나의 슬라이스로 관리하는 방식의 효율성을 설명합니다. 단일 컨텍스트 프라임팅으로 토큰 절감과 빠른 코드 분석이 가능하다는 점을 강조합니다.

[10:15] 수직 슬라이스 아키텍처가 AI 코딩 도구와 에이전트 코딩 도구에 최적화된 구조로 제안되었습니다.

[10:42] 수직 슬라이스 아키텍처는 features 디렉토리 내에 각 기능별로 필요한 모든 컴포넌트(API, 모델, 서비스 등)를 포함하는 구조입니다.

[11:20] 이 구조는 깔끔하고 간결하며, 단일 디렉토리 임포트와 컨텍스트 프라이밍으로 효율적인 AI 코딩이 가능합니다. 기능별 구성으로 관련 코드를 쉽게 찾고 관리할 수 있습니다.

[12:01] AI 코딩 도구 설정을 위한 컨텍스트 프라이밍의 중요성을 설명하면서, 하나의 프롬프트로 모든 컨텍스트를 설정할 수 있다고 소개합니다.

[12:27] 수직 슬라이스 아키텍처의 실제 구조를 보여주며, features 폴더 내의 projects, tasks, users 등의 구성을 설명합니다.

[12:59] 여러 AI 코딩 도구(Claude, Cursor)에서 동일한 컨텍스트 프라이밍 방식을 적용하는 방법을 시연합니다.

[13:44] 도구 자체보다는 패턴과 원칙이 더 중요하다는 점을 강조하며, Principal AI Coding의 핵심 개념을 설명합니다.

[14:17] 다양한 AI 코딩 도구들이 동일한 패턴으로 작동하는 것을 시연하며, 수직 슬라이스 아키텍처의 실용성을 입증합니다.

[15:06] 수직 슬라이스 아키텍처의 기본 개념과 프롬프트 컨텍스트 프라이밍의 중요성을 설명하면서, 횡단 관심사 최소화의 장단점을 소개합니다.

[15:32] 기능 중심, 가치 중심의 구조를 강조하며, 코드베이스보다 사용자와 고객 관점의 중요성을 설명합니다.

[15:50] 수직 슬라이스 아키텍처의 주요 단점으로 코드 중복 문제와 유틸리티 공유의 위험성을 상세히 설명합니다.

[16:46] 신입/중급 엔지니어들이 이 아키텍처에서 겪을 수 있는 어려움과 코드 중복의 현실적인 문제를 다룹니다.

[17:09] AI 코딩 도구에서 단일 컨텍스트 격리의 중요성을 강조하고, 파이프라인 아키텍처로 화제를 전환합니다.

[00:17:25] 파이프라인 아키텍처

데이터 또는 작업 단계를 순차적으로 처리하는 파이프라인 구조를 소개합니다. 주로 ML Ops 및 데이터 처리에 적합하며, 단계별 처리의 장점을 살펴봅니다.

[17:41] 파이프라인 아키텍처의 실제 활용 사례로 데이터 엔지니어링과 ML Ops 분야를 소개합니다.

[17:53] 파이프라인 아키텍처의 기본 구성 요소로 유틸리티와 단계별 구성요소가 있으며, 이들이 모여 실행 가능한 파이프라인을 형성합니다.

[18:04] LLM 개발에서 파이프라인 아키텍처의 장점은 순차적 처리에 적합하고, 타입과 명확한 경로를 제공하며 패턴 기반 접근이 가능하다는 것입니다.

[18:28] AI 코딩 도구들은 이러한 구조화된 패턴과 타입을 선호하며, 이를 통해 작업 수행과 단계 재배열이 용이합니다.

[18:43] 파이프라인 아키텍처의 주요 단점은 파이프라인 기반이 아닌 시스템에는 적합하지 않으며, 상태 관리가 복잡할 수 있다는 것입니다.

[19:14] AI 시스템을 위한 주요 아키텍처로 원자적 구성, 계층화된 파이프라인, 수직 슬라이스를 검토했으며, 특히 수직과 원자적 구조가 AI 코딩에 효과적입니다.

[00:19:41] AI 에이전트 아키텍처

AI 에이전트를 구축하기 위한 구조적 접근법을 논의합니다. 아토믹, 수직 슬라이스, 싱글 파일 에이전트 등 다양한 구조의 특성과 적용 가능성을 비교합니다.

[19:47] AI 에이전트 구축을 위한 최적의 구조로 원자적 구성, 수직 슬라이스, 단일 파일 에이전트가 추천되며, 이는 모든 AI 제공자와 호환됩니다.

[20:35] 원자적 구조의 구성 요소인 atoms, molecules, organisms, membranes에 대해 설명하면서, membrane이 시스템의 API 계층으로서 상호작용 방식을 정의한다고 소개합니다.

[21:17] organism은 파일 에이전트로, molecules에서 필요한 컴포넌트를 구성하며, atoms는 가장 낮은 수준의 테스트 가능한 단위로 설명됩니다.

[22:10] 이 구조는 실행 가능한 코드가 아닌 AI 에이전트 설계를 위한 참고 아키텍처임을 설명합니다.

[22:28] 수직 슬라이스 아키텍처를 대안으로 제시하며, 각 에이전트를 개별 기능으로 보는 접근 방식을 설명합니다.

[23:08] 블로그 에이전트 예시를 통해 수직 슬라이스 아키텍처의 장점과 빠른 버전 관리 가능성을 설명합니다.

[23:34] 단일 파일 에이전트의 버전 관리와 수정이 매우 용이함을 설명합니다. 전체 파일을 복사해서 새 버전을 만들거나 LLM 제공자를 변경하는 등의 작업이 간단하게 가능합니다.

[23:49] 에이전트 아키텍처 중에서 수직 슬라이스 아키텍처와 단일 파일 에이전트가 주목할 만한 방식임을 설명합니다.

[00:24:00] 싱글 파일 에이전트

모든 에이전트 기능을 하나의 파일에 집약하는 설계를 소개합니다. 단일 파일로 컨텍스트를 쉽게 프라임팅하여 AI 도구가 빠르게 실행할 수 있음을 보여줍니다.

[24:06] 단일 파일 에이전트의 특징을 설명합니다. 700줄의 코드가 한 파일에 있는 것이 일반적으로는 안티패턴이지만, 이 구조에서는 독립적인 컨텍스트 에이전트로서 장점이 됩니다.

[24:42] 단일 파일 에이전트의 실용적인 장점을 설명합니다. 파일 참조와 프롬프팅이 매우 단순하고 직관적으로 이루어질 수 있습니다.

[25:23] 채널의 주요 주제인 AI 코딩과 에이전트 코딩에 대해 설명하며, 단일 파일 에이전트 코드베이스의 중요성을 강조합니다.

[25:51] 아키텍처의 중요성에 대한 결론을 제시합니다. 단기적으로는 컨텍스트 관리를 위해 중요하지만, LLM 기술이 발전할수록 그 중요성이 감소할 수 있다고 설명합니다.

[26:32] 컨텍스트 관리의 중요성을 강조하며, 특히 대규모 코드베이스에서 AI 도구들이 효율적으로 작동하기 위해서는 명확한 경로와 구조가 필요함을 설명합니다.

[27:00] 현재 AI 코딩 도구들이 단순 정보 검색에도 많은 토큰을 소비하는 문제점을 지적하고, 레이어드 아키텍처의 한계를 설명합니다.

[27:34] 버티컬 슬라이스 아키텍처를 도입하면 토큰 사용을 크게 절약할 수 있으며, 이는 비용 효율성으로 이어진다고 설명합니다.

[00:28:00] 결론 및 미래 전망

코드베이스 구조가 AI 도구의 성능과 비용 효율성에 미치는 영향을 정리합니다. 향후 AI 코딩과 에이전트 개발의 발전 방향 및 교육 프로그램 안내로 마무리합니다.

[28:06] 향후 AI가 대부분의 코드를 작성할 것이므로, 코드베이스를 AI 관점에서 구조화해야 한다는 새로운 패러다임을 제시합니다.

[28:47] 3월 말에 발표될 AI 코딩 현황 에세이에 대해 소개하며, 이를 통해 AI 코딩의 현재와 미래, 그리고 실질적인 가이드라인을 제공할 것임을 예고합니다.

[29:33] 2025년 1분기 AI 코딩 현황에 대한 독점 콘텐츠를 Principled AI Coding 수료 멤버들과 공유할 예정임을 안내합니다.

[29:46] 뛰어난 설계와 아키텍처에 관심 있는 엔지니어들을 위한 Principled AI Coding 과정을 소개하고 참여를 권장합니다.

[30:03] AI 코딩에서 에이전트 코딩으로의 전환을 설명하며, 2025년이 이 변화에 동참할 수 있는 마지막 기회임을 강조합니다.

[30:31] 8개 강의를 통해 컨텍스트, 모델, 프롬프트 등 핵심 원칙들을 다루며, 초급부터 고급까지 체계적인 학습을 제공합니다.