책에 포함된 노트AI를 잘 쓰는 법: 프롬프트를 넘어 컨텍스트·워크플로·에이전트까지

7부 35장. Codex CLI, Claude Code 같은 도구를 이해하는 법

2026-04-24Views 74약 11분생성형 AI 활용

7부 35장. Codex CLI, Claude Code 같은 도구를 이해하는 법

처음 CLI 기반 코딩 AI를 접하면 누구나 비슷한 질문을 한다.

"그래서 뭐가 제일 좋아요?"

당연한 질문이다. 도구 이름은 많고, 비교 글은 넘치고, 다들 자기 도구가 최고라고 말한다. 그런데 이 질문부터 붙잡으면 오히려 길을 잃기 쉽다. 왜냐하면 이런 도구들은 겉보기 이름은 달라도, 속에서 돌아가는 원리가 꽤 비슷하기 때문이다.

마치 자동차를 처음 배울 때 브랜드 이름부터 외우는 것과 비슷하다. 진짜 중요한 것은 엠블럼보다도 이 차가 수동인지 자동인지, 연비가 어떤지, 짐을 많이 실을 수 있는지, 산길에 강한지 같은 사용 감각이다. CLI 코딩 AI도 마찬가지다. Codex CLI, Claude Code, Gemini CLI, Aider, OpenCode 같은 이름은 겉표지에 가깝다. 먼저 이해해야 할 것은 이 도구들이 어떤 구조로 움직이고, 어떤 방식으로 사람과 역할을 나누며, 어디까지 자율적으로 일하는가다.

이 장에서는 대표 도구들의 이름을 줄줄 외우기보다, 그 아래에 있는 공통 원리를 먼저 잡아 보겠다. 이 원리를 이해하면 새 도구가 나와도 당황하지 않는다. 이름이 바뀌어도 보는 눈은 남기 때문이다.

7부 35장. Codex CLI, Claude Code 같은 도구를 이해하는 법

이 도구들은 무엇인가: 모델이 아니라 하네스다

많은 사람이 이런 도구를 처음 볼 때 "Claude를 터미널에서 쓰는 것", "GPT를 CLI로 쓰는 것" 정도로 생각한다. 반은 맞고, 반은 틀리다.

틀린 쪽이 더 중요하다.

이 도구들은 단순히 모델을 껍데기만 바꿔 붙인 것이 아니다. 높은 수준의 목표를 받으면 스스로 작업을 단계로 나누고, 파일을 읽고, 코드를 수정하고, 명령을 실행하고, 실패하면 다시 고치는 에이전트형 작업 루프를 갖고 있다.¹ 즉, 핵심은 "어떤 모델이냐"만이 아니라, 그 모델을 어떻게 작업 환경에 연결했느냐에 있다.

이 연결 장치를 흔히 하네스라고 생각하면 이해가 쉽다. 말에게 마차를 연결하는 장비처럼, 하네스는 모델을 파일 시스템, 셸, 테스트, Git, 외부 도구와 묶어 준다. 같은 말이라도 수레를 끄는 장비가 다르면 일하는 방식이 달라지듯, 같은 급의 모델이라도 하네스가 다르면 체감이 크게 달라진다.

그래서 어떤 도구는 아주 똑똑한데 답답하게 느껴지고, 어떤 도구는 모델 자체는 비슷해 보여도 훨씬 일을 잘 굴리는 것처럼 느껴진다. 모델이 아니라 작업 구조가 다르기 때문이다.

대표 도구들이 대체로 공유하는 다섯 겹 구조

겉모습은 달라도, 요즘 CLI 코딩 도구들은 대개 비슷한 층으로 이루어져 있다.

입력층: 사람이 목표를 자연어로 말하는 곳
컨텍스트층: 저장소 구조, 관련 파일, 설정 파일, 대화 기록을 모으는 곳
에이전트층: 계획하고, 행동하고, 결과를 보고 다시 판단하는 루프
도구층: 파일 읽기, 편집, 셸 명령, 테스트, Git, 검색 같은 실제 손발
안전층: 승인, 샌드박스, 권한 제한, 체크포인트 같은 안전장치

