Codex CLI를 챗봇처럼 쓰지 않을 때 달라지는 점, AGENTS.md부터 시작하는 이유 | DAKER 커뮤니티

Codex CLI AGENTS.md

Codex CLI를 처음 열면 많은 사람이 채팅창처럼 한 줄 지시를 넣고 답을 기다립니다. 하지만 TechWhistle의 Codex CLI: 5 Tips Power Users Actually Use (2026)가 보여 주는 방식은 조금 다릅니다. Codex CLI는 단순한 터미널 자동완성이 아니라, 파일 시스템을 읽고 명령을 실행하며 코드를 고치고 하위 에이전트까지 띄울 수 있는 로컬 코딩 에이전트에 가깝습니다.

그래서 중요한 것은 프롬프트 한 줄을 더 잘 쓰는 일이 아니라, 세션이 바뀌어도 맥락이 남도록 작업 환경을 정리하는 일입니다. 이 글은 영상에서 소개한 다섯 가지 팁을 바탕으로, 왜 AGENTS.md가 출발점이 되는지부터 차례로 정리합니다.

세션마다 프로젝트를 다시 설명하지 않도록, AGENTS.md를 먼저 남기는 것이 핵심입니다.

Codex CLI를 챗봇처럼만 쓰면 놓치기 쉬운 것

영상에 따르면 Codex CLI는 터미널 안의 ChatGPT로 이해하면 기능을 절반만 쓰게 됩니다. Codex CLI는 코드베이스를 탐색하고, 필요한 경우 명령을 실행하며, 실제 파일 변경까지 이어지는 로컬 에이전트로 동작합니다.

영상에서 소개한 동작 모드는 세 가지입니다. 기본인 Auto는 파일 쓰기와 셸 실행 전에 확인을 받습니다. Full auto는 승인 프롬프트 없이 자율 실행하며, 신뢰할 수 있는 저장소에서만 쓰는 편이 안전하다고 설명합니다. Suggest는 읽기 전용으로 변경안만 제안합니다.

일상 작업에는 Auto가 무난하고, Full auto는 이미 Codex의 판단을 검증한 저장소에 더 어울립니다. Suggest는 위험을 낮춘 두 번째 의견이 필요할 때 적합합니다. 모델 선택도 함께 언급됩니다. 영상은 복잡한 코딩과 계획에는 GPT-5.5를, 단순하고 반복적인 작업에는 GPT-5.4 Mini를 권하며, 세션 도중 /model로 전환할 수 있다고 설명합니다.

AGENTS.md가 먼저인 이유

대부분의 세션에서 Codex는 처음부터 시작합니다. 프로젝트의 아키텍처 결정, 네이밍 방식, 피하고 싶은 패턴을 모른 채 합리적인 추측을 하다 보니, 틀리지는 않지만 원하는 방향과는 다른 결과가 나올 수 있습니다. 영상은 OpenAI 공식 문서를 인용해 Codex가 세션에서 일하기 전에 AGENTS.md를 읽는다고 설명합니다.

즉, AGENTS.md는 매번 채팅으로 반복하던 설명을 파일로 옮겨 두는 온보딩 문서입니다. 한 번 정리해 두면 이후 세션에도 같은 기준이 남습니다.

완벽한 문서보다, 세션마다 반복해 말하던 한 줄을 파일로 옮기는 편이 더 중요합니다.

영상이 제안한 네 가지 섹션

영상 기준으로 효과적인 AGENTS.md는 네 섹션으로 구성됩니다. 첫째는 기술 스택입니다. 사용하는 프레임워크와 라이브러리를 정확히 적습니다. 둘째는 아키텍처 결정입니다. 예를 들어 리포지토리 패턴을 쓰고 DB 직접 호출로 우회하지 않는다는 식의 원칙이 여기에 들어갑니다. 셋째는 컨벤션입니다. 네이밍, 파일 구조, import 순서처럼 일관성이 필요한 규칙을 적습니다. 넷째는 하지 말 것입니다. 예를 들어 console.log 추가 금지, 설정 파일은 묻기 전에 수정하지 않기, 새 기능에는 테스트 작성 같은 항목이 여기에 해당합니다.

