Building AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned

이 논문은 IDE 플러그인에서 터미널 네이티브 에이전트로의 패러다임 전환에 맞춰, 안전성 강화와 컨텍스트 효율성 최적화를 통해 장기간 개발 작업을 자율적으로 수행할 수 있는 오픈소스 CLI 코딩 에이전트 'OPENDEV'의 아키텍처와 설계 원리를 제시합니다.

핵심

이 논문은 **'OPENDEV'**라는 새로운 인공지능 (AI) 도구에 대한 기술 보고서입니다. 쉽게 말해, 이 도구는 개발자들이 컴퓨터의 '명령어 창 (터미널)'에서 직접 코딩 작업을 도와주는 자율적인 AI 비서입니다.

기존의 AI 코딩 도구가 IDE(코드 편집기) 안에 숨어 있어 사용자가 매번 지시해야 했던 것과 달리, OPENDEV 는 터미널이라는 '작업 현장'에 직접 들어가 스스로 계획을 세우고, 파일을 수정하고, 명령어를 실행하며 복잡한 작업을 끝까지 해냅니다.

하지만 AI 가 너무 자유롭게 움직이다 보면 실수를 하거나, 기억력이 나빠져서 중요한 걸 잊어버릴 수 있습니다. 이 논문은 OPENDEV 가 어떻게 이런 문제들을 해결하고, 안전하게, 그리고 오랫동안 일할 수 있게 만들었는지 그 비밀스러운 설계도를 공개합니다.

이 복잡한 내용을 이해하기 쉽게 4 가지 핵심 비유로 설명해 드리겠습니다.

---

1. 🏗️ "한 명의 천재"가 아니라 "전문가 팀" (Compound AI System)

기존의 AI 는 모든 일을 혼자 하는 '혼자 일하는 천재'였습니다. 하지만 OPENDEV 는 작업별 전문가 팀을 꾸립니다.

• 상황: 집을 지으려고 할 때, 설계도만 그리는 건축가와 벽돌을 쌓는 기술자는 서로 다른 능력이 필요합니다.
• OPENDEV 의 방식:
  • 기획자 (Planner): 복잡한 문제를 분석하고 계획을 세웁니다. (이때는 무언가를 직접 건드리지 않고 생각만 합니다.)
  • 탐색가 (Code Explorer): 방대한 코드 속에서 필요한 정보를 찾아옵니다.
  • 실행자 (Main Agent): 실제 코드를 수정하고 명령어를 실행합니다.
  • 비평가 (Critic): "이 계획이 괜찮은가?"라고 다시 한번 점검합니다.
• 장점: 모든 일을 똑똑하지만 비싼 AI 에게 시키지 않고, 간단한 일은 빠르고 저렴한 AI 에게, 복잡한 일은 똑똑한 AI 에게 맡겨 비용과 시간을 아끼면서도 품질은 높입니다.

2. 🧠 "기억력"을 관리하는 지능적인 도서관 (Context Engineering)

AI 는 대화할 때마다 이전 내용을 기억해야 하는데, AI 의 '기억 공간 (컨텍스트 창)'은 한정되어 있습니다. 대화가 길어지면 중요한 정보가 잊히거나, 공간이 꽉 차서 더 이상 일할 수 없게 됩니다.

OPENDEV 는 이 문제를 지능적인 도서관 관리 시스템으로 해결합니다.

• 적응형 정리 (Adaptive Context Compaction):
  • 비유: 책상 위에 책이 쌓이다 보면 중요한 서류가 묻힙니다. OPENDEV 는 책상 공간이 70% 차면 "아직 괜찮아"라고 경고하고, 80% 차면 "오래된 잡동사니는 치워야겠다"라고 중요하지 않은 과거 대화는 요약본으로 바꾸거나 책장 (파일) 에 넣어둡니다.
  • 효과: AI 는 항상 최신 정보와 핵심 요약만 보고 있어도, 필요하면 다시 책장에서 상세한 내용을 꺼낼 수 있습니다. 덕분에 대화는 길어지더라도 AI 는 망가지지 않습니다.