이 다섯 층을 이해하면, 새로운 도구를 보더라도 빠르게 감이 온다.

입력층은 생각보다 단순하다. 사용자는 보통 "무엇을 해라"를 자연어로 지시한다. 하지만 그 다음부터는 급격히 복잡해진다. 도구는 프로젝트에서 관련 파일을 찾고, 필요한 정보를 모으고, 어떤 순서로 움직일지 계획한다. 그 다음에는 실제로 파일을 건드리고 명령을 실행한다. 마지막으로 그 행동이 안전한지, 승인이 필요한지, 되돌릴 수 있는지 관리한다.

이 구조를 모르면 도구를 이름으로만 보게 된다. 반대로 이 구조를 알면, 새로운 제품 소개를 읽을 때도 금방 핵심이 보인다. "아, 이건 컨텍스트 수집이 강한 쪽이구나." "이건 샌드박스가 강하네." "이건 자율성은 높은데 승인 구조가 약하네." 이런 식으로 읽히기 시작한다.

사용감의 차이는 주로 네 군데서 갈린다

도구 이름이 달라도 실제 체감 차이는 주로 네 축에서 벌어진다.

첫째는 모델 결합 방식이다. 어떤 도구는 특정 회사의 모델에 깊게 묶여 있다. 이런 도구는 대개 자사 모델의 장점을 최대한 잘 끌어낸다. 대신 선택의 폭은 좁다. 반대로 BYOK(Bring Your Own Key), 즉 여러 모델 제공자를 연결할 수 있는 도구는 유연성이 크다. 대신 설정이 늘고, 조합에 따라 품질 차이도 커진다. 현재 시장도 대략 이런 흐름으로 나뉜다. 모델 회사가 직접 만든 도구가 있고, 여러 모델을 꽂아 쓸 수 있는 독립형·오픈소스 도구가 따로 있다.²

둘째는 자율성의 정도다. 어떤 도구는 시니어 개발자처럼 늘 먼저 물어본다. "이 파일을 수정해도 될까요?" "이 명령을 실행해도 될까요?" 반대로 어떤 도구는 "일단 맡겨 두세요" 쪽에 가깝다. 작업을 한참 진행한 뒤 결과를 묶어서 보여준다. 둘 다 장단점이 있다. 전자는 느려도 안심이 되고, 후자는 빠르지만 사후 검토 부담이 커진다.

셋째는 실행 환경의 철학이다. 로컬 우선인지, 클라우드 샌드박스 중심인지, 둘을 섞는지에 따라 도구의 느낌이 달라진다. 어떤 도구는 내 작업 디렉터리 안에서 직접 움직이는 감각이 강하고, 어떤 도구는 격리된 환경에서 먼저 시험해 본 뒤 결과를 가져오는 감각이 강하다.

넷째는 통합 범위다. 단순히 파일 수정만 하는지, GitHub 이슈와 PR을 읽는지, MCP로 외부 도구를 붙일 수 있는지, IDE와 세션을 공유하는지에 따라 "그냥 코딩 보조기"인지 "작업 운영체제의 일부"인지가 갈린다.

즉, 좋은 질문은 "누가 최고냐?"가 아니다.

더 좋은 질문은 이런 것이다.

"나는 모델 유연성이 중요한가, 깊은 통합이 중요한가?" "나는 매 단계 승인형이 편한가, 결과 검토형이 편한가?" "내 작업은 로컬 중심인가, 팀 협업과 GitHub 중심인가?"

이 질문이 도구 이름보다 훨씬 중요하다.

왜 어떤 도구는 '대화형' 같고, 어떤 도구는 '위임형' 같을까

CLI 도구를 실제로 써 보면 재미있는 차이가 있다. 어떤 도구는 옆자리에 앉아 같이 상의하는 페어 프로그래머처럼 느껴진다. 반면 어떤 도구는 티켓을 던져 주면 혼자 처리하고 돌아오는 백그라운드 작업자처럼 느껴진다.