영상은 전역 AGENTS.md와 프로젝트별 파일을 함께 두는 방식도 소개합니다. 전역 파일에는 스택 선호, 코드 스타일, 일반 원칙을 두고, 저장소별 파일에는 해당 프로젝트의 규칙을 적어 두면 여러 레포에서 행동이 더 일정해진다는 설명입니다.

애매한 작업일수록 /plan이 먼저입니다

영상에서 연사는 복잡한 작업을 바로 실행했다가 절반은 맞고 절반은 다른 방향으로 흘러가는 경우를 자주 겪었다고 말합니다. 이를 줄이는 방법으로 제시한 것이 /plan입니다.

뻔하지 않은 작업에서는 먼저 /plan을 실행하면 됩니다. 그러면 Codex가 어떤 파일을 바꿀지, 어떤 접근 방식을 택할지, 왜 그렇게 판단했는지를 스레드에 적습니다. 사용자는 그 계획을 검토하고 수정한 뒤 실행할 수 있습니다. 영상은 계획 단계에서 방향을 먼저 고칠 수 있다는 점을 강조합니다.

예를 들어 47번 줄 오타 수정처럼 명확한 작업은 계획 없이 바로 진행해도 괜찮습니다. 반면 OAuth를 지원하도록 인증 모듈을 리팩터링하는 일처럼 범위와 영향이 넓은 작업은 plan first가 더 적합합니다. 영상은 Codex 모범 사례 가이드를 인용해, 애매한 작업에서 계획을 기본값으로 두는 사람이 더 많이 배포한다고 설명합니다. 다만 연사가 언급한 수정 사이클 감소 효과는 영상 발언이며, 이 글에서는 별도 측정 자료를 확인하지 않았습니다.

명확한 버그는 바로 고쳐도 되지만, 애매한 작업은 실행보다 계획이 먼저입니다.

숨은 단축키가 세션의 흐름을 바꿉니다

영상은 공식 Codex CLI 기능 페이지에 있는 단축키 세 가지를 소개합니다. 모두 대화를 기다리는 방식보다, 실행 중인 에이전트를 실시간으로 안내하는 흐름에 가깝게 만들어 줍니다.

@ 연산자는 메시지 어디서나 프로젝트 파일 퍼지 검색을 열고, Tab이나 Enter로 경로를 프롬프트에 넣을 수 있게 합니다. 긴 경로를 직접 입력하지 않아도 됩니다. 작업이 실행되는 동안 Enter를 누르면 중간 지시를 추가할 수 있어서, 끝날 때까지 기다렸다가 처음부터 다시 설명할 필요가 줄어듭니다. 실행 중 Tab을 누르면 다음 지시를 대기열에 넣을 수 있고, 현재 작업이 끝난 뒤 이어서 처리됩니다.

이 세 가지를 함께 쓰면 Codex 세션은 턴제 채팅보다, 움직이고 있는 작업을 옆에서 조정하는 방식에 가까워집니다.

Git worktree와 /subagent는 병렬 작업에 유용합니다

영상 오프닝에서는 세 개의 Git worktree에서 Codex가 각각 테스트, 버그, 문서 작업을 돌리는 장면이 나옵니다. worktree는 같은 저장소에서 여러 브랜치를 서로 다른 디렉터리에 동시에 체크아웃하는 방식입니다. 디렉터리마다 Codex 세션을 따로 두면 서로 막지 않고 격리된 상태로 병렬 작업을 진행할 수 있습니다.

영상은 ovox.ai의 실전 Codex CLI 가이드를 인용해 3~4개 worktree 정도를 적정 범위로 소개합니다. 예를 들어 하나는 현재 기능, 하나는 테스트 커버리지, 하나는 문서 작업처럼 나눌 수 있습니다. 세션 안에서는 /subagent로 하위 에이전트를 띄워 패턴 조사나 코드베이스 탐색을 병렬로 맡길 수도 있습니다. 영상은 공식 서브에이전트 문서를 인용해, Codex가 생성과 대기, 결과 취합을 오케스트레이션한다고 설명합니다.