• 기억력 보충제 (System Reminders):
  • 비유: 긴 회의를 하다 보면 "아, 우리가 처음에 정한 규칙이 뭐였지?"라고 잊어버리기 쉽습니다. OPENDEV 는 AI 가 실수하기 직전에 **"잠깐! 우리가 '파일 수정 전 반드시 테스트를 돌려야 한다'고 약속했었지?"**라고 귀띔해 줍니다.
  • 효과: AI 가 처음의 지시사항을 잊어버리는 '기억 상실' 현상을 막아줍니다.

3. 🛡️ "안전장비"를 여러 겹으로 껴입다 (Safety & Harness)

AI 가 터미널에서 명령어를 실행하면, 실수로 중요한 파일을 지우거나 서버를 멈출 수도 있습니다. OPENDEV 는 이를 막기 위해 5 단계의 안전장비를 착용합니다.

1. 규칙 책 (System Prompt): "절대로 위험한 명령어는 쓰지 마라"라고 처음에 가르칩니다.
2. 도구장 (Schema): 계획 단계에서는 '삭제' 도구를 아예 보이지 않게 숨겨둡니다. (보이지 않으면 쓸 수 없습니다.)
3. 승인 문 (Approval): 위험한 작업을 하려 하면 사용자에게 **"이거 정말 실행할까요?"**라고 물어봅니다.
4. 감시 카메라 (Validation): 명령어가 실행되기 직전에 "이건 위험해 보이는데?"라고 다시 한번 확인합니다.
5. 되돌리기 버튼 (Undo): 만약 실수가 나면, 마지막 단계마다 자동으로 백업을 해두기 때문에 한 번의 명령으로 모든 작업을 되돌릴 수 있습니다.

4. 🔄 "생각"과 "행동"을 분리하다 (Extended ReAct Loop)

기존 AI 는 "생각하면서 동시에 행동"하려다 보니, 생각할 시간이 부족해서 성급하게 실수를 저지르는 경우가 많았습니다.

• OPENDEV 의 방식: 생각 단계와 행동 단계를 명확히 나눕니다.
  • 생각 단계: "어떻게 해결할까?"라고 도구 없이 깊이 고민합니다.
  • 행동 단계: 결정을 내린 후, 비로소 도구를 사용하여 실행합니다.
• 비유: 요리사가 재료를 다듬기 전에 먼저 레시피를 머릿속으로 완벽하게 구상하는 것과 같습니다. 이렇게 하면 실수할 확률이 훨씬 줄어듭니다.

---

💡 결론: 왜 이 논문이 중요한가요?

이 논문은 단순히 "더 똑똑한 AI"를 만드는 법을 말하는 것이 아니라, **"AI 를 현실 세계의 위험한 작업 현장 (터미널) 에 안전하게 투입하는 공학적인 방법"**을 보여줍니다.

• 비용 절감: 필요한 때만 비싼 AI 를 씁니다.
• 안전성: 실수로 시스템을 망가뜨리지 않도록 여러 겹의 안전장치를 뒀습니다.
• 장기 작업: 기억력이 나빠지지 않아서 며칠, 몇 주 동안 이어지는 복잡한 프로젝트도 혼자 처리할 수 있습니다.

OPENDEV 는 AI 가 단순히 "코드 추천"을 하는 것을 넘어, 개발자의 진짜 파트너가 되어 함께 일하는 시대의 새로운 표준을 제시합니다. 마치 AI 가 이제 "도구 상자"를 들고 현장에 직접 내려와 일하는 현장 기술자가 된 것과 같습니다.

기술 요약

OPENDEV: 터미널 기반 AI 코딩 에이전트 구축을 위한 기술적 요약

이 논문은 OpenDev(OPENDEV) 라는 오픈소스 명령줄 인터페이스 (CLI) 기반 AI 코딩 에이전트를 소개하며, 복잡한 IDE 플러그인에서 벗어나 개발자가 소스 제어, 빌드, 배포를 직접 수행하는 터미널 네이티브 환경에서 작동하는 자율형 에이전트의 새로운 패러다임을 제시합니다.

1. 문제 정의 (Problem)