이 차이는 우연이 아니다. 설계 철학 차이다.

승인 중심 도구는 보통 사용자를 자주 루프 안에 넣는다. 계획을 보여 주고, 수정 전에 물어보고, 명령 실행 전에 확인을 받는다. 이런 방식은 대규모 리팩터링이나 민감한 코드 변경에서 마음이 편하다. 대신 흐름이 자주 멈춘다.

반대로 자율 실행 중심 도구는 한 번에 더 길게 달린다. 작업을 위임하고 잠시 다른 일을 할 수 있다는 장점이 있다. 대신 결과를 나중에 한꺼번에 검토해야 하므로, 잘못 달렸을 때 되짚는 비용이 커질 수 있다. 실제 비교 글들도 Claude Code를 상대적으로 협업형, Codex CLI를 더 자율 실행형으로 묘사하곤 한다.³

이 차이를 이해하면 도구를 더 똑똑하게 쓸 수 있다. 예를 들어 설계가 복잡하고 맥락 의존이 큰 작업은 대화형이 편할 수 있다. 반대로 테스트 추가, 반복 리팩터링, 문서 갱신처럼 상대적으로 경계가 분명한 작업은 위임형이 더 시원할 수 있다.

사람도 그렇다. 모든 일을 실시간으로 같이 할 필요는 없다. 어떤 일은 회의가 필요하고, 어떤 일은 티켓만 주면 된다. CLI 코딩 AI도 똑같다.

컨텍스트 파일을 이해하면 도구가 왜 갑자기 똑똑해지는지 보인다

CLI 코딩 도구를 쓰다 보면 종종 이런 파일 이름을 보게 된다. CLAUDE.md, AGENTS.md, 혹은 그에 준하는 프로젝트 지침 파일들이다.

이 파일들은 단순한 메모가 아니다. 에이전트에게 "이 저장소에서는 이렇게 행동하라"라고 알려 주는 현장 매뉴얼에 가깝다.

예를 들어 이런 정보가 들어갈 수 있다.

이 프로젝트의 폴더 구조
어떤 명령으로 테스트를 돌리는지
어떤 코딩 스타일을 따르는지
절대 건드리면 안 되는 디렉터리
리뷰할 때 중시하는 기준
브랜치, 커밋, PR 규칙

OpenCode처럼 일부 도구는 프로젝트를 분석한 뒤 AGENTS.md를 만들어 주기도 한다.⁴ 이것이 중요한 이유는, 에이전트가 매번 처음 보는 외주 개발자처럼 행동하지 않게 만들기 때문이다. 규칙 파일이 없으면 AI는 일반론에 기대기 쉽다. 규칙 파일이 있으면 "이 저장소다운 방식"으로 움직일 가능성이 높아진다.

이 점은 생각보다 크다. 좋은 사용자는 단지 프롬프트를 잘 쓰는 사람이 아니라, 도구가 매 세션마다 덜 헤매도록 작업 환경을 설계하는 사람이다.

도구를 평가할 때 '답변 품질'만 보면 절반만 보는 것이다

웹 채팅형 AI에 익숙하면, 도구를 평가할 때도 자꾸 답변 문장만 보게 된다. 설명이 자연스러운가, 코드가 그럴듯한가, 말투가 똑똑한가를 본다.

하지만 CLI 코딩 도구에서는 이것만 보면 절반도 못 본다.

진짜 중요한 것은 이런 것들이다.

관련 파일을 얼마나 잘 찾는가
계획을 얼마나 분명하게 세우는가
수정 범위를 얼마나 적절히 통제하는가
테스트와 검증을 자연스럽게 연결하는가
실패했을 때 얼마나 잘 복구하는가
diff와 로그가 얼마나 검토하기 쉬운가

쉽게 말해, 말솜씨보다 작업 루프의 완성도가 더 중요하다.

