매번 같은 말을 Codex에게 반복하고 계신가요? “한국어로 답해줘”, “원본 파일 건드리지 마”, “삭제 전에 목록 먼저 보여줘” — 이거, 사실 딱 한 번만 적어두면 다음 세션부터 영원히 안 쳐도 됩니다. AGENTS.md라는 파일 하나에 내 규칙을 써두면, 앱이든 CLI든 VS Code 확장이든 Codex가 열릴 때마다 그걸 자동으로 읽어들이거든요. ChatGPT Plus(월 약 3만 원) 구독만 있으면 따로 설정 페이지 헤맬 것도 없이 5분 만에 끝납니다.
1편에서 Codex 앱을 처음 설치하고 맛봤고, 2편에서 데이터 정리 잡일을 시키고, 3편에서 Gmail·구글 캘린더 연동까지 따라오셨다면, 이제 Codex를 업무에 들일 준비는 거의 끝난 셈이에요 (1편 — 설치·맛보기, 2편 — 데이터 잡일 실전 참고). 그런데 막상 매일 쓰다 보면 “매번 같은 말 타이핑하기 귀찮다”는 감각이 오거든요. 답변은 한국어로, 원본은 건드리지 말고, 메일 톤은 이렇게… 같은 걸 세션마다 다시 일러줘야 하니까요. 이번 편은 그걸 한 번에 끝내는 커스텀 지시(AGENTS.md) 세팅 편입니다.
매번 같은 말 반복이 문제였다
Codex 쓰기 시작하고 나서 가장 먼저 느낀 불편함이 이거였어요. 대화를 새로 열 때마다 처음부터 다시 설명을 해줘야 한다는 것.
“한국어로 답해줘.”
“파일 수정하기 전에 어떻게 바꿀 건지 먼저 보여줘.”
“원본은 건드리지 말고 복사본 만들어서 작업해.”
이 세 문장을 저는 거의 매 세션마다 첫 줄에 쳤습니다. 한두 번은 괜찮은데, 매일 하다 보니 진짜 피곤하더라고요. 챗봇이 아무리 똑똑해도 지난 대화를 기억 못 하면 사용자가 계속 같은 맥락을 공급해줘야 하니까요.
이걸 해결하는 게 커스텀 지시(Custom Instructions)입니다. 쉽게 말하면 “내가 항상 원하는 규칙”을 미리 파일에 적어두면, Codex가 새 대화를 열 때마다 그 파일을 먼저 읽고 시작하는 방식이에요. 한 번만 써두면 그다음부터는 제가 아무 말 안 해도 알아서 한국어로 답하고, 알아서 원본 보호하고, 알아서 작업 목록 먼저 보여줍니다.
반복 입력 제거, 매 세션 일관된 결과, 내 작업 스타일에 맞게 길들이기 — 이 세 가지가 커스텀 지시가 주는 실질적인 이득이거든요.
설정 메뉴 뒤졌는데 안 보인다고요?
저도 처음엔 한참 뒤졌습니다. 앱 어딘가에 “커스텀 지시” 버튼이 있겠거니 했는데 생각보다 구석에 있어요.
Codex 데스크탑 앱 기준으로는 이렇게 갑니다:
Settings → Personalization → Custom Instructions
Mac이면 Cmd+,로 Settings 바로 열 수 있고, Windows는 앱 상단 메뉴에서 Settings 눌러서 들어가면 됩니다. Personalization 탭 안에 Custom Instructions 입력란이 있어요. 여기에 지시사항을 텍스트로 써두면 끝. OpenAI 공식 문서에도 같은 경로로 안내돼 있습니다.
그런데 여기서 조금 흥미로운 게 있습니다. 이 입력란에 뭔가를 저장하면, 사실 그게 파일로 떨어집니다. 경로는 ~/.codex/AGENTS.md. GUI 입력창은 이 파일을 편집하는 껍데기일 뿐이에요.
~/.codex/AGENTS.md그러니까 파일을 직접 텍스트 에디터로 열어서 편집해도 결과가 완전히 동일합니다. 저는 오히려 이 방식을 더 자주 쓰게 됐는데, VS Code에서 열어두고 필요할 때 수정하는 게 더 편하거든요.
그리고 이게 진짜 편한 이유가 하나 더 있습니다. 앱, CLI, VS Code 확장 — 이 세 가지 모두 같은 ~/.codex/AGENTS.md 파일을 공유해요. 앱에서 지시사항 바꾸면 터미널에서 codex 명령어 쳐도 똑같이 적용되고, VS Code 확장에서도 그대로 읽혀요. 한 곳에서 한 번만 고치면 셋 다 한꺼번에 바뀌는 겁니다.
한 가지 알아두면 좋은 동작 방식이 있는데, 커스텀 지시는 세션 시작 시 1회 로드됩니다. 지금 진행 중인 대화 도중에 AGENTS.md를 수정했다고 해서 바로 적용되는 게 아니에요. 수정한 내용은 다음 새 대화(스레드)를 열었을 때부터 반영됩니다. 그러니 지시사항 바꿨는데 왜 반응이 다르지 싶으면 — 새 대화 한 번 열어보시면 됩니다.
AGENTS.md에 뭘 적어야 하나
설정 화면에서 AGENTS.md를 처음 열었을 때 멍해지는 분들이 꽤 있을 거예요. “여기에 뭘 쓰면 되지?” 싶은 그 감각이요.
결론부터 말하면, 좋은 AGENTS.md는 명령형 + 구체적이에요. “잘 해줘”가 아니라 “이렇게 해”가 통하는 거거든요.
제가 실제로 쓰는 기본 템플릿입니다. 직장인이라면 거의 그대로 복사해도 될 거예요.
# 내 작업 기본 규칙
- 모든 답변과 설명은 한국어로 작성한다.
- 파일을 수정·삭제·이동하기 전에 무엇을 할지 먼저 계획을 보여주고 확인받는다.
- 엑셀·CSV·문서 작업 시 원본은 덮어쓰지 말고 새 파일로 저장한다.
- 삭제는 먼저 대상 목록을 보여주고, 내가 승인한 뒤에만 실행한다.
- 다음 폴더는 건드리지 않는다: C:\Users\내이름\중요한폴더눈치 채셨나요? 이게 바로 지난 2편에서 다뤘던 “삭제 사고 예방 2단계 패턴”을 아예 기본 규칙으로 박아두는 방식이에요. 매번 프롬프트에 “삭제 전에 목록 보여줘”라고 타이핑할 필요가 없어지는 거죠. 처음부터 그게 기본값이 되는 거니까요.
나쁜 예 vs 좋은 예를 비교해 볼게요.
| 구분 | 예시 | 왜 |
|---|---|---|
| ❌ 모호 | “코드를 깔끔하게 유지해줘” | Codex가 “깔끔”을 판단할 수 없음 |
| ✅ 구체 | “한 줄 80자 넘으면 줄바꿈, 수정 전 원본은 _backup 파일로 저장” | 측정 가능, 조건 명확 |
| ❌ 모호 | “중요한 파일은 조심해서 다뤄줘” | “중요한”의 기준이 없음 |
| ✅ 구체 | “확장자가 .xlsx, .pdf인 파일은 수정 전 반드시 확인받는다” | 에이전트가 판단 없이 따를 수 있음 |
GitHub이 레포 2,500개 이상을 분석해 정리한 글에서도 비슷한 결론이 나왔더라고요. AGENTS.md에서 효과적이라고 꼽힌 구성은 명령어 섹션을 앞쪽에 배치하는 패턴이었고, 모호한 표현(“클린한 코드”)은 실제로 잘 작동하지 않는다는 거예요. “npm run lint 실행”처럼 에이전트가 그냥 따를 수 있는 명령이 통한다는 거죠.
한 가지 더 — 짧게 유지하는 게 미덕이에요. 장황한 아키텍처 설명이나 “왜 그래야 하는지” 배경 설명은 빼세요. 길고 설명이 많은 AGENTS.md는 토큰만 소비하고 실제 동작에는 별 영향이 없다는 연구 결과도 있거든요. 규칙은 한 줄, 명령형, 구체적. 그게 전부예요.
config.toml이랑 뭐가 다른가요
Codex를 처음 세팅할 때 헷갈리는 지점이 하나 있어요. ~/.codex/ 폴더를 열어보면 파일이 두 개거든요.
~/.codex/
├── config.toml
└── AGENTS.md이름도 다르고 형식도 다른데, 뭐가 뭔지 처음엔 잘 안 와닿죠. 비유로 먼저 설명하면 이래요.
config.toml = 기계 다이얼 설정
AGENTS.md = 비서에게 남기는 메모
조금 더 풀어보면, config.toml은 Codex라는 기계 자체를 어떻게 동작시킬지를 설정하는 파일이에요. 어떤 AI 모델을 쓸지, 파일 접근 권한을 어느 수준으로 줄지, 자동 승인을 켤지 말지, MCP 서버를 연결할지. 이런 게 다 여기 있어요. TOML(설정 값을 적는 텍스트 형식인데, 윈도우 ini 파일과 비슷하다고 보시면 돼요)이라는 형식으로 작성하고요.
AGENTS.md는 다르죠. 이건 에이전트한테 말로 지시하는 메모예요. “한국어로 답해”, “삭제 전에 목록 먼저 보여줘”, “원본은 건드리지 마” 같은 자연어 규칙을 마크다운으로 쓰는 거예요.
| 항목 | config.toml | AGENTS.md |
|---|---|---|
| 형식 | TOML | Markdown |
| 역할 | Codex 앱 동작 방식 설정 | 에이전트에게 전달하는 지시 |
| 예시 내용 | 모델 선택, 샌드박스 모드, 승인 정책, MCP 서버 연결 | 작업 언어, 파일 보호 규칙, 답변 스타일 |
| 누가 읽나 | Codex 앱 자체 | AI 에이전트 |
| 언제 적용 | 앱 시작 시 | 작업 실행 시 |
쉽게 기억하려면 이렇게 생각하면 돼요. config.toml은 차의 기어와 브레이크 세팅, AGENTS.md는 내비게이션에 저장해둔 “집 가는 길 경유지” 같은 거예요. 둘 다 필요하지만 건드리는 이유가 전혀 달라요.
전역이냐 프로젝트별이냐 — 계층 구조
AGENTS.md의 진짜 강점은 여기서 나오는데, 계층 구조를 지원한다는 점이에요.
Codex는 작업을 실행할 때 AGENTS.md를 한 곳이 아니라 세 군데에서 찾아요.
1. ~/.codex/AGENTS.md ← 전역 (모든 작업에 적용)
2. /내프로젝트/AGENTS.md ← 프로젝트 루트 (해당 폴더 작업에만)
3. /내프로젝트/하위폴더/AGENTS.md ← 하위 폴더 (더 구체적 규칙)그리고 이 세 파일을 순서대로 이어붙여서(concatenate) 에이전트한테 전달해요. 전역 → 프로젝트 → 하위폴더 순으로요. 중요한 건, 아래쪽(작업 폴더에 가까운)에 있는 규칙이 더 강하게 작동한다는 거예요.
실제로 어떻게 쓰면 좋을지 직장인 예시를 들어볼게요.
~/.codex/AGENTS.md (전역 — 항상 적용)
- 모든 답변은 한국어로 작성한다.
- 파일 수정 전 계획을 먼저 보여주고 확인받는다.
- 원본 파일은 항상 백업 복사본을 만든 뒤 수정한다.~/회계자료/AGENTS.md (프로젝트별 — 이 폴더 작업에만 추가 적용)
- 이 폴더의 숫자(금액, 수량)는 내가 명시적으로 요청하지 않으면 절대 수정하지 않는다.
- .xlsx 파일은 읽기 전용으로 다루며, 새 결과물은 반드시 별도 파일로 저장한다.
- 이 폴더에서 파일 삭제 명령은 절대 실행하지 않는다.이렇게 분리해두면 회계 폴더에서 작업할 때는 전역 규칙 + 회계 폴더 전용 규칙이 같이 적용되는 거예요. 다른 폴더에서 작업할 땐 전역 규칙만 적용되고요.
처음엔 “이걸 이렇게까지 나눠야 하나” 싶었는데, 써보니까 이게 맞아요. 전역 규칙을 너무 빡빡하게 잡으면 간단한 작업에서도 확인 요청이 쏟아지거든요. 폴더별로 분리하면 “조심해야 할 곳에서만 조심”이 자동으로 되는 거니까, 훨씬 자연스럽게 쓸 수 있더라고요.
분명 적었는데 안 먹어요 — 함정 3가지
설정 파일을 열심히 채웠는데 Codex가 딴소리를 한다면, 십중팔구 아래 세 함정 중 하나입니다. 저도 다 밟아봤거든요.
함정① 32KB 넘으면 조용히 잘린다
AGENTS.md에는 기본 32KiB(32,768바이트) 한도가 있어요. 초과해도 오류 메시지 같은 건 없고, 그냥 뒷부분이 조용히 잘립니다. 문제는 한글인데요 — 한글 한 글자가 UTF-8로 3바이트거든요. 영어는 1바이트니까, 한글로 가득 채우면 영어 대비 3배 빨리 한도에 닿아요. “나중에 추가하면 되겠지” 하다 보면 뒤에 적은 규칙이 통째로 무시되는 겁니다.
대책은 간단해요. 짧고 핵심만 적는 거예요. 중언부언 설명 길게 쓰지 말고, 규칙 자체를 간결하게. 그래도 한도를 늘리고 싶다면 config.toml의 project_doc_max_bytes 값을 올리면 됩니다.
함정② UTF-8 BOM — 윈도우 메모장의 덫
윈도우 환경에서 메모장으로 AGENTS.md를 저장하면 파일 맨 앞에 UTF-8 BOM이라는 표식이 붙어요. 눈에 안 보이는 문자가 몇 바이트 슬쩍 붙는 건데, 2026년 5월 v0.133.0 이전 Codex 버전은 이걸 만나면 파일 자체를 통째로 무시했습니다. 경고도 없이요.
“한글로 꼼꼼히 적었는데 아무리 고쳐도 반응이 없다” — 이 현상의 범인이 바로 BOM이었어요. 해결법은 VS Code 같은 에디터로 “BOM 없는 UTF-8″로 저장하는 것. VS Code에서는 우측 하단 UTF-8 클릭 → “BOM 없이 저장”이면 됩니다. 2026년 5월 말 v0.133.0부터는 이런 인코딩 문제에 경고를 띄워주는 쪽으로 개선됐는데, 그 전 버전 쓰고 있으면 지금 바로 에디터에서 인코딩부터 확인해 보세요.
함정③ AGENTS.override.md는 ‘추가’가 아니라 ‘교체’
같은 폴더에 AGENTS.override.md를 두면 뭔가 우선순위가 높게 적용되는 느낌이잖아요. 근데 이게 기존 AGENTS.md에 더해지는 게 아니라 그 레벨의 AGENTS.md를 통째로 갈아치웁니다. 모르고 만들어두면 기존 규칙이 싹 사라지고 override 파일 내용만 남아요. 저는 이것 때문에 전역 지시사항이 왜 안 먹히나 한참 헤맸거든요.
실전 확인 팁 하나 드리면, Codex에게 “지금 적용된 작업 규칙을 요약해줘”라고 물어보세요. 답하는 내용을 보면 내가 적은 규칙이 제대로 들어갔는지 대략 가늠해볼 수 있어요.
Codex랑 클로드 같이 쓰는 분이라면
이 블로그 보시는 분 중에 Claude Code(클로드)도 병행하시는 분 꽤 많을 것 같아서 따로 적어요. 저도 두 도구를 같이 쓰거든요.
결론부터 말하면, 클로드는 AGENTS.md를 직접 읽지 않아요 (2026년 5월 기준). 클로드는 CLAUDE.md를 봐요. 그러니까 Codex용으로 AGENTS.md에 열심히 규칙을 써도, 클로드한테는 그게 안 먹히는 거예요. 두 도구를 같이 쓰면 규칙을 두 군데서 따로 관리해야 하는 상황이 생기는 거죠. 번거롭더라고요.
우회 방법은 두 가지예요.
# 방법1: CLAUDE.md 안에서 AGENTS.md import
@AGENTS.mdCLAUDE.md 첫 줄에 이렇게 넣으면 클로드가 AGENTS.md 내용을 같이 읽어요. 규칙 파일은 AGENTS.md 하나만 관리하면 됩니다.
두 번째는 심볼릭 링크예요. 심볼릭 링크는 파일 두 개를 하나처럼 연결해서, 한쪽을 고치면 양쪽이 같이 바뀌게 만드는 방식이에요. 바로가기랑 비슷한데 좀 더 단단하게 묶이는 거라고 보시면 됩니다.
# 방법2: 심볼릭 링크로 파일 공유 (윈도우는 관리자 권한 필요)
# ⚠️ 기존 CLAUDE.md가 있으면 먼저 백업하세요 — 안 그러면 명령이 실패하거나 기존 내용이 사라집니다
mv ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak # 기존 파일 백업
ln -s ~/.codex/AGENTS.md ~/.claude/CLAUDE.md # AGENTS.md를 CLAUDE.md로 연결여기서 꼭 조심할 게 있어요. 이미 ~/.claude/CLAUDE.md에 클로드용 규칙을 따로 적어둔 상태라면, 위 링크 명령이 그걸 덮어쓰거나 명령 자체가 실패합니다. 그래서 반드시 기존 파일을 백업한 뒤에 연결하세요. 클로드 규칙과 Codex 규칙을 둘 다 살리고 싶으면, 링크 대신 위의 @AGENTS.md import 방법이 더 안전합니다.
사실 AGENTS.md는 지금 업계 표준 쪽으로 가고 있어요. Cursor, GitHub Copilot, Gemini CLI, Aider, Windsurf, Zed 같은 도구들이 다 지원하거든요. Linux Foundation 오픈표준으로도 올라간 상태고요. 클로드만 예외 처리가 필요한 상황인데, @import 방법 하나면 해결되니까 크게 불편하진 않아요. 클로드를 처음 켰을 때 막혔던 이야기도 따로 글로 다룬 적 있으니 클로드 쪽이 궁금하면 참고해 보세요.
정리 + 다음 편 예고
이번 편 핵심은 한 줄이에요.
AGENTS.md 한 번 적어두면 매 세션 반복 입력이 사라지고, Codex가 내 규칙대로 움직인다. 단 32KB·BOM·override 세 함정만 피하면 된다.
전역(~/.codex/AGENTS.md)에 공통 규칙을 두고, 프로젝트마다 필요한 것만 로컬 AGENTS.md로 덮어쓰는 구조가 제일 깔끔하더라고요. 설정 파일 하나가 비서를 바꿔버리는 경험, 해보면 다시는 예전으로 못 돌아가요.
여기까지 따라오셨다면 Codex 기본 셋업은 끝난 셈이에요. 설치(1편)·데이터 잡일(2편)·Gmail·캘린더 연동(3편)·커스텀 지시(4편)까지, 직장인이 Codex를 업무에 들이는 데 필요한 건 거의 다뤘습니다. 이제 본인 업무에 맞게 AGENTS.md 규칙만 조금씩 다듬어가면, Codex가 점점 더 내 방식대로 움직이는 게 보일 거예요.
Codex는 ChatGPT Plus 구독(월 약 3만 원)에 포함돼 있어요. 데스크탑 앱 별도 결제 없이 쓸 수 있으니, 아직 구독 전이라면 유료 구독 결정 전에 350개 AI를 한 사이트에서 블라인드로 비교하는 법도 한번 보고 결정하셔도 좋고요.
