코덱스(Codex) 사용법, AGENTS.md부터 MCP까지 하네스 세팅 가이드

아직도 코덱스에 일을 맡길 때마다 프로젝트 구조, 코드 규칙, 테스트 방법을 채팅창에 다시 붙여 넣고, 명령 하나 실행할 때마다 승인 버튼을 누르고 계신가요? 설명이 매번 조금씩 달라지니 결과도 들쭉날쭉해지고, 어느새 AI에게 맡긴 일보다 AI를 챙기는 일이 더 많아집니다.

코덱스(Codex)는 OpenAI가 만든 코딩 에이전트로, 터미널(CLI)·IDE·데스크톱 앱에서 코드를 읽고 고치고 명령을 실행합니다. 하네스는 모델이 실제로 일하게 만드는 지침·도구·권한 설정 전체를 뜻합니다. 이 글에서는 하네스를 AGENTS.md(지침), config.toml(모델·승인·샌드박스), 스킬과 MCP(도구) 세 층으로 세팅하는 순서와 Claude Code와 함께 쓸 때 지침 원본을 하나로 두는 방법, 다글로로 받아쓴 기획 회의를 작업 지시 초안으로 바꾸는 흐름까지 정리합니다.

코덱스 사용법의 핵심, 하네스란 무엇인가?

코덱스 사용법을 한 문장으로 줄이면 "매번 설명하지 말고 한 번 적어 두라"입니다. 코덱스는 세션을 시작할 때 AGENTS.md와 config.toml을 읽고, 필요할 때 스킬과 MCP 도구를 불러 씁니다.

설치는 공식 문서 안내대로 npm(npm i -g @openai/codex)이나 Homebrew로 하고, 터미널에서 codex를 실행해 ChatGPT 계정으로 로그인하면 됩니다.

AGENTS.md 작성법과 적용 순서

AGENTS.md는 코덱스가 작업 전에 읽는 마크다운 지침 파일입니다. 전역 파일(~/.codex/AGENTS.md)에는 모든 프로젝트에 공통인 습관을, 저장소 루트의 AGENTS.md에는 그 프로젝트만의 규칙을 적습니다.

코덱스는 아래 순서로 지침을 읽고 합칩니다.

1. 전역: ~/.codex 폴더에서 AGENTS.override.md가 있으면 그 파일을, 없으면 AGENTS.md를 읽습니다.
2. 저장소: 저장소 루트부터 지금 작업 중인 폴더까지 내려가며 폴더마다 파일 하나(AGENTS.override.md, AGENTS.md 순)를 읽습니다.
3. 합치기: 읽은 파일을 위에서부터 이어 붙입니다. 현재 폴더에 가까운 파일이 뒤에 붙으므로 앞의 지침보다 우선합니다.

합친 크기는 기본 32KiB(project_doc_max_bytes)까지만 읽습니다. 그래서 길게 쓰기보다 자주 틀리는 규칙 위주로 짧게 씁니다. 저장소 AGENTS.md에는 보통 다음 내용을 넣습니다.

• 프로젝트 한 줄 소개와 주요 폴더 구조
• 빌드·테스트·린트 명령과 "작업 후 반드시 테스트 실행" 같은 완료 기준
• 코드 스타일과 커밋 메시지 규칙
• 건드리면 안 되는 파일, 사람에게 먼저 물어야 하는 작업

지침이 제대로 읽혔는지는 저장소 루트에서 codex --ask-for-approval never "Summarize the current instructions."를 실행해 확인합니다.

config.toml로 모델·승인 모드·샌드박스 정하기

config.toml은 코덱스가 어떤 모델로, 어디까지 스스로 일할지 정하는 설정 파일입니다. 사용자 설정은 ~/.codex/config.toml에 두고, 저장소별 설정은 .codex/config.toml에 두면 신뢰한 프로젝트에서만 적용됩니다.

model = "사용할 모델 이름"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

