Codex CLI 사용해보기: 셋업부터 첫 실행까지

최근에 Codex CLI를 사용해보면서, 로컬 프로젝트에서 빠르게 설정하고 활용하는 흐름이 꽤 깔끔하다는 걸 느꼈습니다. 이 글에서는 설치부터 프로젝트별 설정, 그리고 첫 실행까지의 과정을 짧게 정리해봅니다.

목표: "프로젝트별 규칙을 가진 Codex CLI"를 빠르게 띄우고, 원하는 작업을 안정적으로 시키는 흐름 만들기

1. Codex CLI 준비하기

Codex CLI는 터미널에서 동작하는 코딩 에이전트입니다. 보통 아래와 같은 흐름으로 시작합니다.

실제 설치 명령은 사용 환경에 따라 다를 수 있으니, 공식 문서에서 최신 설치 방법을 확인하는 걸 추천합니다. (환경별 패키지 매니저나 설치 경로가 다를 수 있습니다.)

Codex는 프로젝트 루트에 있는 AGENTS.md를 읽어, "이 프로젝트에 맞는 작업 규칙"을 이해합니다. 예를 들어 아래처럼 작성할 수 있습니다.

# AGENTS.md
 
<INSTRUCTIONS>
- 모든 변경은 한국어로 설명한다
- 의존성 추가 전에는 반드시 승인 요청
- 변경 전후 파일 위치를 명확히 기록
</INSTRUCTIONS>

이 파일을 통해 팀의 스타일이나 레포 구조 규칙을 Codex에게 강제로 주입할 수 있습니다. 특히 모노레포, 다양한 앱 구조가 있는 프로젝트라면 효과가 큽니다.

이 레포는 apps/와 packages/로 나뉜 모노레포 구조입니다. Codex에게 구조를 이해시키려면, 다음처럼 구체적인 경로를 포함한 요청이 도움이 됩니다.

codex "apps/blog/content/posts/ 안에 codex CLI 셋팅 가이드 mdx 작성해줘"

또는 구조 정리 작업처럼 판단이 필요한 요청도 잘 동작합니다.

codex "apps/ 안에 불필요한 앱이 있으면 제거하고 README 구조 설명도 정리해줘"

이렇게 경로 + 의도를 명확히 전달하면, Codex가 탐색 범위를 줄이고 빠르게 정확한 변경을 수행합니다.

Codex는 SKILL.md를 통해 특정 도메인에 맞춘 작업 절차를 학습시킬 수 있습니다.

예를 들어 "문서 작성 자동화" 스킬이 있다면, 다음과 같이 사용할 수 있습니다.

이는 단순 프롬프트보다 더 일관된 결과를 만들고, 팀 내 베스트 프랙티스를 유지하는 데 유리합니다.

프로젝트 루트에서 Codex를 실행한 뒤, 원하는 작업을 자연어로 요청합니다.

codex "프로젝트 구조 전반적으로 수정할 부분 있는지 확인해줘"

이후 Codex는 프로젝트를 탐색하고, 필요한 파일을 확인한 뒤 수정 제안을 하거나 실제 변경까지 진행합니다.

Codex CLI는 "프로젝트별 규칙 + 반복 가능한 워크플로"를 결합할 때 진짜 힘을 발휘합니다. 단순 자동 완성보다 훨씬 안정적인 에이전트 경험을 원한다면, AGENTS.md와 스킬 구조를 적극적으로 활용해 보세요.

다음 글에서는 실제 프로젝트에 맞춘 스킬 설계 방법이나 리팩터링 워크플로를 예시로 정리해볼 예정입니다.