코딩 에이전트는 어떻게 작동하는가

요즘 개발자 커뮤니티에서 코딩 에이전트 이야기가 정말 많이 나옵니다. Claude Code, Cursor, Windsurf, Copilot 등등 하루가 멀다 하고 새로운 도구가 등장하고 있죠. 그런데 이 도구들이 내부적으로 어떻게 돌아가는지 아는 사람은 의외로 많지 않습니다.

코딩 에이전트는 단순히 코드를 생성하는 것을 넘어서 파일을 읽고 명령어를 실행하고 테스트까지 돌리는 꽤 복잡한 시스템인데요. 그 중심에는 도구 사용(Tool Use)이라는 메커니즘이 있습니다. 이 글에서는 코딩 에이전트가 어떻게 작동하는지 그 원리를 하나씩 뜯어보겠습니다.

코드 완성에서 코딩 에이전트로

코딩 에이전트를 이해하려면 AI 코딩 도구가 어떻게 발전해왔는지 잠깐 돌아볼 필요가 있습니다.

처음에는 자동 완성 시대였습니다. 2021년에 등장한 GitHub Copilot이 대표적인데요. 코드를 타이핑하면 다음 줄을 예측해서 제안하는 방식이었습니다. 똑똑한 Tab 키 같은 느낌이라고 할까요.

그다음은 대화형 시대입니다. 2023년 ChatGPT가 등장하면서 자연어로 “이런 함수 만들어줘”라고 요청하면 코드를 통째로 생성해주기 시작했습니다. 다만 생성된 코드를 개발자가 직접 복사해서 에디터에 붙여넣어야 했죠.

2024년에는 인라인 편집 시대로 넘어갔습니다. Cursor나 Copilot이 에디터 안에서 여러 파일에 걸친 변경을 제안하기 시작했는데 개발자가 하나하나 검토하고 적용하는 건 여전했습니다.

그리고 2025년부터 본격적인 코딩 에이전트 시대가 열렸습니다. “이 이슈를 수정해줘”라고 지시하면 에이전트가 알아서 파일을 탐색하고 코드를 수정하고 테스트를 돌려서 검증하는 것까지 처리합니다. 개발자의 역할이 “코드를 직접 작성하는 사람”에서 “에이전트에게 의도를 전달하고 결과를 검토하는 사람”으로 바뀌기 시작한 거죠.

graph LR
    A["<b>자동 완성</b><br/>다음 줄 예측"] --> B["<b>대화형</b><br/>코드 생성 후 복붙"]
    B --> C["<b>인라인 편집</b><br/>여러 파일 변경 제안"]
    C --> D["<b>코딩 에이전트</b><br/>작업 전체를 자율 수행"]

기존 도구들이 개발자의 타이핑을 도와주는 것이었다면 코딩 에이전트는 작업 자체를 위임받아 수행합니다. 자동 완성이 수동 변속기를 돕는 크루즈 컨트롤이라면 코딩 에이전트는 목적지를 말하면 알아서 운전하는 자율주행에 가깝습니다.

에이전트 루프: 코딩 에이전트의 작동 방식

코딩 에이전트에게 “로그인 페이지 레이아웃이 모바일에서 깨지는데 수정해줘”라고 요청하면 어떤 일이 벌어질까요? 경험 많은 프론트엔드 개발자가 버그를 잡는 과정과 크게 다르지 않습니다.

graph TD
    A["<b>컨텍스트 수집</b><br/>관련 파일 읽기, 에러 분석"] --> B["<b>계획 수립</b><br/>해결 방안 결정, 수정 범위 파악"]
    B --> C["<b>실행</b><br/>코드 수정, 테스트 실행"]
    C -->|필요하면 반복| A

우선 컨텍스트를 수집합니다. LoginPage.tsx 파일을 열어보고 관련 CSS를 확인하고 반응형 스타일이 어떻게 적용돼 있는지 파악하는 단계입니다.

그다음 계획을 수립합니다. “미디어 쿼리가 768px 기준인데 모바일 뷰포트에서 flex 방향이 안 바뀌고 있으니 여기를 고치면 되겠다”는 식으로 방향을 잡죠.

