Claude Code와 새로운 터미널 AI 코딩 도구의 물결

CLI 코딩 에이전트의 실제 구성

터미널 코딩 에이전트는 보통 다섯 가지 요소를 결합한 형태입니다.

• 최첨단 모델 또는 공개 모델과의 채팅 루프
• 저장소 인덱서 또는 파일 탐색 계층
• 셸 명령과 파일 편집을 위한 도구 실행 계층
• 패치 적용 메커니즘
• 대화 기록과 세션 상태를 저장하는 영속성 계층

자동 완성과의 핵심 차이는 자율적으로 행동하는 능력입니다. 자동 완성은 커서 위치의 코드를 예측합니다. 에이전트는 파일을 살펴보고, 테스트를 실행하고, 코드를 수정하고, 실패 원인을 확인하고, 이 과정을 반복하기로 결정할 수 있습니다.

일반적인 루프는 다음과 같습니다.

User task
  ↓
Agent builds prompt from instructions + repo context + prior messages
  ↓
Model proposes actions: read file, edit file, run command
  ↓
CLI executes allowed actions
  ↓
Results are added back into context
  ↓
Model plans next step
  ↓
Repeat until done or stopped

이 루프 덕분에 이러한 도구가 강력하게 느껴집니다. 또한 비용과 지연 시간이 일반적인 “질문 하나에 답변 하나” 방식의 API 사용과 다르게 나타나는 이유이기도 합니다.

실제로 예상 밖의 비용은 대부분 피드백 경로에서 발생합니다. 명령 출력, 파일 내용, 이전 메시지, diff가 이후 턴에 반복적으로 포함되기 때문입니다.

Claude Code, Aider, Cline, OpenCode: 같은 패턴의 서로 다른 형태

도구마다 상호작용 방식은 다르지만, 핵심적인 엔지니어링 패턴은 비슷합니다.

중요한 차이는 “어느 도구가 가장 똑똑한가”가 아닙니다. 도구가 얼마나 많은 컨텍스트를 보내는지, 파일을 어떻게 선택하는지, 기록을 어떻게 요약하는지, 그리고 셸 실행을 얼마나 제어할 수 있는지가 중요합니다.

예를 들어 Aider는 관련 파일을 의도적으로 추가할 때 잘 작동하는 편입니다. Claude Code는 더 자율적으로 행동하며 저장소를 돌아다니는 시니어 엔지니어처럼 느껴질 수 있지만, 그 자율성만큼 권한과 범위를 신중하게 설정해야 합니다. Cline은 편집기 안에서 사용하기 편리하며, 특히 작업 과정을 지켜보고 싶을 때 유용합니다. 하지만 편집기의 편리함 때문에 비용이 많이 드는 단계를 지나치게 많이 승인하기 쉬워질 수 있습니다.

OpenCode 방식의 워크플로는 공급자 선택의 유연성을 원하는 팀에 매력적입니다. 어려운 아키텍처 작업에는 Claude, 구현에는 GPT, 대규모 컨텍스트 검토에는 Gemini를 사용하거나, 비용을 낮춘 로컬 또는 자체 호스팅 작업에는 Qwen, DeepSeek, Kimi, MiniMax, Llama 같은 공개 모델을 사용할 수 있습니다.

이 에이전트들이 API를 사용하는 방식

“이 버그를 수정해 줘”라는 요청 하나가 수십 번의 API 호출로 이어질 수 있습니다.

에이전트의 한 단계에 사용되는 요청 본문을 단순화하면 다음과 같습니다:

{
  "model": "claude-sonnet-4.6",
  "messages": [
    {
      "role": "system",
      "content": "You are a coding agent. Follow repo instructions. Use tools safely."
    },
    {
      "role": "user",
      "content": "Fix the failing invoice total test."
    },
    {
      "role": "assistant",
      "content": "I will inspect the test and related invoice code."
    },
    {
      "role": "tool",
      "name": "read_file",
      "content": "tests/test_invoice_totals.py contents..."
    }
  ],
  "tools": [
    { "name": "read_file" },
    { "name": "apply_patch" },
    { "name": "run_shell" }
  ]
}

실제 구현은 다양하지만, 패턴은 일관됩니다:

1. CLI가 컨텍스트를 수집합니다.
2. 모델이 다음 작업을 결정합니다.
3. CLI가 해당 작업을 수행합니다.
4. 결과를 모델에 다시 전달합니다.
5. 모델이 작업을 이어갑니다.

도구를 제공하는 방식은 보통 두 가지입니다.

텍스트 기반 도구 프로토콜

일부 에이전트는 모델에 구조화된 텍스트를 출력하도록 요청합니다:

RUN: pytest tests/test_invoice_totals.py -q

CLI가 이를 파싱하고 실행합니다. 이 방식은 단순하고 이식성이 좋지만, 쉽게 오류가 발생할 수 있습니다. 모델이 명령을 이상한 형식으로 출력하면 실행 프레임워크에 보호 장치가 필요합니다.

네이티브 함수 호출

다른 에이전트는 모델 API의 도구/함수 호출 기능을 사용합니다. 모델은 구조화된 도구 호출을 반환합니다:

{
  "tool_name": "run_shell",
  "arguments": {
    "command": "pytest tests/test_invoice_totals.py -q",
    "timeout_seconds": 60
  }
}

이 방식은 검증하기가 더 쉽습니다. 에이전트는 위험한 패턴과 일치하는 명령을 거부하거나, 네트워크 접근에 승인을 요구하거나, 쓰기 작업을 워크스페이스로 제한할 수 있습니다.

두 설계 모두에서 비용이 많이 드는 부분은 셸 명령이 아닙니다. 셸 명령을 둘러싸고 점점 커지는 프롬프트입니다.

에이전트 루프가 토큰 비용 구조를 바꾸는 이유

일반적인 API 연동에서는 입력 토큰 2,000개를 보내고 출력 토큰 500개를 받을 수 있습니다. 에이전트 코딩 세션은 다음과 같이 진행될 수 있습니다:

주의할 점은 입력 토큰이 비용의 대부분을 차지하는 경우가 많다는 것입니다. 루프마다 시스템 지침, 대화 이력, 선택한 파일, 도구 출력, 요약을 다시 전송할 수 있습니다. 캐싱이나 컨텍스트 압축을 사용하더라도, 모델이 상황을 모른 채 행동하지 않으려면 충분한 상태 정보가 필요하므로 긴 자율 작업 세션은 비용이 많이 들 수 있습니다.

토큰 사용량을 늘리는 흔한 요인은 네 가지입니다:

• 전체 파일 컨텍스트: 함수 두 개만 중요해도 900줄짜리 파일을 전송하는 경우입니다.
• 장황한 테스트 출력: 의존성 경고, 진행률 표시줄, 관련 없는 실패까지 포함하는 경우입니다.
• 반복적인 저장소 스캔: 다음 명령을 find, tree, 또는 rg 광범위하게 실행하고 그 출력을 다시 컨텍스트에 넣는 경우입니다.
• 제한 없는 대화 이력: 결정을 요약하는 대신 실패한 시도를 모두 보존하는 경우입니다.

복잡하게 꼬인 세션에서 실제로 일어나는 일은 “에이전트가 더 깊이 생각하는 것”이 아닙니다. 그저 오래되어 유효하지 않은 컨텍스트를 더 많이 보는 경우가 많습니다. 관련 정보가 묻혀 있으면 토큰이 많아질수록 모델이 느려지고 정확도가 떨어질 수 있습니다.

사고방식: 프롬프트가 아닌 루프 단위로 예산 책정하기

저는 비용을 추산할 때 루프 단위로 생각합니다.

범위가 작고 목표가 명확한 작업은 다음과 같을 수 있습니다:

8 turns × 12k input tokens average = 96k input tokens
8 turns × 1.5k output tokens average = 12k output tokens

방향을 잡지 못하고 헤매는 작업은 다음과 같을 수 있습니다:

35 turns × 55k input tokens average = 1.9M input tokens
35 turns × 3k output tokens average = 105k output tokens

사용자 프롬프트는 같습니다. 비용 구조는 크게 다릅니다.

문제의 양상을 파악하는 데 정확한 요금까지 알 필요는 없습니다. 에이전트 세션의 비용은 다음 요인에 따라 커집니다:

total cost ≈ Σ(input_tokens_per_step × input_price)
           + Σ(output_tokens_per_step × output_price)
           + tool/runtime overhead