• model: 기본으로 쓸 모델입니다. 모델 이름은 자주 바뀌므로 공식 문서에 있는 최신 이름을 넣습니다.
• approval_policy: 언제 사람의 승인을 받을지 정합니다. on-request는 코덱스가 필요하다고 판단할 때 묻고, never는 묻지 않습니다.
• sandbox_mode: 코덱스가 건드릴 수 있는 범위입니다. read-only는 읽기만, workspace-write는 작업 폴더 안의 쓰기까지, danger-full-access는 제한 없이 허용합니다.

처음에는 on-request와 workspace-write 조합으로 시작해 작업 폴더 밖의 변경을 막고, 익숙해진 뒤에 범위를 넓히는 편이 안전합니다. 같은 값은 실행할 때 --sandbox, --ask-for-approval 옵션으로 잠깐 바꿀 수도 있습니다.

스킬과 MCP로 도구 연결하기

스킬은 필요할 때만 불러오는 업무 절차이고, MCP(Model Context Protocol)는 코덱스를 외부 서비스·도구에 연결하는 표준입니다. 둘 다 AGENTS.md를 가볍게 유지하면서 코덱스가 할 수 있는 일을 늘려 줍니다.

• 스킬: 저장소의 .agents/skills/이름/SKILL.md에 이름·설명과 절차를 적습니다. 코덱스는 평소 이름과 설명만 보고 있다가 요청과 맞을 때 본문을 엽니다. CLI에서 /skills로 목록을 보고 $스킬이름으로 직접 부를 수 있으며, $skill-creator로 대화하며 새 스킬을 만들 수도 있습니다.
• MCP: codex mcp add context7 -- npx -y @upstash/context7-mcp처럼 명령으로 추가하거나, config.toml에 [mcp_servers.이름] 표를 만들고 command와 args를 적습니다. 연결 상태는 코덱스 화면에서 /mcp로 확인합니다.

MCP 서버는 내 계정 권한으로 외부 서비스에 접근합니다. 그래서 공식 배포처의 서버만 연결하고, 토큰은 설정 파일에 직접 적지 말고 환경변수로 넘깁니다.

Claude Code와 함께 쓸 때, 지침 원본은 하나로

코덱스는 AGENTS.md를, Claude Code는 CLAUDE.md를 읽습니다. 두 파일을 따로 관리하면 한쪽만 고쳐져 규칙이 어긋나므로, AGENTS.md 하나를 원본으로 두고 Claude Code가 그 파일을 읽게 하는 방법이 가장 간단합니다.

스킬은 두 도구 모두 SKILL.md 형식(Agent Skills 표준)을 쓰므로, 한 번 만든 절차를 양쪽에서 다시 쓸 수 있습니다.

다글로로 기획 회의를 작업 지시 초안으로 바꾸기

좋은 AGENTS.md와 작업 지시는 결국 회의에서 정한 요구사항에서 나옵니다. 기획 회의를 녹음해 다글로로 받아쓰면 화자가 구분된 원문과 요약이 남아 그대로 지침의 재료가 됩니다.

1. 참석자 동의를 받고 기획 회의를 녹음한 뒤 다글로에 올려 받아씁니다.
2. 같은 프로젝트의 회의 기록을 한 보드에 모으고, 보드챗에 "회의에서 정한 요구사항과 제약 조건만 목록으로 정리해 줘"라고 묻습니다.
3. 답을 검토해 계속 지킬 규칙은 AGENTS.md에, 이번 작업에만 필요한 내용은 코덱스에 줄 작업 지시로 옮깁니다.

결정되지 않은 내용이 지침에 섞이지 않도록 "확정"과 "논의 중"을 나눠 달라고 함께 요청하면 좋습니다.

정리하면, 코덱스는 AGENTS.md로 규칙을 알려 주고 config.toml로 권한을 정하고 스킬과 MCP로 도구를 붙였을 때 꾸준히 같은 품질을 냅니다. 설정 키와 명령은 자주 바뀌므로 세팅 전에 공식 문서를 한 번 더 확인하세요.

#코덱스 #Codex #코덱스사용법 #AGENTSmd #하네스엔지니어링 #MCP #AI코딩 #다글로

👉 기획 회의 무료로 받아쓰기 시작하기