예를 들어 같은 수준의 코드를 내놓더라도, 한 도구는 관련 파일을 정확히 모으고, 변경 이유를 요약하고, 테스트까지 돌리고, 되돌리기까지 쉬울 수 있다. 다른 도구는 코드만 던져 주고 끝날 수 있다. 후자가 언뜻 화려해 보여도, 실제 실무에서는 전자가 훨씬 강하다.

그래서 숙련된 사용자는 코드 한 덩어리보다도 계획, 명령, diff, 테스트 결과를 함께 본다. 그게 진짜 품질이기 때문이다.

샌드박스와 승인 모드는 불편함이 아니라 성격이다

처음 CLI 도구를 쓸 때 많은 사람이 이렇게 느낀다.

"왜 이렇게 자꾸 물어보지?" "왜 이 명령은 막지?" "왜 내 파일을 바로 못 바꾸게 하지?"

하지만 이런 제약은 미완성이라서 붙은 것이 아니라, 도구의 성격을 결정하는 핵심이다.

예를 들어 어떤 도구는 권한 요청을 자주 하면서 사람을 계속 루프 안에 두는 방식을 택한다. 다른 도구는 운영체제 수준 샌드박스나 격리 환경을 중심에 놓고, 그 안에서는 더 자율적으로 움직이게 한다. 최근 도구 비교 자료를 보면 Claude Code 계열은 상대적으로 permission-first, Codex CLI 계열은 sandbox-first에 가까운 설계 철학으로 자주 설명된다.³

이 차이는 곧 사용 시나리오 차이로 이어진다.

민감한 저장소를 직접 다루고 있고, 사람이 매 단계 감시해야 안심되는 환경이라면 승인형이 맞을 수 있다. 반대로 CI나 자동화 파이프라인처럼 격리된 작업장에서 반복 작업을 빠르게 굴리고 싶다면 샌드박스형이 잘 맞을 수 있다.

즉, "뭐가 더 좋으냐"보다 "어디에 더 잘 맞느냐"의 문제다.

GitHub, MCP, IDE 연결은 왜 점점 더 중요해지는가

예전의 코딩 보조 AI는 파일 몇 개 고쳐 주면 역할이 끝났다. 그런데 지금의 CLI 에이전트는 점점 더 넓은 작업장으로 나가고 있다.

GitHub 중심 도구는 저장소, 이슈, PR, 리뷰 흐름과 바로 연결된다. 예를 들어 Copilot CLI는 GitHub 맥락을 직접 읽고, 커스텀 에이전트를 호출하고, 백그라운드 위임까지 할 수 있다.⁵ 이런 연결이 생기면 AI는 단순한 "코드 생성기"가 아니라 "개발 흐름 참가자"가 된다.

MCP(Model Context Protocol) 연결도 마찬가지다. 파일, 검색, 문서, 데이터베이스, 브라우저, 사내 도구가 연결되면 AI는 점점 더 넓은 문맥을 다룰 수 있게 된다. 단, 이 확장은 언제나 양날의 검이다. 손발이 늘어날수록 가능성은 커지지만, 잘못 움직일 위험도 커진다.

그래서 통합이 많은 도구일수록 오히려 더 중요한 것은 "무엇을 할 수 있나"가 아니라 "무엇을 하지 못하게 막을 수 있나"다.

초보자가 자주 하는 오해: 한 도구가 모든 역할을 대신할 것이라는 기대

이런 도구를 처음 쓰는 사람은 종종 하나의 완벽한 도구를 찾으려 한다. 설계도 잘하고, 구현도 잘하고, 디버깅도 잘하고, 리뷰도 잘하고, Git 정리도 잘하고, 배포까지 안전하게 하는 만능 비서를 기대한다.

현실은 조금 다르다.

실제로는 도구마다 더 편한 포지션이 있다. 어떤 도구는 깊은 코드베이스 이해와 리팩터링에 강하고, 어떤 도구는 가볍고 빠른 반복 작업에 강하고, 어떤 도구는 다중 모델과 로컬 모델 연결에 강하다.² 그래서 숙련된 사용자는 "한 도구를 믿는다"기보다 "작업 종류에 맞춰 고른다"에 가깝다.