출력 토큰은 에이전트가 입력하는 모습을 볼 수 있어 눈에 보입니다. 입력 토큰은 CLI가 조합하므로 눈에 보이지 않습니다. 예산을 엄격하게 관리해야 하는 부분은 바로 이 보이지 않는 쪽입니다.

에이전트 작업에 사용할 모델 선택

저는 모든 작업에 하나의 모델만 사용하는 경우가 거의 없습니다.

터미널 에이전트에서는 작업 단계에 맞춰 모델을 선택해야 합니다:

실용적인 구성에서는 대부분의 코딩에 Sonnet급 모델, 어려운 디버깅이나 설계에 Opus/GPT-5.5급 모델, 대규모 검토에 Gemini/Fable 스타일의 긴 컨텍스트 모델, 로컬 린트 방식의 리팩터링에 오픈 모델을 사용할 수 있습니다. 정확한 이름은 바뀌겠지만 이 패턴은 유지됩니다.

흔한 실수는 전체 루프에 가장 비싼 모델을 사용하는 것입니다. 그러면 비싼 모델이 고가의 토큰을 사용해 다음 항목을 읽게 됩니다: node_modules주변의 불필요한 정보, 테스트 경고, 생성된 파일. 가장 강력한 모델은 실제로 그 성능이 필요한 결정에 사용하세요.

중요한 설정 팁

최선의 설정은 “최대한의 자율성”이 아닙니다. “제한된 권한으로 빠르게 피드백을 받는 것”입니다.

1. 생성된 파일과 외부 라이브러리 파일 제외하기

모든 코딩 에이전트에는 제외 목록이 있어야 합니다. 검색과 검토에서 제외하는 항목부터 시작하세요:

node_modules/
dist/
build/
coverage/
.venv/
__pycache__/
target/
vendor/
*.lock
*.min.js
*.map

저는 작업에 의존성 해결이 포함되면 보통 잠금 파일을 전역적으로 제외하지 않지만, 기본 컨텍스트에서는 제외합니다. 필요할 때 잠금 파일을 명시적으로 불러올 수 있습니다.

2. 범위가 좁은 테스트 명령 사용하기

에이전트가 매번 반복할 때마다 기본적으로 전체 테스트 모음을 실행하지 않도록 하세요. 단계별 명령을 제공하세요:

# First loop: fastest relevant test
pytest tests/billing/test_invoice_totals.py -q

# Second loop: nearby package
pytest tests/billing -q

# Final confidence check
pytest -q

JavaScript 또는 TypeScript의 경우:

pnpm test invoice-total.test.ts -- --runInBand
pnpm lint src/billing
pnpm test

핵심은 실행 시간만이 아닙니다. 출력이 작아지면 다음 루프의 프롬프트도 작아집니다.

3. 명령 출력 제한하기

에이전트가 출력 제한을 지원하면 활용하세요. 지원하지 않으면 직접 명령을 감싸세요:

pytest tests/billing -q 2>&1 | tail -120

출력이 많은 빌드의 경우:

pnpm test 2>&1 | grep -E "FAIL|Error|Expected|Received|at " | head -200

주의하세요. 필터링은 유용한 컨텍스트를 숨길 수 있습니다. 저는 첫 실패 전에 적용하지 않고, 첫 실패 이후에 사용합니다. 먼저 실패의 양상을 확인한 다음, 반복 실행을 제한하세요.

4. 전체 재작성 대신 diff 요청하기

큰 파일을 다룰 때는 에이전트에게 다음과 같이 명시적으로 지시하세요:

Make the smallest safe patch. Do not rewrite unrelated functions.
Show a concise diff summary before running tests.

이렇게 하면 위험이 줄고 대개 출력 토큰도 줄어듭니다. 더 중요한 것은 코드 검토를 감당할 수 있는 수준으로 유지해 준다는 점입니다.

5. 계획과 실행 분리하기

복잡한 변경 작업에서는 대개 다음과 같이 시작합니다.

Inspect the relevant files and propose a plan. Do not edit yet.
Limit repo inspection to payment, invoice, and tax modules unless needed.

그런 다음 계획을 승인하고 구현하도록 합니다. 이렇게 하면 “에이전트가 이해하기 전에 수정하는” 실패 패턴을 피할 수 있습니다.

