AI 에이전트로 혼자 350K 라인 코드베이스를 구축하며 얻은 실용적인 교훈

컨텍스트로서의 엔지니어링 환경

개발자의 52일 프로젝트(600회 커밋, 약 965K 라인의 코드 처리량, 356K 라인의 프로덕션 코드)는 에이전트 출력 품질이 모델뿐만 아니라 엔지니어링 환경에 크게 의존한다는 것을 보여주었습니다. 코드베이스 자체가 에이전트의 컨텍스트 시스템 역할을 하여 별도의 RAG 또는 메모리 파일이 필요하지 않습니다.

명확한 아키텍처 경계가 필수적임이 입증되었습니다. 코드베이스는 엄격한 DDD 계층화를 따릅니다: 데이터 구조를 위한 도메인 계층, 비즈니스 로직을 위한 서비스 계층, HTTP 형식 변환을 위한 핸들러 계층으로, 22개의 도메인 모듈이 명확한 경계를 가지고 있습니다. 이는 에이전트에게 어디를 변경해야 하는지 알려줍니다.

디렉토리 구조는 크로스-스택 네이밍 정렬을 통한 문서 역할을 합니다. "Loop"와 같은 기능의 경우: 데이터 구조는 backend/internal/domain/loop/, 로직은 backend/internal/service/loop/, 프론트엔드는 web/src/components/loops/입니다. 제품 개념에서 코드 경로로의 이 직접적인 매핑은 에이전트가 전체 코드베이스를 탐색할 필요를 없앱니다.

기술 부채 증폭

기술 부채는 AI 에이전트와 함께 기하급수적으로 확산됩니다. 개발자가 임시적인 타협(서비스 계층을 우회하여 DB를 직접 쿼리하거나 하드코딩된 매직 넘버 사용)을 할 때, 에이전트는 이러한 패턴을 합법적인 접근 방식으로 체계적으로 재사용합니다. 나쁜 코드를 지뢰로 인식하는 인간 엔지니어와 달리, 에이전트는 기존 패턴을 유효한 선례로 취급합니다.

실질적인 교훈: 정기적인 리팩토링은 미적 이유가 아니라 엔지니어링 신호의 순수성을 유지하기 위해 필수적이 됩니다. 좋은 관행이 지배할 때, 에이전트는 좋은 관행을 증폭시키고; 단축키가 지배할 때, 에이전트는 단축키를 증폭시킵니다. 이는 에이전트 협업 개발에서의 독특한 유지 관리 비용을 나타냅니다.

품질 게이트로서의 강력한 타이핑

Go + TypeScript + Proto를 사용하면 컴파일 타임 오류 감지가 가능하여 에이전트 오류를 런타임에서 개발 시간으로 이동시킵니다. 서명이 맞지 않는 에이전트 생성 함수는 빌드 실패를 일으킵니다. TypeScript는 API 형식 불일치를 즉시 포착합니다. Proto 생성 코드는 백엔드 동기화 없이 메시지 형식이 변경되면 컴파일되지 않습니다. 이러한 오류는 약한 타이핑 언어에서는 런타임으로 빠져나갈 것입니다.

4계층 피드백 시스템

에이전트는 효율적인 반복을 위해 4계층의 피드백이 필요합니다:

• 컴파일 — 핫 리로드, 1초 이내의 Go 재시작, 실시간으로 플래그되는 TypeScript 타입 오류. 구문 및 타입 오류를 제거합니다.
• 단위 테스트 — 도메인 및 서비스 계층을 커버하는 700개 이상의 테스트. 에이전트는 5분 이내에 특히 멀티 테넌트 격리와 같은 경계 조건에 대해 회귀를 도입했는지 알 수 있습니다.
• E2E 테스트 — 실제 기능 경로의 종단 간 검증. 단위 테스트가 닿을 수 없는 통합 문제를 포착합니다.
• CI 파이프라인 — 모든 PR이 전체 테스트 스위트, 린팅, 타입 체크, 멀티 플랫폼 빌드를 실행합니다. 병합 전 최종 안전망입니다.

4계층은 증가하는 지연 시간과 확장하는 커버리지를 제공합니다: 1계층은 단일 라인 변경을 확인하는 반면, 4계층은 크로스 모듈 리팩토링을 검증합니다.