[AI 터미널 도구 10~12일차] Codex CLI로 프로젝트 운영하기

도서명 : AI 자율학습 클로드 코드·코덱스 CLI·제미나이 CLI 완전 활용법

이 포스팅은 길벗 출판사의 코딩 자율학습단 20기 활동의 일환으로, 개인 공부 정리용 포스팅이다.

---

7장 - Codex CLI로 프로젝트 운영하기

7.1 - AGENTS.md 파일 관리하기

이 문서는 Codex가 ‘이 프로젝트에서는 어떤 방식으로 일해야 하는가’를 이해하는 기준이며, 코드 생성, 수정, 테스트, 실행 과정에서 Codex의 행동을 일정하게 유지하도록 안내한다.

위치와 적용 범위

• 1 - 프로젝트 루트 AGENTS.md (프로젝트 기준 문서)
  • 위치 : ./my-project/AGENTS.md
  • 해당 프로젝트에서 작업할 때 따라야 할 기본 규칙과 전반적인 기준을 정리하는 문서
  • 사용중인 기술 스택, 디렉터리 구조, 테스트 기준, 실행 환경 같은 핵심 정보가 포함됨.
• 2 -. 서브폴더 AGENTS.md (영역별 규칙 문서 - 선택)
  • 위치 : ./frontend/AGENTS.md, ./backend/AGENTS.md, ./services/billing/AGENTS.md 등
  • 하나의 저장소 안에서 여러 영역이나 서비스가 공존하는 경우, 서브폴더 단위로 AGENTS.md를 추가해 해당 영역에만 적용할 규칙을 정리할 수 있음.

AGENTS.md에 포함해야 할 주요 항목

구분	내용
프로젝트 개요	기술 스택, 주요 기능 실행 환경
개발 환경	설치 및 실행 명령(npm install, docker compose up 등)
코딩 규칙	ESLint/Prettier 규칙, 함수형 패턴, 변수명 규칙 등
테스트 절차	테스트 실행 방법, 기본 테스트 범위
리뷰 및 배포 지침	커밋 메시지, PR 제목 규칙, 배포 전 점검 항목
보안 및 예외 처리	API 키, 개인정보 처리, 대용량 데이터 처리 주의 사항

AGENTS.md 초안 생성하기

init 명령을 사용해 AGENTS.md의 초안을 생성할 수 있다.

• 1 - 기존 프로젝트에서 초안 생성
  • 이미 파일과 디렉터리가 있는 프로젝트라면 프로젝트 루트에서 대화형 세션을 시작한 뒤 /init 명령을 통해 초안을 생성
• 2 - 새 프로젝트에서 개요를 제공해 생성하기
  • 새 프로젝트라면 프로젝트 개요를 간단히 알려준 뒤 /init 명령을 사용할 수 있다.
  • /init React 기반 Todo 웹앱을 위한 AGENTS.md 파일을 작성해줘.
• 3 - 자동 생성된 문서 다듬기 : 자동 생성된 문서는 어디까지나 초안이므로 다음 내용을 검토해야함
  • 프로젝트와 맞지 않는 항목 제거
  • 길거나 모호한 설명 정리
  • 잘못된 명령어나 오타 수정
  • 팀 또는 영역 별 특성 반영

AGENTS.md 관리 원칙

• 1 - AGENTS.md는 간결하게 유지한다.
  • 프로젝트 전반에 공통으로 적용되는 핵심 지침만 포함
  • 한두 문단과 몇 개의 명확한 규칙 수준으로 유지
  • 배경 설명이나 세부 기준은 별도 문서로 분리
• 2 - AGENTS.md와 상세 문서를 분리해 관리한다.
  • 핵심 규칙만 간단히 요약하고, 세부 지침은 별도 문서로 관리하는 방식이 효과적이다.
  • AGENTS.md는 다음 내용만 담아도 충분하다.
    • 프로젝트 개요(3~5줄) : 프로젝트가 무엇을 하는지 요약
    • 기술 스택과 실행 환경 : Codex가 참고해야 할 최소 정보
    • 핵심 구조 요약 : 주요 디렉터리 역할을 한 줄씩 정리
    • 절대 준수해야 할 규칙(3개 내외) : 금지 항목 또는 필수 규칙
    • 기본 테스트/빌드 명령 : Codex가 자동 실행할 기본값

7.2 - 세션 관리와 작업 이어 쓰기 기능

Codex는 대화와 파일 변경 정보를 자동으로 저장하므로 세션 구조만 이해하면 어제 하던 작업을 오늘 그대로 이어가기가 매우 쉬워진다.

세션 안에서 작업 주제 전환