마지막으로 실행에 들어갑니다. CSS를 수정하고 테스트를 돌려서 다른 페이지에 영향이 없는지 확인합니다.

여기서 중요한 건 이 과정이 한 번으로 끝나지 않는다는 점입니다. 수정 후 테스트가 실패하면 다시 에러를 분석하고 새 계획을 세우고 다시 실행합니다. 이 반복 구조를 에이전트 루프(Agent Loop)라고 부르는데 코딩 에이전트가 복잡한 작업을 처리할 수 있는 이유이기도 합니다. 단순히 코드를 한 번 생성하는 게 아니라 결과를 확인하며 스스로 교정해나갑니다.

언어 모델의 한계

그런데 한 가지 의문이 생깁니다. 에이전트 루프에서 컨텍스트 수집은 파일을 읽어야 하고 실행은 코드를 수정하거나 명령어를 실행해야 합니다. 언어 모델이 이걸 어떻게 하는 걸까요?

사실 언어 모델 자체로는 텍스트를 받아서 텍스트를 돌려주는 것이 전부입니다. 파일을 읽지 못하고 코드를 수정하지 못하고 터미널에서 명령어를 실행하지도 못합니다.

언어 모델에게 “package.json 파일 좀 보여줘”라고 직접 물어보면 아마 이런 대답이 돌아올 겁니다.

“죄송합니다. 저는 파일 시스템에 접근할 수 없어서 직접 파일을 읽을 수 없습니다.”

텍스트를 생성하는 게 할 수 있는 전부이니까요. 그러면 코딩 에이전트는 어떻게 파일도 읽고 코드도 고치고 테스트까지 돌리는 걸까요? 바로 도구 사용(Tool Use)이라는 시스템 덕분입니다.

도구 사용의 작동 원리

도구 사용이 돌아가는 원리는 의외로 단순합니다. 언어 모델에게 “특정 형식으로 응답하면 그 작업을 내가 대신 해줄게”라고 미리 알려주는 겁니다.

구체적인 흐름을 보겠습니다. 개발자가 “이 프로젝트에서 React 버전이 몇이야?”라고 물었다고 해볼까요?

sequenceDiagram
    participant CA as 코딩 에이전트
    participant LM as 언어 모델

    Note over CA: 개발자 질문:<br/>"React 버전이 몇이야?"
    CA->>LM: 질문 + 도구 사용 지침
    Note right of LM: "파일을 읽으려면<br/>ReadFile(파일명)<br/>형식으로 응답하세요"
    LM-->>CA: ReadFile("package.json")
    Note over CA: 실제로 파일 시스템에서<br/>package.json을 읽음
    CA->>LM: package.json 내용 전달
    LM-->>CA: "React 18.3.1입니다"
    Note over CA: 개발자에게 답변 전달

코딩 에이전트는 개발자의 질문을 언어 모델에게 그대로 보내지 않습니다. 질문과 함께 “파일을 읽고 싶으면 ReadFile(파일명) 형식으로 응답하세요” 같은 도구 사용 지침을 추가해서 전달합니다.

이 지침을 받은 언어 모델은 질문에 바로 답하지 않고 ReadFile("package.json")이라고 응답합니다. 코딩 에이전트는 이 응답을 파싱해서 실제로 파일 시스템에서 package.json을 읽어옵니다. 그리고 읽은 내용을 다시 언어 모델에게 보내죠. 이제 언어 모델은 파일의 실제 내용을 기반으로 “React 18.3.1입니다”라고 답할 수 있습니다.

겉으로 보면 언어 모델이 파일을 “읽고” 코드를 “수정하고” 명령어를 “실행하는” 것 같지만 실은 특정 형식의 텍스트를 생성하는 것뿐입니다. 진짜 작업은 코딩 에이전트가 중간에서 수행합니다.

언어 모델 ≠ 코딩 에이전트

여기까지 읽으셨다면 한 가지 중요한 사실을 눈치채셨을 겁니다. 언어 모델과 코딩 에이전트는 같은 게 아닙니다.

