6개월 전, 저는 AI 코딩 에이전트가 단 한 문장으로 완전한 REST API를 구축하는 것을 지켜보았습니다. 에이전트는 프로젝트 구조를 생성하고, 라우트(routes)를 작성하며, 테스트를 추가하고, 코드를 git에 커밋했습니다. 이 모든 과정은 약 4분이 소요되었고 API 호출 비용은 약 40센트였습니다. 저는 터미널을 응시하며 생각했습니다. "이것은 내가 본 것 중 가장 놀라운 일이거나, 아니면 내가 새로운 직업을 찾아야 한다는 뜻이다."

알고 보니 둘 다였습니다.

AI 코딩 에이전트는 단순히 "강력한 자동 완성(autocomplete on steroids)"이 아닙니다. 이들은 관찰(observe), 추론(reason), 행동(act), 그리고 평가(evaluate)를 연속적인 루프 속에서 수행하는 자율 시스템이며, 화려한 텍스트 예측기보다는 티켓을 처리하며 작업하는 주니어 개발자에 훨씬 더 가깝습니다. 이들이 실제로 내부에서 어떻게 작동하는지 이해하는 것은 사용 방식을 변화시키며, 만약 당신이 2026년의 개발자라면 이는 더 이상 선택 사항이 아닙니다.

이 글에서 저는 Claude Code, Codex CLI, Cursor, 그리고 Aider를 구동하는 아키텍처를 분석한 뒤, Python을 사용하여 100줄 미만으로 간단한 에이전트를 직접 구축하는 방법을 보여드리겠습니다.

에이전트 루프: 관찰, 추론, 행동, 반복

모든 AI 코딩 에이전트의 중심에는 Yao 등이 2022년에 소개하여 현재 거의 모든 LLM 기반 에이전트의 표준 아키텍처가 된 ReAct 패턴 (Reason + Act, 추론 + 행동)이라고 불리는, 보기에는 단순해 보이는 루프가 있습니다.

자연어 입력부터 도구 실행까지, 현대적 AI 코딩 에이전트의 4계층 아키텍처

이 루프는 작업이 완료될 때까지 반복되는 네 가지 단계로 구성됩니다:

관찰 (Observe): 에이전트는 프로젝트의 현재 상태를 읽습니다. 열려 있는 파일, 최근 터미널 출력, git diff, 린트(lint) 결과, 그리고 테스트 실패 내용을 살펴봅니다. 이는 단순히 "모든 것을 컨텍스트(context)에 쏟아붓는 것"이 아닙니다. 스마트한 에이전트는 파일 글로빙(file globbing), grep, 그리고 AST 분석을 사용하여 관련 있는 정보만을 가져옵니다.

Reason (추론): LLM은 관찰(observation) 내용을 원래의 작업 및 시스템 프롬프트(system prompt)와 함께 처리합니다. 모델은 다음의 구체적인 행동이 무엇이 되어야 할지 결정합니다. 이 단계가 모델의 품질이 가장 중요하게 작용하는 지점입니다. Claude와 GPT-5는 GPT-4o-mini나 Gemini Flash와 같은 더 작은 모델들보다 코드 구조에 대해 훨씬 더 뛰어난 추론 (reasoning) 능력을 보여줍니다.

Act (행동): 에이전트는 선택된 도구 호출 (tool call)을 실행합니다. 파일을 작성하거나, 테스트를 실행하거나, 코드베이스를 검색하거나, 셸 명령 (shell command)을 실행할 수 있습니다. 이 과정은 샌드박스 환경 (도구에 따라 서브프로세스 (subprocess), Docker 컨테이너, 또는 WASM 런타임)에서 이루어집니다.

Evaluate (평가): 에이전트는 결과를 기대치와 대조하여 확인합니다. 테스트가 통과했나요? 빌드가 성공했나요? 린트 (lint) 출력 결과가 깨끗한가요? 만약 무언가 실패했다면, 그 실패 결과가 다음 관찰 (observation)이 되어 루프 (loop)가 계속됩니다.

