코덱스 AGENTS.md 작성법: 읽는 위치와 프로젝트 규칙

프로젝트 구조, 실행할 명령, 수정하지 않을 파일, 완료 전에 확인할 항목을 적어요. ‘좋은 코드를 작성해’보다 ‘frontend에서 pnpm lint를 실행해’처럼 실제 경로와 명령을 알려 주는 편이 작업에 도움이 돼요.

한 번만 필요한 요청은 대화에 적고, 여러 작업에서 반복될 규칙을 파일에 남겨 보세요. 업무 배경이 길다면 관련 문서의 경로와 언제 읽을지를 적을 수 있어요. 오래된 명령을 많이 넣기보다 지금 사용하는 절차와 맞는지 확인해 주세요.

Codex는 기본적으로 ~/.codex의 개인 지침을 보고, 프로젝트 최상위에서 현재 작업 폴더까지 내려가며 지침을 모아요. CODEX_HOME을 별도로 지정했다면 개인 지침 위치도 달라져요. 현재 폴더에 가까운 지침은 앞서 읽은 프로젝트 규칙을 구체화하거나 덮어쓸 수 있어요.

같은 폴더에 AGENTS.override.md가 있으면 일반 AGENTS.md보다 먼저 선택돼요. 두 파일을 항상 함께 읽는 방식은 아니에요. override는 임시 예외가 필요할 때 쓰고, 예외가 끝나면 남아 있지 않은지 확인해 주세요.

아래는 frontend와 backend가 있는 프로젝트를 위한 작성 예시예요. 실제 폴더 구조와 명령에 맞춰 바꾸고, 기존 AGENTS.md가 있다면 필요한 항목을 합쳐 주세요. 이 예시를 그대로 모든 저장소에 적용하면 없는 명령을 실행하게 될 수 있어요.

# AGENTS.md ## 작업 위치 - 화면 작업은 frontend/에서 진행해 주세요. - API 작업은 backend/에서 진행해 주세요. - 작업할 서비스의 AGENTS.md를 먼저 읽어 주세요. ## 변경 범위 - 요청과 관계없는 파일은 수정하지 말아 주세요. - 자동 생성 파일을 고쳐야 한다면 생성 방법부터 확인해 주세요. ## 완료 확인 - frontend 변경 뒤에는 frontend/에서 pnpm lint를 실행해 주세요. - 실행한 검사와 확인하지 못한 항목을 결과에 적어 주세요.

문서를 저장한 뒤 연습용 작업으로 시험해 보세요. 올바른 폴더에서 명령을 실행하는지, 하지 않은 검사를 통과했다고 보고하지 않는지 확인하면 규칙이 실제로 도움이 되는지 알 수 있어요.

시작 시 지침 탐색은 현재 작업 폴더까지예요. 저장소 최상위에서 시작했다면 frontend/AGENTS.md가 그 탐색 경로에 없을 수 있어요. 최상위 지침에서 ‘화면 작업 전 frontend/AGENTS.md를 읽어 주세요’라고 안내하거나 해당 폴더에서 작업을 시작해 보세요.

CLI에서는 다음처럼 작업 폴더를 정해 읽은 지침을 확인할 수 있어요. frontend가 실제로 있는 프로젝트에서 실행해 주세요.

codex --cd frontend "현재 적용된 지침 파일의 경로와 핵심 규칙을 정리해 줘. 아직 파일은 수정하지 마."

예상한 파일이 빠졌다면 경로와 파일명, 같은 폴더의 override 파일을 확인해요. 지침을 바꾼 뒤에는 새 실행이나 세션에서 확인해야 시작 시 구성된 지침과 혼동하지 않아요.

AGENTS.md에는 프로젝트의 공통 작업 규칙을, 스킬에는 특정 작업을 수행하는 절차를 둬요. DESIGN.md에는 색과 글자, 컴포넌트 기준을 모을 수 있어요. 디자인 문서는 파일명만으로 자동 적용된다고 생각하지 말고 지침에서 읽을 시점을 알려 주세요.

예를 들어 AGENTS.md에는 ‘UI 수정 전 frontend/DESIGN.md를 읽고 기존 컴포넌트를 확인해 주세요’라고 적어요. 여러 단계를 가진 접근성 점검은 별도 스킬로 두면 공통 지침이 길어지는 것을 줄일 수 있어요.

같은 내용이 반복되거나 실제 명령과 달라진 부분부터 정리해요. 무엇을 지킬지와 어떻게 확인할지를 남기고, 긴 배경 자료는 별도 문서로 연결해 보세요. 기본 지침 크기 제한도 있으므로 파일을 계속 늘리기만 하면 일부가 포함되지 않을 수 있어요.

검증 요청 예시: ‘현재 적용된 지침의 출처를 나열하고, 이 작업을 어느 폴더에서 진행할지와 완료 후 실행할 검사를 설명해 줘. 실제로 읽지 못한 파일은 따로 표시해 줘.’ 응답을 실제 파일과 대조해 보세요.

AGENTS.md에 적은 말은 파일 접근 권한 자체를 바꾸지는 않아요. 지침은 작업 방식을 안내하고, 실행 가능한 범위는 환경의 권한 설정도 함께 결정해요. 규칙과 실행 결과를 모두 확인하는 습관이 필요해요.