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

Posted Mar 15, 2026

By rkgh17

5 min read

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

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

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

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

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

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

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

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

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

This post is licensed under CC BY 4.0 by the author.