전형적인 작업은 5회에서 50회 사이의 반복 (iteration)을 거칩니다. 각 반복마다 한 번의 LLM API 호출 비용이 발생합니다. 이것이 코딩 에이전트가 단순한 채팅보다 더 비싼 이유이며, 효율적인 컨텍스트 관리 (context management)가 결정적인 엔지니어링 과제인 이유입니다.

도구 호출 (Tool Call)의 구조

에이전트가 행동하기로 결정하면, 구조화된 도구 호출을 생성합니다. 형식은 구현 방식에 따라 다르지만, 개념은 보편적입니다:

# LLM이 출력하는 내용 (구조화된 도구 호출)
{
  "tool": "write_file",
...

에이전트는 LLM 응답에서 이러한 도구들을 직접 호출하지 않습니다. 모델 출력과 실제 실행 사이에는 경로 탐색 공격 (path traversal attacks), 셸 인젝션 (shell injection), 그리고 프로젝트 디렉토리 외부로의 쓰기 작업을 검사하는 검증 레이어 (validation layer)가 존재합니다. 이 레이어가 없다면, 여러분은 LLM으로부터 생성된 임의의 코드를 자신의 기기에서 실행하게 되는 것이며, 이는 들리는 것만큼이나 매우 위험합니다.

4대 주요 플레이어 비교

현재 주목할 만한 4가지 주요 AI 코딩 에이전트가 있습니다. 이들은 각각 동일한 문제에 대해 근본적으로 다른 접근 방식을 취합니다.

4가지 주요 AI 코딩 에이전트의 기능 매트릭스 및 사용 사례별 강점 (2026년 7월)

Claude Code는 복잡한 다중 파일 리팩토링 (multi-file refactors) 및 심층 디버깅 (deep debugging)에 가장 뛰어납니다. 200K 컨텍스트 윈도우 (context window)를 통해 전체 코드베이스를 메모리에 유지할 수 있으며, Anthropic은 코딩 특화 학습에 막대한 투자를 해온 것이 분명합니다. 트레이드오프 (tradeoff): Claude 전용이며, 터미널 (terminal) 전용이고, Pro 액세스를 위해 월 20달러의 비용이 발생합니다. 브라우저 접근 권한이 없기 때문에 문서를 확인하거나 웹 UI를 테스트할 수 없습니다.

Codex CLI (OpenAI, MIT 라이선스)는 가장 유연한 옵션입니다. 완전한 오픈 소스이며, 모든 모델 (OpenAI, Anthropic, Gemini, Ollama)을 지원하고, API 키 비용 외에는 추가 비용이 들지 않습니다. 처음부터 전체 앱의 스캐폴딩 (scaffolding)이 필요한 그린필드 프로젝트 (greenfield projects)에서 탁월한 성능을 발휘합니다. 트레이드오프: 이 역시 터미널 전용이며, 다중 파일 편집 기능이 우수하지만 Claude Code만큼 정교하지는 않습니다.

Cursor Agent는 IDE 통합 워크플로 (IDE-integrated workflows) 측면에서 독보적입니다. 네이티브 에디터 통합, 문서 조회를 위한 브라우저 접근, UI 테스트 기능, 그리고 깊은 Git 인식 능력을 갖추고 있습니다. 트레이드오프: 독점 소프트웨어 (proprietary)이며, 가격은 월 20달러부터 시작하지만 새로운 에이전트 기능은 월 200달러에 육박합니다. 또한 샌드박스 환경 (sandboxed environment)에서 실행되므로 일부 터미널 작업이 제한됩니다.

Aider는 비용 효율성의 제왕입니다. 오픈 소스 (Apache 2.0)이며 모든 모델을 지원합니다. 최첨단 추론 (frontier reasoning)이 필요하지 않은 배치 작업 (batch operations)의 경우 GPT-4o-mini나 Gemini Flash와 같은 저렴한 모델로 실행할 수 있습니다. 변경 사항을 Git에 자동으로 커밋 (auto-commits)하므로 추적성 (traceability) 측면에서 매우 좋습니다. 트레이드오프: 터미널 전용이며 브라우저 접근 권한이 없고, Claude Code나 Codex CLI에 비해 터미널 기능이 제한적입니다.

저의 개인적인 설정: 복잡한 디버깅(debugging) 및 아키텍처 작업에는 Claude Code를, 신규 프로젝트(greenfield projects)에는 Codex CLI를, 대규모 리팩토링(refactors) 및 코드 리뷰(code review)에는 GPT-4o-mini를 사용하는 Aider를 활용합니다. UI 작업을 위해 브라우저 접근이 필요할 때는 Cursor를 사용합니다. 이 도구들은 경쟁 관계가 아니라 상호 보완적입니다.

직접 구축하기: 80줄로 만드는 최소 기능 에이전트

이론은 이 정도로 충분합니다. 지금 바로 실행해 볼 수 있는 작동 가능한 AI 코딩 에이전트가 여기 있습니다. 이 에이전트는 파일 읽기, 쓰기, 셸 실행(shell execution) 기능을 포함한 전체 ReAct 루프를 구현합니다:

import os, json, subprocess
from openai import OpenAI

...
```

json" in output:
            output = output.split("\n\n```json")[1].split("\n\n```")[0]
        elif "\n\n```" in output:
            output = output.split("\n\n```")[1].split("\n\n```")[0]

        action = json.loads(output)

...

이것은 약 80줄의 실제 코드이며 제대로 작동합니다. 이를 실행하면 다음과 같은 일이 일어납니다:

1. 에이전트가 작업(task)과 자신의 도구를 설명하는 시스템 프롬프트(system prompt)를 받습니다.
2. 파일을 생성해야 한다고 추론(reasoning)한 뒤, write_file("hello.py", ...)를 호출합니다.
3. 파일이 작성되었음을 확인하는 결과를 받습니다.
4. 파일이 제대로 작동하는지 확인해야 한다고 추론한 뒤, run_command("python3 hello.py")를 호출합니다.
5. "Hello from my AI agent!"라는 출력을 확인하고 작업을 완료로 표시합니다.

두 번의 반복(iterations). API 비용은 약 2센트 정도 소요됩니다.

프로덕션급 에이전트가 다른 점

80줄 버전은 연습용 예제에는 작동하지만, Claude Code와 같은 프로덕션(production) 에이전트는 여러 가지 중요한 계층을 추가합니다:

안전성 검증 (Safety validation): 프로덕션 에이전트는 어떤 도구를 실행하기 전에 입력을 검증합니다. .. 경로 탐색(traversal), rm -rf가 포함된 셸 명령, 프로젝트 루트 외부 디렉토리에 대한 쓰기 작업을 거부합니다. 일부는 seccomp 또는 Docker 샌드박스(sandboxes)를 사용합니다.

컨텍스트 윈도우 관리 (Context window management): 매 턴마다 전체 코드베이스를 보낼 수는 없습니다. 프로덕션 에이전트(Production agents)는 AST 인지 코드 검색을 위해 tree-sitter를, 빠른 텍스트 검색을 위해 ripgrep을 사용하며, 적절한 파일을 선택하기 위해 관련성 점수(relevance scoring)를 활용합니다. 일부는 턴이 지나도 주요 관찰 사항을 유지하는 "작업 메모리 (working memory)"를 유지합니다.

오류 복구 (Error recovery): 테스트가 실패하거나 빌드가 깨지면, 에이전트는 단순히 동일한 방식을 재시도하지 않습니다. 우수한 에이전트는 오류 메시지를 분석하고, 근본 원인(root cause)을 식별하며, 다른 전략을 시도합니다. 일부는 에이전트가 다음 행동을 계획하기 전에 무엇이 잘못되었는지 명시적으로 나열하는 "성찰 (reflection)" 단계를 구현합니다.

멀티 에이전트 협업 (Multi-agent coordination): 최첨단 기술(2026년 7월 발표된 Cursor의 에이전트 스웜(agent swarms))은 병렬로 실행되는 여러 에이전트 간에 작업을 분할합니다. 한 에이전트는 백엔드를 작성하고, 다른 에이전트는 프론트엔드를 작성하며, 세 번째 에이전트는 통합 테스트(integration tests)를 실행합니다. 이 지점에서 코딩 에이전트는 단일 개발자보다는 개발 팀에 더 가까워지기 시작합니다.

에이전트가 실패할 때 (그리고 그에 대한 대처법)

이 도구들을 몇 달 동안 매일 사용해 본 결과, 제가 가장 자주 목격하는 실패 모드(failure modes)는 다음과 같습니다:

무한 루프 (The infinite loop): 에이전트가 동일한 방식을 계속 시도하고, 동일한 방식으로 실패하며, 전혀 조정하지 못하는 현상입니다. 이는 오류 메시지가 모호하여 모델이 대안 전략을 식별할 수 없을 때 발생합니다. 해결책: N번의 연속된 실패 후에는 "포기하고 도움을 요청하기" 탈출구(escape hatch)를 추가하세요.

과잉 엔지니어링 (The over-engineer): 에이전트가 단순한 문제를 정교한 아키텍처로 해결하려 드는 경우입니다. 설정 파일 파서(config file parser)를 요청했는데 의존성 주입(dependency injection)이 포함된 플러그인 시스템을 구축해 버립니다. 해결책: 시스템 프롬프트(system prompt)에 "가장 단순한 솔루션을 선호할 것"을 포함하세요. 범위(scope)를 명시적으로 지정해야 합니다.

환각을 일으키는 API (The hallucinated API): 에이전트가 존재하지 않는 함수를 호출하거나 모듈을 임포트(import)합니다. 이는 모델의 학습 데이터에 지식 컷오프(knowledge cutoff) 이후에 출시된 라이브러리가 포함되어 있거나, 서로 다른 프레임워크 간의 유사한 API를 혼동할 때 발생합니다. 해결책: X에 의존하는 코드를 작성하기 전에 python3 -c "import X"를 실행하는 "임포트 확인 (verify imports)" 단계를 추가하세요.

컨텍스트 붕괴 (The context collapse): 에이전트가 처음에는 잘 작동하다가 20번째 반복(iteration)에 이르면 이전의 결정 사항들을 놓치기 시작합니다. 스스로 모순된 행동을 하거나, 이전 작업을 되돌리거나, 원래 작업의 제약 조건(constraints)을 잊어버립니다. 해결책: 시스템 프롬프트(system prompt)에 주기적으로 진행 상황을 요약하도록 하고, 턴(turn)이 바뀌어도 주요 결정 사항이 유지되는 구조화된 메모리(structured memory)를 사용하세요.

결론 (The Bottom Line)

AI 코딩 에이전트는 개발자를 대체하는 것이 아닙니다. 이들은 개발자들이 전혀 즐기지 않았던 개발의 부분들, 즉 보일러플레이트(boilerplate) 작성, 설정 파일 디버깅, 올바른 임포트 경로 찾기, 그리고 리팩터링(refactor) 후 테스트 업데이트 등을 대체하고 있습니다.

이러한 도구와 함께 번창하는 개발자는 아키텍처(architecture)를 이해하는 사람들입니다. 에이전트가 유한한 컨텍스트 윈도우(context window)를 가진 ReAct 루프를 실행하고 있다는 것을 알게 되면, 명확한 수락 기준(acceptance criteria)과 함께 집중된 작업을 부여하는 법을 배우게 됩니다. 도구 검증(tool validation)이 어떻게 작동하는지 이해하면, 왜 어떤 명령은 실패하고 어떤 명령은 실패하지 않는지 알게 됩니다.

제가 보여드린 80줄짜리 에이전트는 진정으로 유용합니다. 거기서부터 시작하세요. 오류 복구(error recovery)를 추가하고, 컨텍스트 관리(context management)를 추가하며, 안전 검증(safety validation)을 추가하세요. 어느샌가 여러분은 매주 몇 시간씩을 아껴주는 무언가를 구축하게 될 것입니다.

에이전트에게 위임할 것과 직접 작성할 것 사이의 경계선을 어디에 긋겠습니까?