코딩 에이전트란 무엇인가#
코딩 에이전트는 코드를 읽고, 고치고, 실행하고, 검증하는 일을 돕는 AI 프로그램입니다. 실제 파일과 명령을 다룰 수 있지만 지원 도구와 권한에 따라 가능한 작업이 다르고, 완료와 정확성은 보장되지 않습니다. Mirr의 도구와 권한에서 접근 범위와 승인 설정을 확인하세요.
예를 들어 "로그인은 되는데 새로고침하면 계속 로그아웃돼"라는 과제를 아래처럼 나눠 요청할 수 있습니다. 실행 기록이 아닌 작업 예시입니다.
- 읽기 — 세션 코드와 관련 파일을 찾아 읽습니다.
- 수정 — 원인에 맞게 코드를 고칩니다.
- 실행 — 테스트나 빌드를 실행합니다.
- 검증 — 결과를 확인하고, 무엇이 바뀌었는지 설명합니다.
이 네 가지를 한 번에 이어가는 것이 코딩 에이전트입니다.
챗봇·자동완성·에이전트의 차이#
| 구분 | 하는 일 | 예시 |
|---|---|---|
| 챗봇 | 질문에 답을 말함 | "이 코드가 왜 안 돼?"에 대한 설명 |
| 자동완성 | 다음 코드를 제안 | Tab으로 함수 몸통 완성 |
| 코딩 에이전트 | 파일을 읽고, 고치고, 실행하고, 검증 | 세션 버그를 찾아 고치고 테스트까지 통과 |
이 표는 인터페이스를 이해하기 위한 구분입니다. 챗봇에도 도구가 붙을 수 있고 자동완성과 에이전트가 한 제품 안에 함께 있을 수 있으므로 이름보다 실제 접근 권한과 수행 범위를 확인하세요.
에이전트가 하는 네 가지: 읽기, 수정, 실행, 검증#
읽기는 단순히 파일을 나열하는 것이 아닙니다. 어디가 문제인지 찾기 위해 관련 파일과 심볼을 읽습니다. 저장소 전체를 읽을 수도 있고, 필요한 부분만 읽을 수도 있습니다.
수정은 요청한 범위 안에서 코드를 바꿉니다. 함수 이름을 바꾸거나, null 처리를 추가하거나, 테스트를 추가합니다. 요청하지 않은 파일은 건드리지 않아야 합니다.
실행은 명령과 테스트를 돌립니다. 고친 코드가 실제로 동작하는지 확인합니다. 실패하면 다시 고칩니다.
검증은 결과를 확인합니다. 테스트가 통과하는지, 무엇이 바뀌었는지, 왜 그런지 설명합니다. 이 단계가 없으면 에이전트는 코드만 생성하고 멈춥니다.
에이전트 루프는 어떻게 도는가#
에이전트는 대개 이런 순서로 일합니다.
- 의도 파악 — 사용자가 원하는 결과를 이해합니다.
- 계획 — 어디를 볼지, 무엇을 바꿀지 정합니다.
- 도구 사용 — 파일을 읽고, 검색하고, 명령을 실행합니다.
- 확인 — 결과를 보고, 다음 행동을 정합니다.
- 반복 — 끝날 때까지 이어갑니다.
반복 중에도 권한·비용·안전 조건을 벗어나면 멈춰야 합니다. 실행 실패는 원인을 확인하고, 이미 외부에 반영된 작업은 중복 실행하지 않도록 결과부터 조사하세요.
터미널 에이전트와 IDE 에이전트#
| 구분 | 터미널 에이전트 | IDE 에이전트 |
|---|---|---|
| 인터페이스 | CLI, TUI | 에디터, 확장 |
| 강점 | CI, 서버, 대규모 저장소, 자동화 | 시각적 diff, 빠른 편집, IDE 통합 |
| 약점 | 시각적 diff가 약함 | 로컬·에디터 의존 |
| 예시 | Claude Code, Codex, OpenCode, Mirr Code | Cursor, Copilot, Cline |
터미널과 IDE는 인터페이스의 차이입니다. 시각적 diff, CI 연동과 자동화 지원은 각 제품·버전에서 따로 확인해야 하며 어느 한쪽이 큰 저장소에 항상 더 적합한 것은 아닙니다.
한국 개발자에게 왜 중요한가#
한국 개발자에게는 세 가지가 실제로 중요합니다.
- 한국어로 지시하기. 영어로 바꾸지 않고 원하는 결과를 한국어로 입력합니다.
- 한국어 문서와 도구. 한글 파일명과 사내 시스템을 다루는 흐름을 확인합니다. HWPX·엑셀의 실제 읽기·수정·변환은 연결된 도구와 실행 환경에 따라 달라집니다.
- 한국어로 확인하기. 코드 수정 설명과 리뷰 코멘트를 한국어로 받습니다.
코딩 에이전트는 이 세 가지를 도와줍니다. 영어로 된 문서와 도구를 한국어로 연결하고, 한국어로 작업 결과를 확인하게 해 줍니다.
예제: 한 작업을 끝까지 시키기#
mirr -p "이 프로젝트의 실행 방법을 설명해 줘. 파일은 수정하지 마."
이 명령은 설명만 요청하는 예시이지 읽기 전용 권한을 강제하지 않습니다. 저장소를 읽기 전에 데이터 처리 조건을 확인하고 민감정보를 제외하세요. 대화형 작업에서는 Yolo를 끄고 Ask 모드와 도구 권한을 확인합니다. 일회성 -p 실행에 같은 승인 절차가 있다고 가정하지 말고, 필요한 경우 별도 격리 환경에서 파일·셸·네트워크 권한을 제한하세요.
다음은 작은 수정을 맡기는 예입니다.
mirr -p "UserProfile을 UserAccount로 바꿔. import와 테스트도 함께 고쳐 줘."
실행했다면 변경 diff와 실제 테스트 출력을 확인하세요. /rewind는 외부 게시·배포·DB 변경을 자동으로 되돌리지 않습니다. 복구 전에 추적되지 않은 파일과 다른 사람·프로그램의 변경은 따로 보관하세요. 세션과 복구를 참고하세요. 읽기→수정→테스트를 수행한 실제 transcript는 아직 확보하지 못했습니다.
자주 묻는 질문#
코딩 에이전트가 사람의 일을 대신하나요?#
아니요. 코드를 읽고, 고치고, 실행하고, 검증하는 일을 돕는 도구입니다. 설계와 판단, 실제 변경과 테스트 결과의 검토는 사람이 맡아야 합니다.
안전한가요?#
읽기만 요청해도 쓰기나 외부 전송이 차단되지는 않습니다. 민감정보를 제외하고 도구·운영체제·서비스 권한을 제한하세요. 체크포인트는 없거나 일부 파일을 복구하지 못할 수 있으므로 원본 백업과 변경 검토가 필요합니다.
영어로만 써야 하나요?#
한국어로 요청하고 코드와 오류 메시지는 원문으로 유지할 수 있습니다. REVIEW.md에 팀 기준을 적는 방법도 있지만 자동으로 읽히는지는 제품별 확인이 필요합니다. 필요한 기준을 요청에 직접 전달하고 결과를 검토하세요.
CI에서도 쓸 수 있나요?#
CI 연동은 제품의 비대화형 실행, 인증과 권한 지원에 따라 달라집니다. 이 글에서는 Mirr의 CI 실행이나 종료 코드 동작을 검증하지 않았습니다. 실제 환경에서 확인하기 전에는 자동 수정·게시를 활성화하지 마세요.
챗봇과 무엇이 다른가요?#
코딩 에이전트는 모델의 설명을 실제 파일·명령·도구 사용으로 이어갈 수 있습니다. 다만 챗봇에도 도구가 붙을 수 있으므로 이름보다 실제 지원 범위와 권한을 확인하세요. 에이전트도 오류나 권한·비용 제한으로 멈출 수 있습니다.
MCP와 무엇이 다른가요?#
MCP는 에이전트가 외부 도구와 데이터에 접근하는 표준입니다. 에이전트는 MCP를 통해 GitHub, 데이터베이스, 내부 API 등을 사용합니다.
처음 맡길 과제를 고르는 방법#
첫 과제로 로그인 전체를 고치거나 배포를 자동화하는 일부터 고를 필요는 없습니다. 파일 몇 개로 결과를 설명할 수 있고, 실패해도 원본으로 돌아갈 수 있는 과제가 좋습니다. 예를 들어 공개 연습 저장소의 날짜 표시 문구를 고치고 기존 테스트를 확인하는 일입니다. 바꿔야 할 문구와 그대로 둘 날짜 계산을 함께 적으면 변경 범위를 검토하기도 쉽습니다. 반대로 결제 처리, 고객 데이터 삭제, 운영 권한 변경처럼 결과가 외부에 남는 일은 파일 수정 연습과 분리하세요.
과제 설명에는 현재 동작, 원하는 동작, 수정 가능한 경로, 완료 기준을 넣습니다. “한국어 오류 메시지를 자연스럽게 고쳐 줘”보다는 “입력 검사의 오류 문구만 고치고 오류 코드와 HTTP 상태는 유지해 줘”가 검토할 대상을 더 잘 드러냅니다. 한국어 문장이 자연스러워졌더라도 호출자가 사용하는 오류 코드가 바뀌면 요구사항을 만족한 것이 아닙니다. 변경하지 말아야 할 계약도 결과물의 일부로 다루세요.
워크플로와 에이전트는 무엇이 다른가#
Anthropic은 에이전트 시스템을 설명하면서 두 종류를 구분합니다. 워크플로는 LLM과 도구를 미리 정해 둔 코드 경로로 엮은 시스템이고, 에이전트는 LLM이 처리 과정과 도구 사용을 스스로 정하며 작업 방식에 대한 통제를 유지하는 시스템입니다. 같은 글은 가능한 한 가장 단순한 해법을 먼저 고르고, 복잡도는 필요할 때만 올리라고 권합니다. 에이전틱 시스템은 흔히 지연 시간과 비용을 치르고 더 나은 작업 성능을 얻는다고 설명합니다.
코딩 작업에 대입하면 기준이 비교적 분명합니다. 린트, 포맷, 빌드처럼 순서가 정해진 검사는 스크립트로 묶는 편이 예측하기 쉽습니다. 반면 증상에서 원인을 찾고, 여러 파일을 함께 고치고, 테스트 결과에 따라 방향을 바꿔야 하는 버그 수정에는 에이전트가 맞습니다. 같은 글도 유연성과 모델의 판단이 필요할 때 에이전트가 더 나은 선택이라고 말합니다.
모델은 명령을 직접 실행하지 않는다#
Anthropic의 도구 사용 문서는 모델이 코드를 직접 실행할 수 없다고 설명합니다. 그래서 도구를 쓸 때마다 모델이 요청하고, 애플리케이션이 실행하고, 결과를 돌려주고, 모델이 이어 가는 왕복이 생깁니다. 응답의 stop_reason이 tool_use이면 루프가 계속되고, end_turn 같은 다른 값이 나오면 루프가 끝납니다.
이 구조에서 파일을 쓰고 명령을 실행하는 주체는 모델을 둘러싼 애플리케이션, 곧 하네스입니다. 같은 문서는 셸 명령이나 파일 편집처럼 Anthropic이 스키마를 공개한 도구도 실행은 애플리케이션이 맡는다고 설명합니다. 따라서 승인 설정과 실행 기록은 모델에게 조심하라고 부탁하는 문장이 아니라 실행 계층의 설정으로 확인하세요.
자율성이 커질수록 드는 비용#
Anthropic은 에이전트의 자율성에 비용 증가와 오류 누적이라는 대가가 따른다고 경고합니다. 에이전트는 여러 턴에 걸쳐 움직이고, Claude Code 문서가 설명하듯 도구 호출의 결과는 다음 판단의 근거가 됩니다. 그래서 초기의 잘못된 판단이 뒤의 행동으로 이어질 수 있습니다. 같은 글은 샌드박스처럼 격리된 환경에서 충분히 시험하고 적절한 안전장치를 두라고 권합니다.
처음 쓸 때는 실제 저장소 대신 복사본이나 별도 브랜치에서 실행하고, 도구가 몇 번 호출됐는지와 어떤 명령이 실행됐는지를 기록해 두세요. 그 기록이 있어야 다음 과제의 범위와 권한을 더 좁게 정할 수 있습니다. 격리 환경을 준비하기 어렵다면 최소한 작업 대상 폴더를 하나로 한정하고, 쓰기가 필요한 도구만 켜 두세요.
멈춤 조건과 사람의 확인 지점#
Anthropic의 에이전트 설명에 따르면 에이전트는 사람의 지시나 대화로 과제를 시작하고, 과제가 분명해지면 계획을 세워 스스로 움직입니다. 판단이나 정보가 필요할 때만 사람에게 돌아오며, 체크포인트나 막힌 지점에서는 피드백을 받기 위해 멈출 수 있습니다. 같은 글은 과제 완료 외에 최대 반복 횟수 같은 중단 조건을 두어야 통제를 유지할 수 있다고 말합니다.
요청에도 멈춤 조건을 함께 적어 두는 것이 좋습니다. 예를 들어 "같은 테스트가 세 번 연속 실패하면 원인과 시도한 수정을 정리하고 멈추세요"나 "인증 설정 파일을 바꾸기 전에 먼저 보고하세요" 같은 문장입니다. 이 문장은 제안 예시이며, 실제 제품에서 이런 조건을 어떻게 적용하는지는 설정 화면과 문서에서 확인하세요.
테스트가 통과해도 남는 검토#
Anthropic은 코드 해결책이 자동 테스트로 검증될 수 있고 에이전트가 테스트 결과를 피드백으로 삼아 반복할 수 있어서 소프트웨어 개발이 에이전트에 잘 맞는다고 설명합니다. 그러나 자동 테스트가 기능을 확인해 줄 뿐이며, 해결책이 시스템 전체의 요구사항과 맞는지는 사람의 검토가 여전히 중요하다고 덧붙입니다.
Claude Code 문서도 맥락을 모으고, 행동하고, 결과를 검증하는 단계가 섞여서 진행된다고 설명합니다. 따라서 검증 단계에서는 통과한 테스트 이름만 적지 말고, 확인하지 않은 동작과 아직 맞는지 모르는 요구사항도 함께 적어 두세요. 빠진 확인 항목이 다음 검토의 출발점이 됩니다.
도구 설명이 에이전트의 행동을 바꾼다#
Anthropic은 도구의 정의와 명세에도 전체 프롬프트만큼 공을 들여야 한다고 말합니다. 좋은 도구 설명에는 사용 예시, 경계 사례, 입력 형식 요구사항, 다른 도구와의 경계가 들어 있어야 합니다. 같은 글은 매개변수 이름과 설명을 팀의 신입 개발자에게 쓰는 문서 주석처럼 다듬으라고 권합니다. 모델이 도구를 잘못 고르거나 인자를 엉뚱하게 채운다면, 모델 탓을 하기 전에 도구 설명이 모호하지 않은지 먼저 봐야 합니다.
같은 글은 에이전트가 각 단계마다 도구 호출 결과나 코드 실행 결과처럼 환경에서 온 실제 신호를 얻어야 진행 상황을 평가할 수 있다고도 설명합니다. 실패 로그를 읽지 않고 다음 수정으로 넘어간다면, 이 신호를 제대로 쓰지 않은 상태라고 보아야 합니다.
파일 수정 형식과 변경 크기 확인#
Anthropic은 파일 수정을 diff로 적을지 파일 전체를 다시 쓸지에 따라 모델이 쓰기 어려운 정도가 달라진다고 설명합니다. diff는 바뀌는 줄 수를 청크 헤더에 미리 맞춰 써야 하고, 코드를 JSON 안에 넣으면 줄바꿈과 따옴표를 이스케이프해야 합니다. 같은 변경이라도 편집 방식에 따라 결과가 흔들릴 수 있습니다.
검토할 때는 요청한 함수 하나만 바뀌었는지, 관련 없는 파일이나 줄 바꿈이 많이 바뀌지 않았는지 diff 크기부터 확인하세요. 요청과 무관한 변경이 크면 편집 방식을 의심하고, 되돌린 뒤 대상 파일과 범위를 좁혀 다시 요청하는 편이 낫습니다.
변경 크기는 요청과 무관한 파일이 얼마나 바뀌었는지를 알려 줍니다. 에이전트는 요청한 함수 하나를 고치려다 인접 파일이나 설정을 함께 바꿀 수 있고, 이 범위를 diff로 확인하는 것이 에이전트를 신뢰하는 최소한의 기준입니다. 요청과 무관한 변경이 크면 그 이유를 추측하기보다, 대상과 범위를 좁혀 다시 돌리는 편이 결과를 예측하기 쉽습니다. 이 기준을 지키면 에이전트가 끝까지 처리한 작업과 사람이 승인한 작업을 결과로 구분할 수 있고, 다음 과제의 범위를 더 정확히, 그리고 반복 가능한 기준으로 정할 수 있습니다.
편집 메모#
편집 메모 (2026-11-02): 설명 요청의 읽기 전용 보장, 무조건적인 안전·완료 표현과 REVIEW.md·CI 일반화를 바로잡았습니다. 명령은 미실행 예시이며 실제 작업 transcript는 아직 없습니다. 기존 2026-10-31 표시는 이번 부분 수정의 전체 검증일로 갱신하지 않았습니다.