Claude Code로 148개 API를 자동 구현한 이야기 — AI 개발팀 3가지 모드

반복 코딩을 AI에 맡기기로 했다

백엔드 프로젝트에서 도메인 CRUD를 구현하는 일은 패턴이 정해져 있다. Service 로직 작성하고, DAO 만들고, 쿼리 작성하고, 상수 등록하고, 테스트 돌리고. 하나만 하면 금방인데 이게 30개, 50개, 100개가 넘어가면 달라진다. 패턴은 같은데 도메인마다 미묘하게 다른 부분이 있어서 완전한 코드 생성기를 만들기도 애매하고, 그렇다고 하나씩 손으로 치기엔 시간이 너무 많이 든다.

Claude Code에 이 작업을 맡겨보기로 했다. 처음에는 “이 도메인 구현해줘”라고 하나씩 시켰는데, 어느 순간 팀으로 구성하면 더 효율적이겠다는 생각이 들었다. 결과적으로 3가지 개발 모드를 만들었고, 7개 레이어 148개 API를 이 방식으로 구현했다.

이 글에서는 각 모드의 구조와 선택 기준, 그리고 실전에서 부딪힌 문제들을 정리한다.

3가지 모드 — 언제 무엇을 쓰나

핵심은 “기능이 몇 개인가”와 “기능 간에 의존성이 있는가”다.

1
2
3
4
5
6
7

개발 요청
    │
    ├── 1~3개 기능 or 수정/버그  →  단일 Agent 모드
    │
    └── 4개 이상 기능
          ├── 레이어 간 동기화 필요  →  파이프라인 팀 모드
          └── 기능 간 독립적         →  도메인 병렬 팀 모드

직관적이지만 이 의사결정이 결과에 큰 차이를 만든다. 잘못 고르면 시간을 두 배로 쓰거나, 아예 산출물을 버려야 할 수도 있다.

단일 Agent 모드

가장 단순한 형태. Agent 하나가 분석부터 구현, 검증까지 전부 담당한다.

1
2
3

Agent 1명
  Phase 0 (분석)  →  T0 (테스트 스캐폴딩)
      →  T1 (구현)  →  T2 (DAO + 쿼리)  →  T3 (검증)

실제로 이 모드로 처리한 레이어는 이랬다.

단일 Agent 모드가 맞는 상황은 명확하다.

• 기존 코드 수정이나 버그 픽스 — 하나의 맥락에 집중해야 할 때
• 이미 완성된 레이어를 참조할 수 있을 때 — Agent가 “이 패턴 따라해”라고 할 수 있으면 품질이 높아진다
• 도메인이 3개 이하 — 에이전트 하나가 전체 맥락을 들고 다닐 수 있을 때

Integration 레이어(29개 API)는 양이 꽤 되지만 단일 Agent로 처리했다. 이미 Physical 레이어가 참조 코드로 있었기 때문에, Agent가 패턴을 학습한 상태에서 도메인만 바꿔가며 구현하면 됐다. 이런 경우 팀을 꾸리면 오히려 컨텍스트 전달 비용이 발생한다.

파이프라인 팀 모드

역할이 분리된 Teammate 4명이 직렬로 연결된다. 산출물이 순서대로 전달되면서 각 전문가가 자기 영역만 담당한다.

1
2
3
4
5

team-lead  →  diagram-dev  →  ts-dev  →  query-dev
    │              │              │           │
    │         다이어그램 생성   TS 구현    쿼리 작성
    │
    └── 전체 조율 + 산출물 검증

이 모드로 구현한 레이어들:

파이프라인 팀 모드의 핵심은 다이어그램이 먼저라는 점이다. diagram-dev가 프로세스 플로우를 먼저 그리면, ts-dev는 그 다이어그램을 보면서 구현하고, query-dev는 ts-dev의 DAO 인터페이스를 보면서 쿼리를 작성한다. 각 단계의 산출물이 다음 단계의 명세서 역할을 한다.

반대로, 다이어그램 없이 바로 코드부터 작성하면 어떻게 되냐. ts-dev가 자기 해석대로 구현하고, query-dev가 또 자기 해석대로 쿼리를 쓴다. 둘의 해석이 달라서 파라미터가 안 맞는 일이 빈번했다. 사람 팀에서도 설계 문서 없이 코드부터 치면 나중에 고생하는 것과 같은 원리다.

도메인 병렬 팀 모드