기존의 AI 코딩 도구는 주로 IDE 에 통합되어 수동적인 '코파일럿' 역할을 했으나, 최근 터미널 기반 에이전트 (Claude Code, Aider 등) 로의 전환이 가속화되고 있습니다. 그러나 장시간 실행되는 터미널 에이전트 구현에는 다음과 같은 근본적인 공학적 난제가 존재합니다.

• 컨텍스트 폭주 (Context Bloat): 장기간의 세션에서 토큰 예산을 초과하여 에이전트의 추론 능력이 저하되거나 시스템이 중단되는 문제.
• 파괴적 작업 위험: 에이전트가 임의의 쉘 명령어를 실행할 수 있어 실수로 중요한 파일을 삭제하거나 시스템을 손상시킬 수 있는 안전성 문제.
• 지시 사항 소실 (Instruction Fade-out): 대화 길이가 길어질수록 초기 시스템 프롬프트의 지시사항이 모델의 주의 (Attention) 영역에서 멀어져 에이전트가 규칙을 위반하거나 작업을 prematurely 종료하는 현상.
• 닫힌 소스 및 문서화 부재: 기존 상용 CLI 에이전트들은 소스가 공개되지 않았거나 기술적 설계 결정에 대한 문서가 부족하여 학술적·산업적 발전에 제약이 있었습니다.

2. 방법론 (Methodology)

OPENDEV 는 단일 거대 언어 모델 (LLM) 에 의존하지 않고, 컴파운드 AI 시스템 (Compound AI System) 아키텍처를 기반으로 설계되었습니다. 이는 다양한 모델, 검색기, 도구를 조합하여 최적의 성능을 내는 구조입니다.

2.1. 4 계층 시스템 아키텍처

1. Entry & UI: CLI(TUI) 및 Web UI 를 지원하며, 세션 관리, 모드 전환, 승인 요청 등을 처리합니다.
2. Agent Core (에이전트 코어):
   • Scaffolding (발판 구축): 세션 시작 전 시스템 프롬프트, 도구 스키마, 서브에이전트를 미리 구성 (Eager Construction) 합니다.
   • Harness (하네스): 런타임 중 도구 실행, 컨텍스트 관리, 안전성 강화를 조율합니다.
   • 이중 모드 (Dual-Mode): 'Plan Mode'(읽기 전용 서브에이전트 활용) 와 'Normal Mode'(전체 도구 접근) 를 분리하여 안전한 계획 수립과 실행을 보장합니다.
   • 확장된 ReAct 루프: 사고 (Thinking), 자기 비판 (Self-critique), 행동 (Action) 단계를 명확히 분리하여 추론의 깊이를 확보합니다.
3. Tool & Context (도구 및 컨텍스트):
   • 지연 도구 발견 (Lazy Tool Discovery): MCP(Model Context Protocol) 를 통해 필요한 도구만 컨텍스트에 로드하여 토큰 오버헤드를 최소화합니다.
   • 적응형 컨텍스트 압축 (Adaptive Context Compaction): 토큰 사용량이 70%~99% 에 따라 경고, 관측치 마스킹, 빠른 가지치기, LLM 기반 요약 등 5 단계로 점진적으로 압축합니다.
   • 이중 메모리 아키텍처: 장기 기억 (episodic memory, 요약) 과 단기 기억 (working memory, 최근 대화) 을 분리하여 사고 모델에 효율적인 컨텍스트를 제공합니다.
4. Persistence (영속성): 세션 기록, 설정, 파일 변경 로그 (Undo 기능) 를 로컬 JSON/JSONL 로 저장합니다.

2.2. 핵심 기술적 기법

• 작업별 모델 라우팅: 사고, 실행, 비판, 비전 (Vision), 압축 등 각 단계에 최적화된 별도의 LLM 을 할당하여 비용과 성능을 최적화합니다.
• 이벤트 기반 시스템 리마인더: 초기 프롬프트에 의존하지 않고, 에이전트가 실수할 가능성이 높은 시점 (예: 할 일 미완료, 오류 발생) 에 '사용자 역할 (role: user)' 메시지로 즉각적인 지시를 주입하여 주의 감소를 방지합니다.
• 심층 방어 (Defense-in-Depth) 안전성:
  1. 프롬프트 수준의 가드레일
  2. 스키마 수준의 도구 격리 (Plan Mode 에서 쓰기 도구 제거)
  3. 런타임 승인 시스템
  4. 도구 수준 유효성 검사 (위험 패턴 차단)
  5. 수명 주기 후크 (사용자 정의 스크립트)
  • 이 중 스키마 격리는 에이전트가 아예 위험한 도구를 보지 못하게 함으로써 가장 강력한 안전 장벽을 제공합니다.