서로 다른 주제를 오가야 하는 상황에서 새로운 요청 흐름을 시작함으로써 대화의 주제를 자연스럽게 전환할 수 있다. 이전 대화 내용은 세션 기록으로 남아 있지만, 이후 대화는 새로운 맥락을 중심으로 이어진다. 이를 통해 같은 프로젝트 안에서 여러 작업을 단계적으로 나누어 진행할 수 있다.
이 방식은 기존 기록을 삭제하지 않으면서도, 현재 다루고 싶은 주제에 집중할 수 있도록 도와준다.

# 예시
> /new

• 이전 작업 흐름 : 회원가입 API 설계에 대한 대화
• 새로운 작업 흐름 : 로그인 API 구현에 대한 대화

세션 이어서 작업하는 세 가지 방식

• 1 - 최근 세션 이어가기
  • codex resume --last
  • codex --continue
• 2 - 세션 목록에서 직접 골라 불러오기
  • codex resume
• 3 - 세션 ID로 정확하게 불러오기
  • codex resume [세션 ID]

대화 내용에 따른 컨텍스트 최적화

• 1 - 대화 내용을 요약해 컨텍스트 정리
  • /compact
• 2 - 새로운 작업 흐름으로 시작하기
  • 특정 기능 개발처럼 주제가 완전히 바뀐다면 컨텍스트를 넘기지 않고 /new로 시작하는 편이 더 효율적

7.3 - 컨텍스트 관리와 토큰 최적화

컨텍스트

컨텍스트를 정리하는 두 가지 도구

구분	작동 방식	사용 시점
/compact	최근 대화는 유지하고 과거 내용을 자동 요약	기능 단위 작업 종료 후, 컨텍스트 부담이 커졌을때
/new	이전 대화 기록은 세션에 남아 있고, 이후 요청은 새로운 주제를 중심으로 이어감	주제가 명확히 전환되거나 작업 성격이 완전히 달라질 때

토큰

토큰을 줄이는 다섯 가지 습관

• 1 - Agents.md를 간결하게 유지
• 2 - 파일과 이미지는 필요한 만큼만 첨부
• 3 - 요청을 묶어서 전달
• 4 - 기능 단위로 세션 끊기
• 5 - 사용하지 않는 MCP 서버 끄기

컨텍스트를 지키면서 공유 정보를 늘리는 방법

• 1 - AGENTS.md + resume
  • 규칙, 원칙, 아키텍처 : AGENTS.md에 정리
  • 현재 작업 현황 : 세션 종료 직전에 한두 줄로 간단히 정리
  • 세션 종료 전 : /compact로 대화 요약
  • 다음 작업 시작 시 : codex --continue 또는 codex resume --last 사용
• 2 - TODO 체크리스트로 진행 상황 기록 : Codex는 체크리스트 형식을 매우 잘 인식
  • [] API 인증 로직 정리
  • [x] 로그인 페이지 리팩터링 완료
• 3 - 이미지 + 짧은 설명 함께 제공

8장 - Codex CLI 고급 기능

8.1 - MCP 서버 연결하기

서버 연결 설정

Codex의 주요 설정(모델, 승인 정책, MCP 서버 등록)은 Config.toml파일에서 관리한다.

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github@latest"]
env = { GITHUB_PERSONAL_TOKEN = "ghp_xxx" }

• [mcp_servers.서버명] : MCP 서버를 Codex에 등록하는 불록, 서버명은 자유롭게 지정 가능
• command : Codex가 MCP서버를 실행할 때 호출하는 명령어
• args : command에 전달한 인자 몰록, 실행할 MCP 패키지를 지정
• env : MCP 서버가 외부 서비스(API)에 접근할 때 사용할 인증 정보 설정

8.2 - config.toml 심화 설정

config.toml의 전체 구조 이해

Codex에서 관리 가능한 주요 항목은 다음과 같다.

• AI 모델 선택(model)
• 사고 깊이(model_responing_effort)
• 승인 정책(approval_policy)
• 샌드박스 범위(sandbox_mode)
• MCP 서버 구성(mcp_servers.*)
• 환경변수 접근 제어(shell_environment_policy)

~/.codex/config.toml 기본 구조 예시

# 기본 모델
model = "gpt-5.2-codex"
# 사고 깊이(권장: medium)
model_reasoning_effort = "medium"
# 주요 작업에만 승인 요청
approval_policy = "on-request"
# 현재 프로젝트 폴더만 수정 가능
sandbox_mode = "workspace-write"
# Codex가 접근 가능한 환경 변수 제어
[shell_environment_policy]
include_only = ["PATH", "HOME", "USER", "LANG"]
# 문서 검색 MCP 예시(Context7)
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]