긴 세션에서 비용 관리하기

긴 세션은 CLI 에이전트가 진가를 발휘하는 동시에 위험해지는 상황입니다.

실제 업무에서 사용하는 비용 관리 체크리스트는 다음과 같습니다.

• 세션 목표 설정하기: “청구 기능 수정”이 아니라 “ test_invoice_rounding 통과시키기”를 목표로 삼습니다.
• 가능하면 파일 지정하기: 에이전트에게 모든 것을 찾아내도록 요청하는 대신 정확한 경로를 제공합니다.
• 작업 방향이 바뀌면 컨텍스트 초기화하기: 작업이 바뀌면 요약과 함께 새 세션을 시작합니다.
• 실패 내용 직접 요약하기: 3,000줄짜리 로그 대신 중요한 30줄을 붙여 넣습니다.
• 더 강력한 모델로 의도적으로 전환하기: 명확한 장애물에 부딪힌 뒤에만 더 강력한 모델을 사용합니다.
• 루프가 반복되면 중단하기: 에이전트가 같은 방식으로 두 번 실패하면 개입합니다.

좋은 초기화 프롬프트는 다음과 같습니다.

We are fixing invoice rounding.

Known facts:
- Failure is in tests/billing/test_invoice_totals.py::test_round_half_even
- Expected 10.24, actual 10.25
- Decimal quantization happens in src/billing/money.py
- Tax calculation calls round_money() from src/billing/tax.py

Continue from this summary. Inspect only those files first.

이 프롬프트는 실패한 대화 전체를 계속 가져가는 것보다 비용이 적게 들고 더 명확할 수 있습니다.

API 키, 제공업체 및 라우팅

대부분의 CLI 에이전트는 모델 제공업체의 API에 직접 연결하거나 호환 게이트웨이를 통해 연결할 수 있습니다. 주요 엔지니어링 고려 사항은 다음과 같습니다.

• 인증: API 키가 어디에 저장되며 셸 기록이나 로그에 유출되는지 여부.
• 모델 라우팅: 각 단계를 어떤 모델이 처리하는지.
• 요청 속도 제한: 에이전트 루프는 짧은 시간에 많은 요청을 보낼 수 있습니다.
• 관측 가능성: 세션별 토큰 및 비용 보고.
• 데이터 경계: 코드를 외부 API로 보낼 수 있는지 여부.

최소한의 환경 설정은 대개 다음과 같습니다.

export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
export GEMINI_API_KEY="..."

팀에서는 모델을 선택하고 사용량을 기록하는 래퍼 스크립트를 선호합니다.

#!/usr/bin/env bash
set -euo pipefail

export AGENT_MODEL="${AGENT_MODEL:-sonnet}"
export AGENT_MAX_OUTPUT_TOKENS="${AGENT_MAX_OUTPUT_TOKENS:-4096}"
export AGENT_SESSION_BUDGET_USD="${AGENT_SESSION_BUDGET_USD:-10}"

coding-agent "$@"

여러 모델을 지원하는 게이트웨이를 사용한다면, 하나의 인터페이스를 통해 Claude, GPT, Gemini 또는 오픈 모델 트래픽을 라우팅하는 데 유용할 수 있습니다. 중요한 기능은 로고 목록이 아니라 신뢰할 수 있는 사용량 집계와 모델별 제어를 제공하는지 여부입니다.

저장소 지침에 포함하는 내용

대부분의 에이전트는 어떤 형태로든 저장소 지침 파일을 따릅니다. 저는 지침을 짧고 실무적으로 유지합니다.

## Agent Instructions

- Prefer minimal diffs over rewrites.
- Do not run full test suites until targeted tests pass.
- Never edit generated files in `dist/`, `build/`, or `coverage/`.
- Use `rg` for search.
- Before large refactors, propose a plan and wait.
- If a command emits more than 200 lines, rerun with a narrower command.

이것은 예의를 갖추는 문제가 아닙니다. 루프의 동작 방식을 결정하는 일입니다. 에이전트는 여전히 실수하겠지만, 좋은 지침은 반복적인 낭비를 줄여 줍니다.