대규모 레이어에서 다수 도메인을 동시에 구현할 때 쓴다. team-lead가 도메인을 분배하고, 각 Agent가 git worktree로 만든 독립 브랜치에서 병렬 처리한다.

1
2
3
4

team-lead
  ├── bo-agent   (businessObject 15개 + AI 2개)
  ├── co-agent   (chartObject 14개 + collection 1개)
  └── bg-agent   (businessGroup 7개 + link 4개 + lambda 1개)

Business 레이어는 44개 API를 이 모드로 처리했다. 도메인 간 의존성이 없어서 3명이 동시에 작업해도 충돌이 없었다. 순차로 했으면 훨씬 오래 걸렸을 일을 병렬로 쪼개서 시간을 크게 줄인 케이스다.

git worktree가 핵심이다

병렬 팀 모드에서 가장 중요한 건 각 Agent가 독립된 작업 공간을 가져야 한다는 점이다. 같은 브랜치에서 여러 Agent가 동시에 파일을 수정하면 충돌이 나고, 그걸 해결하느라 시간을 더 쓴다.

git worktree를 쓰면 하나의 저장소에서 여러 브랜치를 동시에 체크아웃할 수 있다. 각 Agent는 자기 worktree에서 자유롭게 작업하고, 완료 후 team-lead가 순서대로 머지한다.

1
2
3
4
5
6
7
8
9
10

# team-lead가 각 Agent용 worktree 생성
git worktree add ../project-bo feature/business-object
git worktree add ../project-co feature/chart-object
git worktree add ../project-bg feature/business-group

# 각 Agent는 자기 디렉토리에서 독립 작업
# 완료 후 team-lead가 순서대로 머지
git merge feature/business-object
git merge feature/chart-object
git merge feature/business-group

병렬 모드의 함정

도메인이 “독립적”이라고 판단했는데 실제로는 아닌 경우가 있었다. 두 도메인이 같은 유틸리티 함수를 수정하거나, 같은 상수 파일에 값을 추가하면 머지할 때 충돌이 난다. 이런 공유 자원은 team-lead가 사전에 파악해서 먼저 처리해두거나, 한쪽 Agent에만 배정하는 게 안전하다.

TDD 기반 Phase 구조

모드와 무관하게 모든 개발은 같은 Phase 구조를 따른다.

Phase 0~2는 “코드를 치기 전에 이해하는 시간”이다. AI에 “이 도메인 구현해”라고 바로 시키면 기존 코드와 완전히 다른 스타일로 만들어온다. 먼저 기존 패턴을 학습시키고, DB 스키마를 확인하게 하고, 모르는 건 질문하게 해야 품질이 올라간다.

T0에서 실패하는 테스트를 먼저 작성하는 이유는 간단하다. 테스트 없이 구현부터 시키면 “돌아가기는 하는데 맞는지 모르는” 코드가 나온다. 테스트가 있으면 최소한 의도한 동작은 보장된다.

3단계 검증 파이프라인

모든 모드에서 구현이 끝나면 동일한 검증 파이프라인을 거친다.

1
2
3
4
5
6
7
8
9
10

# 1단계: 타입 체크
tsc --noEmit
# → 타입 오류 0개 확인

# 2단계: E2E 테스트
npx ts-node launcher.ts --test
# → 전체 통과율 100% 목표

# 3단계: 코드 품질
# /simplify 스킬로 중복·복잡도·네이밍 검토

1단계만 통과하면 되는 게 아니다. 타입 체크가 통과해도 런타임에 터지는 경우가 있고(쿼리 바인딩 불일치 등), 테스트가 통과해도 코드 품질이 형편없는 경우가 있다. 세 단계 모두 통과해야 해당 브랜치의 작업이 완료된다.

실제로 이 파이프라인이 없었던 초기에는 “타입 체크 통과했으니 됐지” 하고 넘겼다가, 나중에 통합 테스트에서 쿼리 파라미터가 안 맞는 게 수십 개씩 발견됐다. 각 단계의 검증 대상이 다르기 때문에 빼면 안 된다.

AI가 반복하는 실수 — 프롬프트로 잡기

148개 API를 구현하면서 AI가 반복적으로 틀리는 패턴을 발견했다. 한 번은 실수일 수 있지만, 같은 실수가 세 번 이상 나오면 프롬프트에 명시적으로 제약을 추가했다.

존재하지 않는 테이블 참조

