📋기본 세팅
AI에게 프로젝트를 알려주기
AGENTS.md를 작성하여 AI에게 프로젝트의 맥락과 규칙을 알려주는 방법을 배웁니다.
Chapter 3: 기본 세팅 — AI에게 프로젝트를 알려주기
"오케스트라에 악보 없이 '그냥 좋은 음악 해줘'라고 하면 어떻게 될까요?"
혼란스러운 소리가 나겠죠. AI 코딩 도구도 마찬가지입니다. 프로젝트에 대한 정보가 없으면, AI는 무엇을 만들어야 하는지, 어떤 규칙을 따라야 하는지 알 수 없습니다.
이번 챕터에서는 AI에게 **프로젝트의 총보(score)**를 건네주는 방법을 배웁니다.
AGENTS.md란?
AGENTS.md는 GPT Codex CLI가 프로젝트에 대해 알아야 할 모든 정보를 담은 마크다운 파일입니다. 프로젝트 폴더의 루트(최상위)에 이 파일을 놓으면, Codex가 작업을 시작할 때 자동으로 읽어들입니다.
AGENTS.md = 총보(Full Score)
오케스트라 총보에는 다음이 적혀 있습니다:
- 곡의 제목, 작곡가, 장르
- 사용하는 악기 편성 (2 Fl, 2 Ob, 2 Cl, 2 Bn...)
- 템포 지시 (Allegro, ♩= 120)
- 조성 (C major)
- 각 섹션의 역할과 규칙
AGENTS.md에는 이런 것들이 적혀 있습니다:
- 프로젝트 이름과 목적
- 사용하는 기술 스택 (React, Python, MediaPipe...)
- 코딩 스타일 규칙
- 파일 구조
- 주의사항
총보 없이 연주할 수 있는 오케스트라는 없습니다. AGENTS.md 없이도 Codex는 작동하지만, 결과의 품질이 크게 달라집니다.
AGENTS.md 작성법
기본 구조
AGENTS.md는 평범한 텍스트 파일입니다. 마크다운 문법을 사용하지만, 복잡한 것은 없습니다. 핵심은 AI가 알아야 할 정보를 명확하게 적는 것입니다.
각 섹션 자세히 보기
1. 개요 (Overview)
프로젝트가 무엇이고 왜 만드는지 한두 문장으로 설명합니다.
총보 첫 페이지의 곡 제목과 프로그램 노트입니다. "이 곡은 XX를 위해 작곡된 실내악 작품이다" 같은 설명이죠.
2. 기술 스택 (Tech Stack)
사용하는 기술을 나열합니다. 이것은 AI에게 "이 악기들만 사용해"라고 지시하는 것과 같습니다.
왜 중요할까요? 기술 스택을 명시하지 않으면, AI가 자기 마음대로 라이브러리를 선택합니다. "바이올린 소나타를 써달라고 했더니 일렉 기타를 꺼내는" 상황을 방지합니다.
3. 파일 구조 (File Structure)
프로젝트의 폴더/파일 구성을 보여줍니다. AI가 새 파일을 만들 때 이 구조를 따르게 됩니다.
악보의 파트 배치와 같습니다. "1단은 피콜로, 2단은 플루트, 3단은 오보에..." 이렇게 정해두면, 새로운 마디를 쓸 때도 같은 배치를 따르겠죠.
4. 코딩 규칙 (Coding Rules)
코드 작성 시 지켜야 할 규칙입니다. 변수 이름 규칙, 주석 언어, 코드 스타일 등.
5. 주의사항 (Important Notes)
AI가 흔히 실수하는 부분이나, 특별히 주의해야 할 점을 적습니다.
전역 설정 vs 프로젝트 설정
Codex에는 두 가지 설정 레벨이 있습니다:
전역 설정: ~/.codex/config.toml
홈 디렉토리의 .codex 폴더에 있는 설정 파일입니다. 모든 프로젝트에 적용됩니다.
전역 설정은 개인 악기 세팅입니다. 어떤 오케스트라에 가든 여러분의 악기 셋업(리드 강도, 마우스피스 종류 등)은 동일하죠? 마찬가지로, 전역 설정은 어떤 프로젝트에서든 적용되는 개인 선호도입니다.
프로젝트 설정: .codex/config.toml
프로젝트 폴더 안에 .codex 폴더를 만들고 config.toml을 넣으면, 해당 프로젝트에서만 적용되는 설정을 만들 수 있습니다.
프로젝트 설정은 곡별 악기 세팅입니다. 재즈 공연에서는 마우스피스를 바꾸고, 클래식 공연에서는 다른 마우스피스를 쓰듯이, 프로젝트마다 다른 설정을 적용할 수 있습니다.
프로젝트 설정이 전역 설정보다 우선합니다. 전역에서 suggest로 설정했더라도, 프로젝트에서 auto-edit으로 설정하면 해당 프로젝트에서는 auto-edit이 적용됩니다.
AGENTS.override.md — 개인 설정 오버라이드
팀 프로젝트에서는 AGENTS.md를 모든 팀원이 공유합니다. 하지만 개인적인 선호(예: 주석을 한국어로 쓰고 싶다)가 있을 때는 AGENTS.override.md를 사용합니다.
AGENTS.md = 지휘자가 전체 오케스트라에게 주는 공통 지시 AGENTS.override.md = 각 연주자가 자기 파트보에 연필로 적어넣는 개인 메모
"여기서 보잉을 업으로", "이 부분 살짝 루바토" — 이런 개인 해석을 적는 공간입니다. 다른 연주자에게는 보이지 않지만, 자기 연주에는 반영됩니다.
AGENTS.override.md는 개인 설정이므로, git에 올리면 안 됩니다. .gitignore 파일에 AGENTS.override.md를 추가하세요. (git이 뭔지는 나중 챕터에서 배웁니다.)
(비교) Claude Code: CLAUDE.md
Claude Code에서는 AGENTS.md 대신 CLAUDE.md라는 파일을 사용합니다. 역할은 동일하지만, 이름과 몇 가지 세부 사항이 다릅니다.
Claude Code에는 /init 명령어가 있어서, 프로젝트 폴더를 분석해 CLAUDE.md 초안을 자동으로 생성해줍니다.
Claude Code의 전역 설정은 프로젝트 설정 페이지나 ~/.claude/ 디렉토리에서 관리합니다.
(비교) Gemini CLI: 설정 파일 구조
Gemini CLI는 약간 다른 방식을 사용합니다:
- 전역 설정:
~/.gemini/settings.json— JSON 형식의 전역 설정 - 프로젝트 설정:
.gemini/settings.json— 프로젝트별 설정 - 커스텀 명령어:
.gemini/commands/폴더에 재사용 가능한 프롬프트 저장 - 프로젝트 지침:
GEMINI.md— Codex의 AGENTS.md와 같은 역할
Gemini의 커스텀 명령어 기능은 자주 사용하는 프롬프트를 저장해두고 재사용할 수 있어 편리합니다:
세 도구의 설정 비교
실전: 음악 프로젝트용 AGENTS.md 작성하기
이제 실제로 여러분의 첫 AGENTS.md를 작성해봅시다. MediaPipe 제스처 컨트롤러 프로젝트를 위한 완전한 예시입니다.
프로젝트 폴더로 이동
AGENTS.md 파일 생성
아무 텍스트 에디터로 AGENTS.md 파일을 만듭니다. 터미널에서도 가능합니다:
네, 맞습니다! AGENTS.md 자체도 바이브 코딩으로 만들 수 있습니다. AI에게 프로젝트를 설명하면, AI가 AGENTS.md를 작성해줍니다.
내용 확인 및 수정
생성된 AGENTS.md를 확인하고, 필요하면 수정합니다:
구체적으로 적을수록 좋습니다. 모호한 지시는 모호한 결과를 만듭니다.
나쁜 예: "깔끔하게 코딩해줘" 좋은 예: "함수 하나는 30줄을 넘지 않게, 변수 이름은 camelCase로, 모든 함수 위에 JSDoc 주석을 달아줘"
이것은 음악에서도 마찬가지입니다: 나쁜 지시: "감정을 살려서 연주해주세요" 좋은 지시: "마디 24부터 mp에서 시작해서 마디 32까지 점진적으로 ff까지 크레셴도해주세요"
프로젝트별 전문화
하나의 AGENTS.md가 모든 프로젝트에 맞지는 않습니다. 프로젝트의 성격에 따라 다른 지침을 작성해야 합니다.
예시 1: 음악 인터랙션 프로젝트
예시 2: 포트폴리오 웹사이트 프로젝트
같은 작곡가라도 영화 음악과 실내악을 쓸 때 악보 작성 방식이 다릅니다. 영화 음악은 타임코드와 싱크 포인트가 중요하고, 실내악은 각 파트의 독립성과 앙상블 밸런스가 중요하죠.
프로젝트별 AGENTS.md도 마찬가지입니다. 실시간 인터랙션 프로젝트에서는 성능이 최우선이고, 포트폴리오에서는 디자인과 SEO가 최우선입니다.
다음 챕터 미리보기
AGENTS.md로 AI에게 프로젝트를 알려주는 방법을 배웠습니다. 다음 챕터에서는 AI의 기억력에 대해 배웁니다. AI가 얼마나 많은 내용을 기억할 수 있는지, 기억이 넘치면 어떻게 되는지, 그리고 기억을 효율적으로 관리하는 방법을 알아봅니다.
- AGENTS.md = AI에게 주는 총보(Full Score). 프로젝트의 모든 규칙과 정보를 담는다.
- 전역 설정 = 모든 프로젝트에 적용되는 개인 선호.
~/.codex/config.toml - 프로젝트 설정 = 특정 프로젝트에만 적용.
.codex/config.toml - AGENTS.override.md = 팀 프로젝트에서의 개인 메모. git에 올리지 않는다.
- 구체적으로 적을수록 AI의 결과물이 좋아진다. "감정을 살려서"가 아니라 "mp에서 ff까지 크레셴도"처럼!