이 태도는 중요하다. 도구를 신앙처럼 대하면 실망도 크다. 반대로 기능과 철학을 분해해서 보면, 각 도구는 꽤 선명한 자리를 가진다.

즉, 이름을 고집하지 말고 역할을 보라.

처음 써 볼 때 가장 좋은 접근: 작은 일로 성격부터 파악하기

새 CLI 코딩 도구를 잡았을 때 가장 먼저 해야 할 일은 큰 기능을 맡기는 것이 아니다. 먼저 그 도구의 성격을 파악해야 한다.

가장 좋은 첫 실험은 대개 이런 순서다.

저장소 구조를 설명하게 해 본다.
관련 파일을 어떻게 찾는지 본다.
계획만 먼저 세우게 해 본다.
작은 수정 하나만 맡긴다.
테스트나 린트를 돌리게 해 본다.
마지막으로 diff와 요약을 검토한다.

이 흐름이 좋은 이유는, 도구의 본성이 드러나기 때문이다. 계획이 좋은지, 검색이 섬세한지, 과하게 수정하는지, 검증을 잘 붙이는지, 요약이 명료한지 한 번에 드러난다.

반대로 처음부터 "이 앱 전체를 리팩터링해 줘"라고 던지면, 잘하든 못하든 무엇이 강점이고 약점인지 배우기 어렵다. 도구를 제대로 이해하려면 먼저 작은 작업에서 리듬을 느껴야 한다.

좋은 사용자는 프롬프트보다 경계를 잘 준다

CLI 코딩 도구에 지시할 때도 물론 프롬프트는 중요하다. 하지만 여기서는 화려한 문장보다 경계 설정이 훨씬 중요하다.

예를 들어 이런 지시는 좋다.

"먼저 계획만 보여 줘." "src/auth와 tests/auth만 건드려." "성공 기준은 관련 테스트 통과야." "DB 스키마와 배포 설정은 수정하지 마." "변경 후 diff를 요약해 줘."

이런 문장은 문학적으로 멋지지 않다. 하지만 실무에서는 이런 지시가 훨씬 강하다. CLI 에이전트는 실제로 움직일 수 있는 손발이 많기 때문에, 멋진 설명보다도 범위, 승인, 성공 기준이 더 중요하다.

이 점에서 CLI 도구는 운전과 비슷하다. 엑셀을 어떻게 밟을지만 아는 사람보다, 브레이크와 차선의 감각을 아는 사람이 더 안전하고 빠르다.

도구를 고를 때 결국 봐야 하는 질문

마지막으로, 이름보다 먼저 스스로에게 물어야 할 질문을 정리해 보자.

나는 특정 모델 생태계에 이미 들어가 있는가
모델을 바꿔 끼우는 자유가 중요한가
매 단계 승인형이 편한가, 결과 검토형이 편한가
로컬 실행과 프라이버시가 중요한가
GitHub, 이슈, PR 흐름 연결이 중요한가
무료 시작이나 비용 통제가 중요한가
IDE와 터미널을 함께 쓸 것인가, 터미널 하나로 밀 것인가

이 질문에 대한 답이 정리되면, 도구 선택은 훨씬 쉬워진다.

이미 ChatGPT 구독과 OpenAI 흐름이 익숙한 사람은 Codex 계열이 자연스럽게 느껴질 수 있다. Anthropic 생태계에 있고 깊은 코드 이해와 승인형 흐름이 편하면 Claude Code가 잘 맞을 수 있다. 무료로 가볍게 시작하거나 큰 컨텍스트와 검색 결합이 필요하면 Gemini CLI 쪽이 매력적으로 보일 수 있다. 모델을 자주 바꾸고 싶거나 로컬 모델까지 포함해 유연하게 쓰고 싶다면 Aider, OpenCode 같은 쪽이 더 잘 맞을 수 있다.²

중요한 것은, 이 결론이 브랜드 충성심에서 나오면 안 된다는 점이다. 작업 방식이 먼저이고, 도구 이름은 나중이어야 한다.