흔히 “ChatGPT가 내 코드를 고쳐줬어”라거나 “Claude가 버그를 찾았어”라고 표현하곤 합니다. 하지만 엄밀히 말하면 언어 모델 자체가 코드를 수정한 게 아닙니다. 언어 모델은 “이 파일을 수정하면 됩니다”라는 텍스트를 생성했을 뿐이고 실제 파일 수정은 그 주변의 에이전트 시스템이 처리한 겁니다.

flowchart TB
    subgraph Agent["코딩 에이전트 (전체 시스템)"]
        direction TB
        LM["<b>언어 모델</b><br/>텍스트 생성만 담당"]
        Tools["<b>도구 시스템</b><br/>파일 읽기/쓰기, 셸 실행"]
        Loop["<b>에이전트 루프</b><br/>반복 실행과 자기 교정"]
        Ctx["<b>컨텍스트 관리</b><br/>메모리, 요약, 압축"]
        Safety["<b>안전장치</b><br/>권한 관리, 샌드박싱"]
    end

코딩 에이전트는 언어 모델 하나로 이루어진 게 아닙니다. 언어 모델은 그 안의 한 구성 요소일 뿐이고 그 주변을 도구 시스템과 에이전트 루프, 컨텍스트 관리, 안전장치가 감싸고 있습니다.

이 구분이 왜 중요할까요? 같은 언어 모델이라도 어떤 에이전트 시스템 위에서 돌아가느냐에 따라 결과가 크게 달라지기 때문입니다. 동일한 모델을 웹 채팅창에서 쓰면 코드를 복사해서 직접 붙여넣어야 하지만 코딩 에이전트 안에서 쓰면 파일을 자동으로 수정하고 테스트까지 돌릴 수 있습니다.

그래서 코딩 도구를 비교할 때 “어떤 모델을 쓰느냐”만 볼 게 아니라 “에이전트 시스템이 얼마나 잘 만들어져 있느냐”도 함께 봐야 합니다. 도구를 얼마나 다양하게 제공하는지, 에이전트 루프가 얼마나 안정적으로 돌아가는지, 컨텍스트를 얼마나 효율적으로 관리하는지가 실제 사용 경험을 좌우하니까요.

에이전트가 사용하는 도구들

그렇다면 코딩 에이전트는 보통 어떤 도구를 갖고 있을까요? 제품마다 세부 사항은 다르지만 대부분의 코딩 에이전트가 공통으로 제공하는 도구들이 있습니다.

flowchart LR
    Task["작업 요청"] --> Agent

    subgraph Agent["코딩 에이전트"]
        LM["언어 모델"] <-->|도구 호출 / 결과 반환| Tools["도구 모음"]
    end

    subgraph Tools2["주요 도구"]
        direction TB
        F["파일 읽기/쓰기"]
        S["코드 검색"]
        B["셸 명령 실행"]
        W["웹 검색/문서 조회"]
    end

    Tools --> Tools2

가장 기본은 파일 읽기/쓰기입니다. 코드를 읽어서 분석하고 수정사항을 파일에 반영합니다. 이때 전체 파일을 덮어쓰는 게 아니라 변경된 부분만 적용하는 diff 방식을 쓰는 에이전트가 대부분이에요.

코드 검색도 빠질 수 없습니다. 파일명 패턴으로 찾는 Glob이나 코드 내용을 정규식으로 검색하는 Grep 같은 도구인데 수만 개 파일이 있는 프로젝트에서 관련 코드를 빠르게 찾아내야 하니까요.

셸 명령 실행은 npm test로 테스트를 돌리거나 git diff로 변경사항을 확인하는 데 씁니다. 빌드, 린트, 패키지 설치 같은 터미널 작업을 에이전트가 직접 수행할 수 있게 해주는 도구입니다.

그 밖에 웹 검색/문서 조회를 지원하는 에이전트도 많습니다. 라이브러리 공식 문서를 읽어오거나 Stack Overflow에서 해결책을 찾을 때 유용하죠.

여기에 더해 MCP(Model Context Protocol) 같은 확장 프로토콜을 통해 데이터베이스 쿼리나 외부 API 호출 같은 도구를 추가할 수도 있습니다. 결국 에이전트의 능력은 어떤 도구를 얼마나 잘 쓰느냐에 달려 있습니다.

컨텍스트 윈도우: 에이전트의 작업 기억

