AI 코딩 도구를 실무에 붙일 때 가장 먼저 부딪히는 문제는 “코드를 생성하느냐”가 아닙니다. 문제는 생성된 코드가 제품 저장소 안에서 끝까지 검증되고, 실패하면 이유를 남기고, 위험한 변경 앞에서는 멈추는가입니다.
짧은 함수나 테스트 초안은 모델만으로도 충분히 좋아졌습니다. 하지만 실제 제품 개발은 한 번의 답변으로 끝나지 않습니다. 파일을 읽고, 변경 범위를 판단하고, 테스트를 실행하고, 실패 로그를 해석하고, 다시 고쳐야 합니다.
그래서 팀이 준비해야 할 것은 “더 긴 프롬프트”가 아니라, 에이전트가 안전하게 오래 일할 수 있는 실행 환경입니다.
이 글은 “코딩 에이전트 런타임 설계” 시리즈의 1편입니다. 결론부터 말하면, 코딩 에이전트는 더 이상 프롬프트 응답기가 아니라 목표, 상태, 권한, 검증을 가진 개발 런타임으로 봐야 합니다.
핵심 요약
- 기존 AI 코딩 도구의 기본 단위는
prompt였습니다. - 실제 개발 업무는 단일 프롬프트보다 길고 상태 의존적입니다.
- SWE-bench와 SWE-agent는 저장소 탐색, 파일 수정, 테스트 실행이 가능한 환경의 중요성을 보여줍니다.
- OpenAI Codex harness와 App Server 구조는 여러 UI보다 아래쪽의 agent loop와 thread state가 중요해지고 있음을 보여줍니다.
- 실무에서 필요한 것은 프롬프트 모음이 아니라 에이전트가 오래 일해도 안전한 작업 계약입니다.
프롬프트만으로는 개발을 끝낼 수 없다
초기 AI 코딩 도구의 사용 방식은 단순했습니다.
이 함수 리팩터링해줘.조금 더 구체적으로는 이렇게 요청했습니다.
auth 모듈 테스트 코드를 작성하고 실패하는 테스트를 고쳐줘.이런 요청은 여전히 유효합니다. 작은 함수 수정, 단일 컴포넌트 개선, 테스트 코드 초안에는 충분히 효과적입니다.
하지만 실제 제품 개발은 보통 이런 단일 요청으로 끝나지 않습니다. 예를 들어 결제 모듈을 다른 PG로 교체한다고 해보겠습니다. 이 작업에는 기존 결제 흐름 분석, API client 교체, webhook 수정, 환경 변수와 secret 관리, 테스트 수정, 배포 전 검증, 실패 시 rollback 계획까지 포함됩니다.
실제 흐름은 단일 응답보다 반복 실행 루프에 가깝습니다. 테스트가 실패하면 다시 수정으로 돌아가고, 통과하면 리뷰와 문서화로 넘어갑니다.
- 요구사항 이해
- 코드베이스 탐색
- 변경 범위 추정 / 구현 계획
- 파일 수정
- 테스트 실행
- 실패 원인 분석
- 재수정
- 리뷰
- 문서화
- 작업 상태 업데이트
여기서 중요한 것은 “한 번의 프롬프트”가 아니라 “작업 상태”입니다.
실제 개발 업무는 상태를 가진다
개발자는 작업 중에 많은 상태를 머릿속에 유지합니다.
| 상태 | 예시 |
|---|---|
| 목표 | 왜 이 기능을 바꾸는가 |
| 범위 | 어떤 파일과 모듈을 건드릴 수 있는가 |
| 제약 | DB schema 변경은 가능한가 |
| 검증 | 어떤 테스트를 통과해야 하는가 |
| 실패 이력 | 어떤 접근이 실패했는가 |
| 산출물 | 최종 diff, 테스트 로그, 리뷰 노트 |
AI 코딩 에이전트도 개발 업무를 제대로 수행하려면 이 상태를 다룰 수 있어야 합니다. 여기서 상태는 단순 대화 기록이 아닙니다. 대화 기록은 길고, 노이즈가 많고, 재검토하기 어렵습니다.
개발 워크플로우에 필요한 것은 아래처럼 분리된 구조화 상태입니다.
결국 코딩 에이전트는 응답 생성기보다 작업 실행기에 가까워집니다.
SWE-bench가 보여준 난이도
SWE-bench는 실제 GitHub issue와 pull request에서 추출한 소프트웨어 엔지니어링 문제를 평가하는 벤치마크입니다. 단순 알고리즘 문제가 아니라 실제 저장소 안에서 발생한 버그와 기능 수정 문제를 다룹니다.
SWE-bench의 핵심은 모델에게 코드베이스와 issue를 주고, 실제 테스트를 통과하는 patch를 만들도록 요구한다는 점입니다. Princeton의 SWE-bench 소개는 이 작업이 수천 줄 파일 속에서 문제를 찾고 여러 부분과 상호작용하는 수정을 만들어야 하는 문제라고 설명합니다.
이 지점이 중요합니다.
코딩 에이전트가 어려운 이유는 “코드를 모른다”가 아닙니다. LLM은 짧은 코드 조각은 꽤 잘 생성합니다. 어려운 것은 저장소 전체 맥락 안에서 어떤 파일을 읽어야 하고, 어떤 테스트를 실행해야 하며, 실패 로그를 어떻게 해석해야 하는가입니다.
즉 문제는 모델 지능만이 아니라 실행 환경입니다.
SWE-agent가 보여준 인터페이스의 중요성
SWE-agent 논문은 이 문제를 Agent-Computer Interface 관점에서 봅니다. 사람에게 IDE가 필요한 것처럼, 언어 모델 에이전트에게도 코드 탐색, 파일 수정, 테스트 실행에 맞춘 전용 인터페이스가 필요하다는 주장입니다.
Princeton의 논문 페이지는 SWE-agent의 custom interface가 코드 파일 생성과 편집, 저장소 탐색, 테스트 실행 능력을 개선했다고 설명합니다. 실무적으로 가져올 결론은 명확합니다.
좋은 코딩 에이전트는 좋은 프롬프트만으로 만들어지지 않는다. 좋은 실행 인터페이스와 작업 계약이 필요하다.
하네스는 단순히 모델을 호출하는 wrapper가 아닙니다. 에이전트에게 실행 인터페이스와 작업 계약을 함께 제공하는 환경입니다.
Codex harness가 시사하는 변화
OpenAI의 Codex harness와 App Server 글은 이 흐름을 제품 구조 관점에서 보여줍니다. Codex는 웹 앱, CLI, IDE 확장, macOS 앱 같은 여러 surface에서 동작하지만, 아래에서는 동일한 harness와 agent loop를 공유합니다.
그 글에서 Codex core는 agent code가 있는 library이면서 하나의 Codex thread를 persistence와 함께 관리하는 runtime으로 설명됩니다. App Server는 장기 실행 프로세스로 core thread를 호스팅하고, 클라이언트 요청과 서버 알림이 양방향으로 오가는 JSON-RPC API를 제공합니다.
개발자 관점에서는 이렇게 해석할 수 있습니다.
UI가 핵심이 아니다.핵심은 agent loop, thread state, workspace access, diff event, approval request다.VS Code, CLI, 웹 앱, 데스크톱 앱은 surface입니다. 진짜 중요한 것은 그 아래에서 목표를 유지하고, 작업 상태를 저장하고, 도구 실행을 통제하고, 검증 결과를 남기는 runtime layer입니다.
질문이 바뀐다
AI 코딩 도구를 평가할 때 질문도 바뀌어야 합니다.
| 예전 질문 | 이제 필요한 질문 |
|---|---|
| 코드 잘 짜나? | 목표를 오래 유지할 수 있나? |
| 응답 빠른가? | 작업 상태를 복구할 수 있나? |
| 테스트 짜주나? | 테스트 실패를 해석하고 재시도하나? |
| 파일 수정하나? | diff와 검증 결과를 산출물로 남기나? |
| 기억하나? | 무엇을 memory로 승격하고 무엇을 버리나? |
모델 성능은 중요합니다. 하지만 모델만으로는 충분하지 않습니다. 오래 실행되는 개발 작업에서는 잘못된 목표를 오래 실행하는 것도 위험이고, 검증 없이 “완료”라고 말하는 것도 위험입니다.
그래서 runtime 설계가 필요합니다.
실무적으로 무엇을 준비해야 하나
이 시리즈의 결론은 처음부터 거대한 멀티 에이전트 시스템을 만들자는 것이 아닙니다. 오히려 반대입니다. 작게 시작해야 합니다.
다만 시작점은 프롬프트 모음이 아니라 작업 계약이어야 합니다.
| 문서 | 역할 |
|---|---|
goal.md | 목표, 완료 조건, 중단 조건 |
run-ledger.md | 작업 단위 실행 기록 |
artifact-contract.md | 마지막에 남길 결과물 형식 |
memory-policy.md | 기억할 것과 버릴 것의 기준 |
permission-policy.md | 승인 필요 작업과 차단 작업 |
이 다섯 문서만 있어도 코딩 에이전트의 품질이 달라집니다. 프롬프트는 요청을 전달합니다. 하지만 작업 계약은 에이전트가 안전하게 오래 일할 수 있는 경계를 만듭니다.
적용 체크리스트
현재 팀의 코딩 에이전트 운영 방식을 점검할 때는 아래 항목부터 확인하면 됩니다.
[ ] 작업 목표가 한 문장으로 정리되어 있는가?[ ] 완료 조건이 테스트나 산출물로 확인 가능한가?[ ] 위험 작업의 중단 조건이 있는가?[ ] 실패한 시도를 대화가 아니라 기록으로 남기는가?[ ] 최종 응답이 아니라 검토 가능한 artifact를 남기는가?[ ] 반복 지식과 일회성 로그를 구분하는가?이번 편에서 가져갈 기준
코딩 에이전트를 도입할 때 첫 질문은 “어떤 모델을 쓸까”가 아니라 “이 에이전트가 어떤 runtime contract 안에서 일할까”여야 합니다. 최소한 목표, 허용 범위, 중단 조건, 검증 명령, 산출물 형식은 작업 전에 분리되어 있어야 합니다.
다음 편
2편에서는 Codex /goal을 출발점으로 목표 기반 개발을 다룹니다. 핵심은 명령어 사용법이 아니라 Goal Contract입니다.
시리즈 이어 읽기
- 1편: 코딩 에이전트는 왜 런타임이 되는가
- 2편: Codex
/goal로 보는 목표 기반 개발 - 3편: A2A와 MCP로 보는 멀티 에이전트 개발 워크플로우
- 4편: AI Memory는 RAG가 아니다
- 5편: 개발 하네스에 적용하는 AI 코딩 에이전트 문서 세트
댓글
GitHub 계정으로 로그인하면 댓글을 남길 수 있습니다. 댓글은 GitHub Discussions를 통해 운영됩니다.