AI가 네이밍 패턴으로 테이블명을 추측해서 쿼리를 작성하는데, 실제로 없는 테이블인 경우가 있었다. USER_CONFIG가 있으니까 USER_CONFIG_DETAIL도 있겠지 하는 식의 추론이다.

해결: 쿼리 작성 전 반드시 DDL 파일을 먼저 읽도록 지시. “존재하는 테이블만 사용할 것, 추측 금지”를 프롬프트에 명시했다.

서브엔티티에 독립 INSERT 생성

부모-자식 관계인 테이블에서, 자식 테이블에 독립적인 INSERT를 만드는 실수. 자식 데이터는 부모와 함께 트랜잭션으로 처리해야 하는데, AI가 별도 API로 분리해버렸다.

해결: “서브엔티티는 UPDATE/INSERT_XM(부모와 함께 처리하는 복합 타입)만 허용, 독립 INSERT 금지”를 규칙으로 추가.

실행 순서 오류

여러 API를 체인으로 실행할 때, 자식 테이블의 UPDATE가 부모 테이블의 DELETE보다 나중에 실행되어 FK 제약 위반이 발생. AI는 알파벳 순서로 정렬했는데, 도메인 관점에서는 부모가 먼저 처리되어야 한다.

해결: 도메인 기반 정렬 로직을 추가하고, prefix 매칭으로 부모-자식 관계를 자동 판별하도록 했다.

날짜 필드 alias 불일치

DB에서 SYS_CREATE_DATE 같은 시스템 접두사가 붙은 컬럼을 조회할 때, 어떤 쿼리는 접두사를 유지하고 어떤 쿼리는 벗겨서 반환했다. 다운스트림에서 필드명이 안 맞아 null이 들어오는 버그.

해결: 외부 노출 쿼리의 alias를 명시적으로 매핑하는 규칙 추가.

이런 패턴들은 한 번 프롬프트에 반영하면 이후에는 거의 재발하지 않았다. AI에게 “하지 말 것”을 명확히 알려주는 게 “할 것”을 알려주는 것만큼 중요하다.

모드 선택 기준 정리

실전에서 체득한 기준을 정리하면 이렇다.

하나 더 — 처음에는 단일 Agent로 시작하라. 첫 번째 도메인을 단일 Agent로 구현하면 참조 코드가 생긴다. 두 번째부터는 그 참조 코드를 기반으로 팀 모드를 적용하면 품질이 훨씬 안정적이다. 참조 코드 없이 팀 모드부터 시작하면 각 Teammate가 제각각 다른 스타일로 만들어서 나중에 통일하느라 고생한다.

148개 API — 전체 그림

최종적으로 7개 레이어를 모드별로 나눠서 구현한 전체 현황이다.

Presentation 레이어는 사전에 구현되어 있었고, 나머지 114개 API를 AI로 구현했다. 100% 자동은 아니다. Phase 0의 인터뷰에서 도메인 맥락을 전달해야 했고, 검증 파이프라인에서 실패하면 피드백을 줘야 했다. 하지만 “내가 직접 Service 코드를 치는 시간”은 거의 없었다.

돌아보면

AI에 코딩을 맡기는 건 “프롬프트 잘 쓰면 끝”이 아니다. 실제로 필요한 건 이런 것들이었다.

구조화된 프로세스. Phase 0~T4 구조가 없으면 AI가 매번 다른 순서로 작업해서 결과가 들쭉날쭉하다. 사람에게도 프로세스가 필요하듯, AI에도 필요하다.

모드 선택 판단력. 40개 넘는 독립 도메인을 파이프라인으로 직렬 처리하면 시간 낭비고, 3개짜리를 팀으로 구성하면 오버헤드가 더 크다. 상황에 맞는 모드를 고르는 게 결과를 좌우한다.

실패 패턴의 누적 학습. AI가 반복하는 실수를 프롬프트에 “하지 말 것”으로 축적하면 시간이 갈수록 품질이 올라간다. 148개를 구현하면서 프롬프트에 추가된 제약 조건이 15개 정도 됐다. 초반의 시행착오가 후반의 안정성으로 돌아온 셈이다.

처음부터 팀 모드를 쓸 필요는 없다. 단일 Agent로 시작해서 참조 코드를 만들고, 규모가 커지면 팀을 구성하고, 반복되는 실수는 프롬프트에 잡아두면 된다.

참고

• Claude Code Agent — Agent/Team 모드 공식 문서
• Claude Code Skills — Skills 공식 문서
• git worktree — 하나의 저장소에서 여러 브랜치 동시 체크아웃