코딩 에이전트와 대화하다 보면 처음에 말한 내용을 에이전트가 까먹는 경우가 있습니다. 이건 컨텍스트 윈도우 때문인데요.

컨텍스트 윈도우란 언어 모델이 한 번에 처리할 수 있는 텍스트의 최대 크기입니다. 2026년 현재 모델에 따라 128K에서 1M 토큰 정도까지 다양한데요. 얼핏 들으면 넉넉해 보이지만 실제 코딩 작업에서는 금방 찹니다.

소스 코드 몇 개 읽어오고 테스트 출력 받아서 분석하고 에러 로그 확인하는 것만으로도 수만 토큰이 소모됩니다. 게다가 연구에 따르면 컨텍스트가 길어질수록 모델의 성능이 떨어지는 경향이 있다고 합니다. 특히 컨텍스트 중간에 있는 정보를 놓치기 쉬운 “Lost in the Middle” 현상도 알려져 있죠.

그래서 코딩 에이전트들은 다양한 방법으로 컨텍스트를 관리합니다. 대화가 길어지면 이전 내용을 자동으로 요약하거나 파일 전체를 넣는 대신 관련된 부분만 잘라서 넣는 식이죠. 일부 에이전트는 프로젝트 수준의 메모리 파일을 두고 대화가 끝나도 중요한 맥락을 유지하기도 합니다.

안전장치: 도구에는 제한이 필요하다

코딩 에이전트가 파일을 수정하고 셸 명령어를 실행할 수 있다는 건 그만큼 위험할 수도 있다는 뜻입니다. rm -rf / 같은 명령어를 실행하거나 프로덕션 데이터베이스를 건드리면 큰일이니까요.

그래서 대부분의 코딩 에이전트에는 안전장치가 마련되어 있습니다.

가장 흔한 건 권한 시스템입니다. 파일 읽기는 자유롭게 허용하되 파일 쓰기나 셸 명령 실행은 사용자 승인을 받도록 하는 거죠. 어떤 동작을 자동 허용하고 어떤 동작에 확인을 요구할지 개발자가 직접 설정할 수 있는 경우가 많습니다.

샌드박싱도 중요한 장치입니다. 에이전트가 실행하는 코드를 컨테이너나 가상머신 안에 격리해서 시스템 전체에 영향을 미치지 못하게 합니다. 네트워크 접근을 제한해서 외부 서버로 코드가 유출되는 것도 방지하고요.

결국 코딩 에이전트를 잘 활용하려면 적절한 권한을 설정하고 중요한 작업에는 반드시 사람이 확인하는 Human-in-the-Loop 방식을 유지하는 게 좋습니다. 강력한 도구일수록 안전하게 다루는 법을 아는 게 중요하니까요.

마치며

코딩 에이전트의 작동 원리를 한 문장으로 정리하면 이렇습니다. 언어 모델에게 도구라는 손과 발을 달아준 시스템입니다.

언어 모델 자체는 텍스트를 생성하는 것밖에 못 하지만 코딩 에이전트가 도구 사용 지침을 전달하고 호출 결과를 중개하면서 파일 탐색이나 코드 수정, 명령어 실행 같은 현실 세계의 작업이 가능해집니다. 이 과정이 에이전트 루프를 통해 반복되면서 단순한 코드 생성을 넘어 복잡한 프로그래밍 과제를 단계적으로 풀어갈 수 있게 되는 거죠.

자동 완성 시대에서 시작해 불과 몇 년 만에 작업 전체를 위임할 수 있는 수준까지 왔습니다. 앞으로 컨텍스트 윈도우가 더 커지고 도구 사용 능력이 더 정교해지면 코딩 에이전트가 할 수 있는 일의 범위는 계속 넓어질 겁니다. 다만 그때도 변하지 않을 건 코딩 에이전트의 동작 원리 자체입니다. 언어 모델과 도구 사용의 조합, 에이전트 루프를 통한 반복적 문제 해결이라는 기본 구조는 당분간 그대로일 테니까요.

코딩 에이전트를 직접 써보고 싶다면 클로드 코드로 시작해보는 것도 좋고 도구 확장에 관심이 있다면 MCP(Model Context Protocol)도 살펴보세요.