흔히 놓치는 함정이 있습니다. 지나치게 긴 지침 파일은 배경 잡음이 됩니다. 에이전트 지침이 스타일 철학에 관한 300줄로 채워져 있으면 모델은 중요한 세 가지 운영 제약을 놓칠 수 있습니다. 가치가 높은 규칙을 먼저 배치하세요.

지연 시간: 또 다른 비용

토큰 비용이 감당할 만하더라도 지연 시간은 작업 흐름을 끊을 수 있습니다.

에이전트 지연 시간은 다음에서 발생합니다.

• 모델 추론 시간
• 도구 실행 시간
• 파일 인덱싱 시간
• 테스트 실행 시간
• 사람의 승인을 기다리는 시간

빠르게 반복하는 작업에서는 “다음으로 유용한 관찰 결과를 얻기까지 걸리는 시간”을 최적화합니다. 15초짜리 특정 테스트가 6분짜리 전체 CI 시뮬레이션보다 낫습니다. 4초 만에 구문 오류를 정확히 찾아내는 작은 모델이 훌륭한 설명을 작성하는 데 45초를 쓰는 프리미엄 모델보다 낫습니다.

가장 좋은 세션은 페어 프로그래밍처럼 느껴집니다.

inspect → patch → targeted test → inspect failure → patch → targeted test → final suite

가장 나쁜 세션은 CI 흉내 내기처럼 느껴집니다.

scan repo → edit many files → run everything → drown in logs → repeat

한계와 실패 패턴

터미널 에이전트는 유용하지만 마법 같은 도구는 아닙니다.

다음과 같은 상황에서 어려움을 겪습니다.

• 저장소에 테스트로 포착되지 않는 숨겨진 런타임 의존성이 있습니다.
• 작업에 코드 변환보다 제품에 관한 판단이 필요합니다.
• 오류가 외부 서비스나 불안정한 상태에 따라 발생합니다.
• 코드베이스에 오해를 유발하는 추상화나 오래된 문서가 있습니다.
• 에이전트가 관련 검증 명령을 실행할 수 없습니다.

그럴듯하지만 잘못된 수정안을 만들기도 합니다. 특히 테스트가 부실할 때 이런 일이 흔합니다. 에이전트가 동작을 검증할 수 없다면 그 결과물을 주니어 엔지니어의 검토되지 않은 패치처럼 취급하세요. 유용할 수는 있지만, 절대 자동으로 신뢰해서는 안 됩니다.

보안도 중요합니다. 도구의 승인 방식을 이해하지 못한 상태에서 민감한 저장소에 대한 무제한 셸 접근 권한을 에이전트에게 부여하지 마세요. 제한하지 않는 한 “명령 실행”에는 환경 변수 출력, 파일 수정, 패키지 설치, 네트워크 접근 기능도 포함됩니다.

실무 핵심 요점

• CLI 코딩 도구를 단일 프롬프트가 아니라 API 기반 제어 루프로 다루세요.
• 루프 횟수와 컨텍스트 크기, 특히 명령 출력을 줄여 비용을 최적화하세요.
• 강력한 모델은 모든 기계적인 단계가 아니라 어려운 추론에 사용하세요.
• 저장소 지침은 짧고 실무적이며 에이전트 동작에 초점을 맞추도록 유지하세요.
• 특정 테스트를 먼저 실행하고, 더 넓은 범위의 검증은 마지막에 수행하세요.
• 오래된 기록을 계속 가져가는 대신 간결한 요약으로 긴 세션을 초기화하세요.
• 입력 토큰을 주시하세요. 에이전트 기반 코딩에서 눈에 잘 띄지 않는 주요 비용 발생 요인입니다.
• 에이전트가 실패한 전략을 반복하면 중단하고 개입하세요.

Claude Code, Aider, Cline, OpenCode는 실제로 일어나고 있는 변화의 일부입니다. 코딩 지원은 제안 엔진에서 터미널 기반 협업 도구로 이동하고 있습니다. 가장 큰 혜택을 얻는 팀은 단순히 “에이전트를 켜는” 팀이 아닐 것입니다. 컨텍스트 범위를 좁히고, 안전한 도구를 사용하고, 비용을 관측할 수 있게 하며, 모든 단계에서 검증하도록 루프를 설계하는 팀일 것입니다.