AI 코딩 에이전트, 똑똑하게 부리는 법

AI 코딩 에이전트를 처음 쓸 때는 마법 같다. “이 버그 고쳐줘” 하면 고치고, “테스트 짜줘” 하면 짠다. 그런데 며칠 쓰다 보면 이상한 점을 발견한다.

얘가 어제 한 일을 전혀 기억 못 한다.

새 세션을 열 때마다 “이 프로젝트가 뭔가요?”부터 시작하는 AI를 보면서, 매번 같은 설명을 반복하는 자신을 발견하게 된다. 이건 AI의 한계가 아니라 우리가 컨텍스트를 설계하지 않았기 때문이다.

기억상실증 환자에게 업무 인수인계하기

AI 에이전트의 작동 방식을 솔직하게 표현하면 이렇다:

• 세션 시작 → 깊은 잠에서 깨어남 (과거 기억 없음)
• 세션 종료 → 다시 깊은 잠에 빠짐 (모든 기억 소실)

영화 〈메멘토〉의 주인공처럼, 매번 “나는 누구인가?”부터 다시 시작한다. 차이가 있다면 — 메멘토의 레너드는 몸에 문신을 새겨서 기억을 보존했고, 우리는 파일에 적어서 기억을 보존한다는 것.

이 파일들을 어떻게 구성하느냐가 AI 에이전트의 생산성을 결정한다. 잘 설계된 컨텍스트를 가진 AI는 시니어 개발자처럼 행동하고, 그렇지 않은 AI는 매번 온보딩이 필요한 인턴처럼 행동한다.

컨텍스트의 두 축: 지식과 행동

AI에게 전달해야 할 컨텍스트는 크게 두 가지로 나뉜다.

지식 (Knowledge) — “이 프로젝트가 뭔지”

프로젝트의 구조, 도메인 규칙, API 스펙, 데이터 모델 같은 정적 정보다. 사람으로 치면 “이 회사가 뭐 하는 곳이고, 우리 시스템이 어떻게 생겼는지”에 대한 이해.

ai-context/
├── domain-overview.md    # 도메인 설명, 비즈니스 규칙
├── data-model.md         # 핵심 엔티티 정의
├── api-spec.json         # API 스펙 (DSL)
└── architecture.md       # 아키텍처 결정 사항

행동 (Action) — “어떻게 일해야 하는지”

개발 워크플로우, 배포 절차, 코딩 컨벤션 같은 동적 절차다. 사람으로 치면 “우리 팀은 PR 올리기 전에 꼭 이것부터 하고, 배포는 이 순서로 한다”에 대한 가이드.

skills/
├── develop/
│   └── SKILL.md    # 개발 워크플로우
├── review/
│   └── SKILL.md    # 코드 리뷰 기준
└── deploy/
│   └── SKILL.md    # 배포 절차

이 둘을 왜 분리하느냐? 로딩 타이밍이 다르기 때문이다.

지식은 세션 시작과 동시에 로드되어야 한다. AI가 프로젝트를 이해하지 못한 상태에서 코드를 짜게 하면 엉뚱한 결과가 나온다. 반면 행동(Skill)은 필요한 시점에 불러오면 된다. 배포할 때만 배포 스킬을, 리뷰할 때만 리뷰 스킬을 로드하는 식이다.

이렇게 하면 토큰 효율도 좋아진다. 모든 정보를 한꺼번에 밀어넣으면 비용도 오르고 응답도 느려진다.

DSL로 토큰 아끼기

AI에게 프로젝트 정보를 전달할 때, 자연어로 장황하게 쓰면 토큰을 엄청나게 소모한다.

자연어로 설명하면:

“사용자 주문 API는 POST 방식으로 /api/v1/orders 경로를 사용합니다. OrderCreateRequest를 받아서 OrderResponse를 반환하며, 내부적으로 CreateOrderUseCase를 호출합니다. 이 API는 Order 도메인과 Payment 도메인에 관여하며…”

이걸 JSON DSL(Domain Specific Language)로 압축하면:

{
  "endpoint": "POST /api/v1/orders",
  "request": "OrderCreateRequest",
  "response": "OrderResponse",
  "useCase": "CreateOrderUseCase",
  "domains": ["Order", "Payment"],
  "calls": [
    { "service": "payment-api", "endpoint": "POST /api/v1/payments" }
  ]
}

같은 정보를 약 1/3의 토큰으로 전달할 수 있다. AI는 구조화된 데이터를 자연어보다 더 정확하게 파싱한다. 특히 여러 서비스 간 호출 관계를 파악할 때, JSON 구조만으로 “A → B → C” 같은 플로우를 즉시 추적할 수 있다.

DSL 구조를 직접 설계할 필요도 없다. AI에게 이렇게 시키면 된다:

1. “현재 이 프로젝트의 API를 전부 분석해봐”
2. “분석 결과를 다음 세션에서도 기억할 수 있게 DSL로 정리해줘”
3. 결과를 검증하고 피드백 → AI가 스스로 개선

핵심: 구조를 잡는 건 개발자의 몫, 내용을 채우는 건 AI의 몫.

역할을 나눠서 부려먹기

프로젝트가 커지면 하나의 AI 세션에 모든 걸 맡기는 건 비효율적이다. 사람도 한 명이 기획·설계·개발·배포를 동시에 하면 퀄리티가 떨어지듯, AI도 역할을 나눠주면 각 영역에서 더 정확한 답을 낸다.

실전에서 효과적인 역할 분리:

역할	컨텍스트 범위	하는 일
Architect	전체 시스템 구조	설계 분석, 영향도 파악, 작업 분배
Developer	특정 서비스/모듈	집중 설계 + 코드 구현
Reviewer	코드 변경분	코드 리뷰, 테스트 검증

각 역할마다 로드하는 컨텍스트 범위가 다르다는 게 핵심이다.

• Architect에게는 전체 서비스의 API/메시지 스펙 개요만 로드
• Developer에게는 담당 서비스의 전체 문서를 로드
• Reviewer에게는 코딩 컨벤션과 변경된 파일만 로드

불필요한 컨텍스트를 줄이면 AI의 집중도가 올라간다. 사람이 회의할 때 관련 없는 문서 50페이지를 함께 주면 핵심을 놓치는 것과 같은 원리다.

아키텍처가 AI 친화적이려면

여기서 재미있는 발견이 있다. 코드 아키텍처에 따라 AI가 프로젝트를 이해하는 난이도가 크게 달라진다.

레이어드 아키텍처의 함정

전통적인 레이어드 아키텍처에서는 OrderService.java 하나에 수십 개의 메서드가 들어간다. AI가 “주문 취소” 기능을 이해하려면 500줄짜리 서비스 클래스 전체를 읽어야 하고, 실제로 필요한 50줄 외에 450줄의 노이즈가 함께 딸려온다.

클린 아키텍처가 답인 이유

클린 아키텍처(또는 헥사고날)에서는 CancelOrderUseCase라는 독립된 유닛이 존재한다. AI는 딱 이 파일만 읽으면 된다. 입력이 뭔지(Port), 출력이 뭔지(Port), 비즈니스 로직이 뭔지(UseCase)가 명확하게 분리되어 있으니까.

이걸 표로 정리하면:

아키텍처 조합	AI 컨텍스트 구성 난이도
모놀리식 + 레이어드	🔴 어려움
모놀리식 + 클린	🟡 보통
MSA + 레이어드	🟡 보통
MSA + 클린	🟢 쉬움

핵심은 MSA냐 모놀리식이냐가 아니라, UseCase/Port/Adapter의 역할 분리가 명확한가다. 역할이 명확하면 AI의 컨텍스트 문서와 코드 구조가 1:1로 매핑되고, 노이즈 없이 정확한 작업이 가능해진다.

AI가 틀렸을 때: 피드백의 기술

AI 에이전트를 잘 쓰는 사람과 못 쓰는 사람의 가장 큰 차이는 피드백 방식이다.

❌ 나쁜 피드백:

“틀렸어. 다시 해봐.”

✅ 좋은 피드백:

“이 부분이 틀렸어. RegionDecisionFactor 모델이 Service에서 어떤 역할을 하는지 다시 살펴봐.”

그리고 AI가 정답을 맞혔을 때가 진짜 중요한 순간이다:

“맞아. 근데 왜 처음에는 이걸 추론 못 했어? 네가 만든 스펙에 뭐가 빠져있었는지 생각해봐.”

AI가 스스로 부족한 점을 인지하면, 컨텍스트 문서를 어떻게 보완해야 하는지까지 제안한다. 이 사이클을 반복하면 컨텍스트 품질이 계속 올라간다.

잊지 말 것: AI가 학습한 교훈은 반드시 파일에 기록시켜야 한다. “다음부턴 잘할게요”는 의미 없다. 다음 세션에서는 또 기억을 잃을 테니까.

MCP로 눈과 손 달아주기

컨텍스트 설계가 AI의 뇌라면, MCP(Model Context Protocol)는 AI의 눈과 손이다.

잘 학습된 AI에게 MCP를 연결하면:

• Jira/Linear 연동 → 티켓을 읽고, 분석하고, 하위 이슈를 직접 생성
• GitHub 연동 → PR 생성, 코드 리뷰, 태그 관리까지 자동화
• 모니터링 연동 → Datadog/Sentry 로그를 자연어로 분석

중요한 건 순서다. 컨텍스트 없이 MCP부터 연결하면 망한다. 프로젝트를 이해하지 못하는 AI에게 Jira 접근 권한을 주면, 엉뚱한 티켓을 생성하고 잘못된 PR을 올린다.

뇌를 먼저 만들고, 그 다음에 눈과 손을 달아주자.

실전 체크리스트

AI 에이전트 컨텍스트를 처음 설계한다면:

• 프로젝트 루트에 CLAUDE.md (또는 에이전트별 컨텍스트 파일) 생성
• 도메인 개요, 핵심 엔티티, 비즈니스 규칙 정리
• API/이벤트 스펙을 JSON DSL로 구조화
• 개발/배포 워크플로우를 Skill 파일로 분리
• 역할별 컨텍스트 로딩 범위 설정
• AI가 학습한 교훈을 기록할 공간 확보
• MCP 연동 (컨텍스트 품질이 충분해진 후)

마무리

AI 에이전트는 도구다. 그런데 여느 도구와 좀 다른 점이 있다면, 쓰는 사람이 얼마나 잘 설계하느냐에 따라 성능 차이가 극단적이라는 것이다.

같은 Claude Code를 쓰더라도, 컨텍스트를 잘 설계한 팀은 4명이 16명분의 일을 하고, 그렇지 않은 팀은 “AI가 별로 쓸모없네”라는 결론에 도달한다.

결국 AI 시대의 핵심 역량은 코딩이 아니라 설계다. 무엇을 알려줄지, 어떤 역할을 맡길지, 어떤 구조로 정보를 전달할지 — 이 설계 능력이 개발자의 생산성을 가른다.

AI에게 “코드 짜줘”라고 말하기 전에, 먼저 AI의 뇌부터 설계하자.