3. 주요 기여 (Key Contributions)

1. 작업별 LLM 구성 가능한 컴파운드 아키텍처: 각 인지 작업 (사고, 실행 등) 마다 다른 모델을 유연하게 연결하여 비용과 지연 시간을 최적화합니다.
2. 확장된 ReAct 실행 파이프라인: 명시적인 사고 단계와 자기 비판 단계를 도입하여 에이전트의 성급한 행동을 방지하고 추론 품질을 높였습니다.
3. 장기적 행동 유도 (Behavioral Steering): 이벤트 기반 시스템 리마인더와 조건부 프롬프트 조립을 통해 장시간 세션에서도 에이전트가 지시사항을 따르도록 유도합니다.
4. 토큰 효율적 확장성 및 심층 방어 안전성: MCP 를 통한 지연 도구 발견과 5 단계 안전 계층을 도입하여 안전성을 유지하면서도 컨텍스트 효율성을 극대화했습니다.
5. 1 순위 엔지니어링 관심사로서의 컨텍스트 엔지니어링: 컨텍스트 관리를 단순한 최적화가 아닌 핵심 설계 원칙으로 삼고, 적응형 압축 및 경험 기반 메모리 파이프라인을 구현했습니다.

4. 결과 및 성과 (Results)

• 컨텍스트 효율성: 적응형 컨텍스트 압축 (ACC) 을 통해 관측치 (tool outputs) 의 피크 컨텍스트 소비를 약 54% 감소시켰으며, 일반적인 30 턴 세션에서 비상 요약 (emergency summarization) 이 필요 없는 경우가 많았습니다.
• 안전성: 스키마 레벨의 도구 격리와 5 단계 안전 계층을 통해 파괴적 명령어 실행을 구조적으로 차단했습니다.
• 유연성: 모델 변경이 코드 수정 없이 설정 파일 변경만으로 가능하도록 하여 모델 진화에 대응할 수 있는 유연한 구조를 입증했습니다.
• 실용성: 오픈소스로서 터미널 네이티브 인터랙티브 코딩 에이전트의 첫 번째 포괄적인 기술 보고서로서, 폐쇄형 상용 시스템과 오픈 학술 담론 사이의 격차를 해소했습니다.

5. 의의 및 의의 (Significance)

이 논문은 AI 코딩 에이전트의 미래가 단순한 코드 생성이 아닌, 터미널 환경에서 장기간 자율적으로 작동하는 에이전트 시스템에 있음을 보여줍니다.

• 엔지니어링 통찰: "컨텍스트는 버퍼가 아닌 예산 (Budget)"이라는 원칙 하에, 컨텍스트 관리가 에이전트의 수명을 결정하는 핵심 요소임을 강조했습니다.
• 안전성 패러다임 전환: 런타임 권한 체크보다는 스키마 레벨의 도구 제거가 더 강력한 안전 장치임을 증명했습니다.
• 오픈 소스 표준 제시: 기존에 블랙박스였던 상용 에이전트들의 설계 결정 (Design Decisions) 을 공개함으로써, 향후 자율형 소프트웨어 엔지니어링 연구와 개발의 기준점 (Blueprint) 을 제공합니다.
• 향후 방향: 컨텍스트 엔지니어링, 적응형 자원 할당, 구조화된 코드 표현을 통한 메모리 강화, 그리고 IDE 와 CLI 의 하이브리드 통합 등 향후 연구 방향을 제시했습니다.

결론적으로 OPENDEV 는 AI 에이전트가 개발자의 실제 작업 흐름 (Workflow) 에 자연스럽게 통합되어 복잡한 소프트웨어 엔지니어링 작업을 자율적으로 수행할 수 있는 기술적 토대를 마련한 중요한 성과입니다.