코덱스 CLI 활용법 5가지: 파워 유저가 실제로 쓰는 agents.md·플랜·워크트리 전략

핵심 메시지

• 코덱스 CLI는 똑똑한 터미널 자동완성이 아니라, 파일 시스템에 접근하고 명령을 실행하며 코드를 수정하는 로컬 코딩 에이전트다.
• 코덱스에는 기본값인 오토, 완전 자동, 읽기 전용 제안 모드가 있고, 영상에 따르면 복잡한 작업에는 GPT-5.5, 일상 작업에는 더 빠르고 저렴한 GPT-5.4 미니가 권장된다.
• agents.md 파일에 기술 스택·아키텍처 결정·컨벤션·금지사항을 적어 두면 코덱스가 매 세션 작업 전에 이를 읽어 코드베이스 전문가처럼 행동한다.
• 애매한 작업에는 /plan으로 먼저 계획을 세우고 스레드에서 직접 수정한 뒤 실행하며, @ 연산자·실행 중 엔터·탭 큐 같은 단축키로 작업을 실시간 지휘한다.
• 깃 워크트리로 여러 브랜치에서 코덱스 세션을 병렬로 돌리고, /subagent로 자식 에이전트를 띄우며, /model로 모델을 바꾸고 스킬 시스템으로 반복 작업을 재사용한다.

쉽게 이해하기

영상은 세 개의 터미널 창에서 세 개의 깃 워크트리로 코덱스를 동시에 돌려, 하나는 테스트를 작성하고 하나는 버그를 고치고 하나는 문서를 갱신하는 장면으로 시작한다. 많은 개발자가 코덱스를 '터미널 속 챗봇'처럼 쓰며 잠재력의 20% 정도만 활용한다고 지적하며, 나머지 80%를 끌어내는 다섯 가지 기법을 소개한다.

먼저 올바른 멘탈 모델이 필요하다. 코덱스 CLI는 코드베이스를 읽고 명령을 실행하며 파일을 자율적으로 수정하는 로컬 에이전트다. 동작 모드는 세 가지로, 파일 작성이나 셸 명령 전에 확인을 받는 기본값 오토, 승인 없이 완전히 자율로 도는 풀 오토, 아무것도 건드리지 않고 변경만 제안하는 읽기 전용 제안 모드가 있다. 영상은 OpenAI 문서를 인용해 복잡한 코딩·계획 작업에는 GPT-5.5가, 빠르고 저렴한 일상 작업에는 GPT-5.4 미니가 권장되며 /model로 세션 중에도 전환할 수 있다고 설명한다.

첫 번째와 두 번째 기법은 agents.md와 /plan이다. 코덱스는 매 세션 처음부터 시작하므로 아키텍처 결정이나 명명 규칙을 기억하지 못한다. agents.md에 기술 스택, 아키텍처 결정, 컨벤션, 금지사항(don'ts) 네 가지를 적어 두면, 코덱스가 작업 전에 이를 읽어 해당 코드베이스의 전문가처럼 행동한다. 전역 파일을 먼저 쓰고 저장소별 파일을 더하는 계층 구성도 권장된다. 또한 분명하지 않은 작업에는 /plan으로 코덱스가 무엇을 바꾸고 어떤 파일을 건드릴지 먼저 보여주게 한 뒤, 스레드에서 계획을 직접 고치고 실행하면 사용자가 검토자가 아니라 설계자가 된다.

세 번째 기법은 공식 기능 페이지에 있지만 잘 알려지지 않은 세 가지 단축키다. @ 연산자는 메시지 안에서 프로젝트 전체를 대상으로 퍼지 파일 검색을 열어 경로를 바로 넣어 준다. 코덱스가 작업하는 도중 엔터를 누르면 새 지시를 중간에 끼워 넣어 방향을 실시간으로 바로잡을 수 있다. 탭을 누르면 다음 지시를 큐에 넣어, 코덱스가 현재 작업을 마친 뒤 큐의 지시를 이어받아 계속 진행한다. 이 세 가지는 코덱스를 차례를 주고받는 대화에서 끊김 없는 작업 세션으로 바꿔 준다.

네 번째와 다섯 번째는 병렬화와 효율화다. 깃 워크트리를 쓰면 같은 저장소에서 여러 브랜치를 별도 디렉터리로 동시에 체크아웃해 각각 독립된 코덱스 세션을 돌릴 수 있는데, 영상은 세에서 네 개가 적당하다고 본다. 세션 안에서는 /subagent로 자식 에이전트를 띄워 병렬 탐색을 시키고, 코덱스가 오케스트레이션을 자동으로 처리한다. 다만 브랜치가 크게 갈라지면 병합이 복잡해지므로 서로 독립적인 작업에 적합하다. 마지막으로 /model로 지루한 작업은 미니, 아키텍처 결정은 GPT-5.5로 나눠 쓰고, /skills나 달러 기호로 접근하는 스킬 시스템에 재사용 가능한 워크플로를 skill.md로 저장해 둘 수 있다.

주요 인사이트

• 코덱스 CLI를 단순한 자동완성이 아니라 파일 시스템과 명령 실행 권한을 가진 로컬 에이전트로 이해하는 것이 모든 활용의 출발점이다.
• agents.md로 한 번 적어 두면 계속 적용되는 온보딩 문서를 두는 것이, 매 세션 같은 설명을 반복하는 비용을 없애는 가장 큰 지렛대다.
• 애매한 작업에 /plan으로 먼저 계획을 검토·수정하면 수정 반복이 절반으로 줄고 사용자는 설계자의 위치에 선다.
• 진짜 제약은 시간이 아니라 주의력이며, 이 다섯 기법은 저부가가치 작업을 덜어내 개발자가 아키텍처와 코드 리뷰 같은 판단에 집중하게 해 준다.

자주 묻는 질문

관련 AI 소식