다만 병렬 작업이 항상 이득인 것은 아닙니다. 브랜치가 크게 갈라지면 머지가 어려워질 수 있기 때문입니다. 영상도 상태가 겹치지 않는 독립 작업에만 병렬을 쓰는 편이 좋다고 분명히 말합니다.

병렬 작업은 빠르지만, 공유 상태가 많은 일에는 오히려 머지 비용이 커질 수 있습니다.

루틴은 Mini, 설계는 5.5로 나누는 이유

영상은 모든 작업에 GPT-5.5가 필요한 것은 아니라고 설명합니다. 파일 요약, 문서 생성, 테스트 스캐폴딩 같은 루틴 작업은 GPT-5.4 Mini가 더 빠르고 저렴할 수 있습니다. 반대로 아키텍처 결정이나 복잡한 코딩, 계획 수립은 GPT-5.5가 더 어울린다는 것이 영상의 권장 패턴입니다.

이 구분은 세션을 끊지 않고 /model로 전환할 수 있다는 점에서 실용적입니다. 문서화나 요약을 처리할 때는 Mini를 쓰고, 설계 판단이 필요한 순간에만 5.5로 돌아오는 식입니다.

함께 소개된 또 하나의 기능은 skills입니다. /skills 또는 $로 접근하며, 필요할 때 적용하는 재사용 가능한 작업 파일로 설명됩니다. 영상은 Compozio HQ의 awesome Codex skills 저장소를 언급하며, 커밋 메시지 작성, PR 리뷰, 테스트 커버리지 분석 같은 스킬을 예로 듭니다. 직접 skill.md를 작성하면 Codex가 자동으로 불러와 적용한다고도 소개합니다.

해커톤이나 사이드 프로젝트에서 바로 적용하는 흐름

영상의 다섯 가지 팁을 하루 작업 흐름으로 옮기면 비교적 단순합니다. 먼저 AGENTS.md를 준비해 두고, 필요하면 worktree를 나눕니다. 복잡한 기능은 /plan으로 시작하고, 분명한 버그는 바로 실행합니다. 파일 지정은 @로 처리하고, 실행 중 수정이 필요하면 Enter나 Tab으로 흐름을 이어 갑니다. 문서와 요약은 Mini, 구조 결정은 GPT-5.5로 나누면 됩니다.

이 방식이 어려운 문제 자체를 없애 주는 것은 아닙니다. 영상도 아키텍처 판단과 코드 리뷰는 결국 사람의 몫이라고 말합니다. 다만 반복 설명과 낮은 가치의 수작업을 줄여, 사람이 더 중요한 판단에 집중하게 돕는다는 점이 핵심입니다.

이 글이 다루는 범위

이 글은 TechWhistle 영상의 다섯 가지 팁을 바탕으로 정리한 요약입니다. 초점은 Codex CLI를 로컬 에이전트처럼 다루는 운영 습관에 있습니다. DAKER·DACON 플랫폼 점수, 특정 대회 순위, 모델 벤치마크 수치처럼 영상이 직접 다루지 않은 내용은 넣지 않았습니다.

또한 모델 이름인 GPT-5.5, GPT-5.4 Mini와 모드 이름인 Auto, Full auto, Suggest는 영상 시점의 설명입니다. 제품 UI나 권장 모델은 바뀔 수 있으므로 실제 적용 전에는 터미널의 /model 목록과 최신 공식 문서를 함께 확인하는 편이 안전합니다. Claude Code의 CLAUDE.md와 Codex의 AGENTS.md는 목적이 비슷해 보여도 도구와 파일명, 명령이 다르므로 그대로 섞어 쓰지 않는 것이 좋습니다.

참고 자료

본문은 위 영상 자막과 설명을 기준으로 정리했습니다. 영상에서 언급한 공식 문서와 외부 가이드의 구체 URL은 자막에 모두 나오지 않아, 여기서는 원문 YouTube 링크를 1차 출처로 두었습니다.

여러분은 Codex CLI를 쓸 때 먼저 남겨 두고 싶은 프로젝트 규칙이 무엇인지 궁금합니다.