Codex와 Claude Code가 잘 따르는 디렉터리 컨벤션과 코드 스타일은 무엇일까요?

Codex와 Claude Code가 본질적으로 선호하는 특정 프로그래밍 언어, 프레임워크, 들여쓰기 폭, 폴더 모양이 따로 있는 것은 아닙니다. 두 도구가 비교적 안정적으로 따르기 쉬운 환경은 기존 저장소의 관례가 일관되고, 필요한 규칙의 적용 범위가 명확하며, 변경 결과를 자동으로 검증할 수 있는 환경입니다. 따라서 목표는 ‘AI가 좋아할 만한 구조’를 새로 발명하는 일이 아니라, 사람도 새 참여자도 이해할 수 있는 프로젝트 규약을 짧고 검증 가능하게 만드는 일입니다. openai.com↗code.claude.com↗

여기서 말하는 Codex와 Claude Code는 저장소 안의 파일을 읽고, 지침을 참고하며, 코드를 수정하거나 명령을 실행할 수 있는 코딩 에이전트 도구를 가리킵니다. 이런 도구는 코드 자체에서 많은 단서를 얻지만, 제품의 도메인 용어, 금지된 변경, 배포 전 확인 절차, 특정 폴더의 예외 규칙까지 항상 정확히 추론할 수는 없습니다. 그 빈자리를 저장소 구조, 지침 파일, 실행 가능한 검증 절차가 메웁니다. cdn.openai.com↗

왜 ‘정답 폴더 구조’보다 일관성이 중요한가요?

예를 들어 어떤 팀은 기능 단위로 src/payments/, src/users/를 나누고, 다른 팀은 계층 단위로 src/controllers/, src/services/, src/repositories/를 나눌 수 있습니다. 어느 한 방식이 Codex나 Claude Code에 자동으로 더 낫다고 단정할 근거는 없습니다. 중요한 것은 한 저장소 안에서 같은 종류의 책임이 비슷한 위치에 있고, 새 파일도 같은 기준으로 배치되며, 테스트와 import 방식도 기존 패턴을 따른다는 점입니다.

에이전트가 새 결제 기능을 추가할 때도 마찬가지입니다. 기존 결제 모듈에 요청 검증, 오류 처리, 데이터 접근, 테스트의 배치 방식이 보인다면 그 패턴을 이어 가는 편이 안전합니다. 반대로 새 기능마다 파일명과 계층을 새로 정하거나, 한 폴더에는 도메인 코드와 빌드 산출물·임시 파일이 뒤섞여 있다면 에이전트도 사람도 수정 위치와 영향 범위를 판단하기 어려워집니다.

따라서 디렉터리 컨벤션은 미관을 위한 규칙만이 아닙니다. 코드를 어디서 찾고, 무엇을 함께 바꾸며, 어느 검증을 실행해야 하는지를 드러내는 탐색 체계입니다. 이름과 경계가 안정적일수록 지침 파일에 장황한 설명을 반복할 필요도 줄어듭니다.

저장소의 기본 안내는 어디에 두어야 하나요?

Codex에서는 일반적으로 AGENTS.md가 프로젝트 지침 파일 역할을 합니다. 이 파일에 담긴 코드 스타일, 구조, 명명, 테스트 관련 지침은 파일이 있는 디렉터리와 그 하위 트리에 적용되며, 더 깊은 위치의 지침이 충돌할 때 더 구체적인 지침으로 작동할 수 있습니다. 개인 환경의 지침이나 AGENTS.override.md를 통한 재정의도 지원됩니다. openai.com↗

Claude Code에서는 CLAUDE.md 또는 .claude/CLAUDE.md를 프로젝트 메모리와 안내의 중심으로 사용할 수 있습니다. 상위 경로의 CLAUDE.md는 시작 시 문맥에 제공될 수 있고, 하위 디렉터리의 파일은 해당 경로의 파일을 다룰 때 필요한 방식으로 로드됩니다. 또한 개인별 설정을 위한 CLAUDE.local.md와 홈 디렉터리 수준의 파일도 사용할 수 있습니다. code.claude.com↗

두 파일은 이름이 비슷해 보여도 자동 탐색 방식까지 같은 것은 아닙니다. 특히 Claude Code가 AGENTS.md를 자동으로 공통 지침으로 읽는다고 가정하면 안 됩니다. 두 도구를 함께 쓸 때는 CLAUDE.md에서 @AGENTS.md로 공통 파일을 가져오거나, 팀의 운영 방식에 맞는 연결을 명시해야 합니다. code.claude.com↗

루트의 안내 파일은 저장소 전체를 장황하게 설명하는 백과사전보다 진입 지도에 가깝게 유지하는 편이 좋습니다. 새 작업자가 가장 먼저 알아야 할 명령, 최상위 구조, 핵심 불변 조건, 상세 문서의 위치를 제시하면 충분합니다. 긴 단일 지침 파일은 실제 코드와 작업 요구에 써야 할 문맥을 차지하고, 정작 중요한 제약을 눈에 띄지 않게 만들 수 있습니다. OpenAI의 Codex 관련 사례도 약 100줄 안팎의 짧은 지도형 파일과 별도 문서의 조합을 제시합니다. openai.com↗

AGENTS.md와 CLAUDE.md에는 무엇을 적어야 하나요?

좋은 지침은 이미 코드에서 분명하게 보이는 사실을 길게 복제하지 않습니다. 대신 코드만 보아서는 알기 어렵거나, 잘못 추론했을 때 비용이 큰 정보를 우선 기록합니다. Codex 관련 자료는 명명 규칙, 도메인 언어, 알려진 제약과 의존성, 빌드·테스트 절차 같은 정보를 AGENTS.md에 넣을 만한 내용으로 제시합니다. cdn.openai.com↗

루트 지침에는 다음 질문에 답하는 내용을 간결하게 담을 수 있습니다.

• 처음 변경 후 어떤 명령으로 포맷, 정적 검사, 타입 검사, 테스트를 실행하는가
• 소스, 테스트, 설계 문서, 운영 문서는 각각 어디에 있는가
• 기존 모듈을 확장할 때 따라야 할 파일명, import, 오류 처리, 테스트의 관례는 무엇인가
• 생성 파일, 빌드 산출물, 잠금 파일, 비밀값을 수정하거나 저장소에 포함해도 되는가
• 위험도가 높은 영역에서 계획 제시, 추가 검토, 특정 테스트가 필요한가
• 상세한 설계와 운영 절차는 어느 문서에서 찾는가

반면 “깨끗한 코드를 작성한다”, “보안을 중요하게 생각한다”, “최선을 다한다”처럼 해석이 넓은 문장은 실행 규칙이 되기 어렵습니다. 이를테면 “외부 입력은 기존 검증 모듈을 사용하고, 새 API 경로에는 해당 통합 테스트를 추가한다”처럼 관찰과 검증이 가능한 문장이 더 유용합니다. Claude Code의 권장 사항도 프로젝트 특유의 규칙을 구체적으로 쓰고, 길어진 지침은 정기적으로 검토·정리하는 방향을 강조합니다. code.claude.com↗

지침은 구현 세부를 모두 명령하는 문서가 아니라 판단 기준을 압축한 문서여야 합니다. 특정 라이브러리의 사용법, API 계약, 장애 대응 순서처럼 길고 변경 가능성이 큰 지식은 docs/ 아래의 적절한 문서로 옮기고, 루트 지침에서는 그 위치와 적용 조건을 알려 주는 편이 유지하기 쉽습니다.

하위 디렉터리별 규칙은 언제 필요한가요?

하위 규칙은 모든 폴더에 기계적으로 추가할 파일이 아닙니다. 루트의 공통 규칙만으로 충분한 곳에는 별도 파일이 오히려 탐색 부담과 충돌 가능성을 늘릴 수 있습니다. 일반 규칙에서 분명히 벗어나는 경계, 또는 실수의 영향이 큰 경계에만 두는 것이 적합합니다.

예를 들어 src/payments/에는 금액 계산 표현 방식, 외부 결제 공급자에 대한 모의 객체 사용 방식, 특정 통합 테스트 실행 명령을 적을 수 있습니다. infra/에는 변경 전 계획 제시, 적용 전 검사, 환경별 파일 수정 제한을 둘 수 있습니다. generated/에는 직접 수정 금지와 원본·생성 명령을 적는 방식이 가능합니다. 이때 규칙의 목적은 해당 폴더를 특별해 보이게 하는 것이 아니라, 그 영역의 실제 제약을 작업 문맥에 정확히 제공하는 것입니다.

Codex의 경우 하위 AGENTS.md는 그 디렉터리 아래에 적용되며, 더 깊은 파일이 더 구체적인 규칙을 제공할 수 있습니다. Claude Code도 여러 CLAUDE.md를 누적해 문맥으로 제공할 수 있으므로, 하위 파일은 상위 파일을 뒤집는 모호한 선언보다 해당 영역에만 필요한 구체 조건을 추가하는 방식이 안전합니다. openai.com↗code.claude.com↗

가령 루트에는 “변경한 패키지의 테스트를 실행한다”고 쓰고, 결제 폴더에는 “결제 계약이 바뀌면 단위 테스트와 통합 테스트를 모두 실행한다”고 쓰는 식입니다. 반대로 루트에서 “테스트를 반드시 실행한다”고 한 뒤 하위 폴더에서 “테스트는 하지 않는다”고 적으면 도구뿐 아니라 사람도 어느 규칙을 따라야 하는지 혼란스러워집니다.

Claude Code의 .claude/rules/는 어떻게 나누면 좋나요?

Claude Code에서는 항상 필요한 전역 규칙을 CLAUDE.md에 두고, 주제가 뚜렷하거나 경로에 따라 달라지는 규칙은 .claude/rules/ 아래의 작은 파일로 분리할 수 있습니다. 규칙 파일은 재귀적으로 구성할 수 있으며, 경로 조건을 이용해 특정 파일이나 영역에서만 필요한 규칙을 적용하는 구성이 가능합니다. code.claude.com↗

분리 기준은 ‘파일 수’보다 ‘함께 바뀌는 규칙의 응집도’입니다. 예를 들어 테스트 명령과 테스트 데이터의 원칙은 testing.md, import와 명명·포매팅의 예외는 code-style.md, 비밀값·외부 요청·권한 관련 제약은 security.md처럼 나눌 수 있습니다. 각 파일은 한 가지 주제를 다루고, 제목만 보아도 언제 읽어야 하는지 알 수 있어야 합니다.

이 방식의 장점은 필요 없는 지침을 항상 길게 읽지 않아도 된다는 데 있습니다. 예를 들어 문서만 편집하는 작업에 데이터베이스 마이그레이션 규칙 전체가 계속 섞이면 핵심 지시가 흐려질 수 있습니다. 다만 너무 잘게 나누면 규칙의 위치를 찾기 어려워집니다. 루트 CLAUDE.md에는 주요 규칙 묶음의 존재와 쓰임을 짧게 안내하고, 실제 내용은 주제 파일에 두는 균형이 필요합니다.

규칙을 분리한 뒤에는 같은 의무를 여러 파일에 복사하지 않는 편이 좋습니다. 복사본은 시간이 지나며 서로 다른 내용이 되기 쉽습니다. 공통 원칙은 한 곳에 두고, 경로별 파일에는 예외와 추가 조건만 기록하면 충돌을 줄일 수 있습니다.

코드 스타일은 어떤 방식으로 명시해야 하나요?

‘AI 친화적 코드 스타일’은 탭 또는 공백, 함수형 또는 객체지향처럼 보편적인 한 선택을 뜻하지 않습니다. 더 중요한 기준은 해당 저장소의 로컬 관례를 재현할 수 있는가입니다. 새 모듈도 기존 모듈과 같은 파일명 패턴, export 방식, import 순서, 오류 처리 경로, 테스트 구조를 따른다면 리뷰와 유지보수가 쉬워집니다.

프로젝트가 언어의 일반 관례와 다르게 선택한 부분은 반드시 명시할 가치가 큽니다. Claude Code 문서는 예시로 ES 모듈 사용이나 named import 구조 분해처럼 프로젝트에 특유한 코드 스타일을 들고 있습니다. 즉, 언어의 기본 규칙을 모두 다시 쓰기보다 “우리 프로젝트에서는 기본값과 다르게 무엇을 하는가”를 적는 편이 효율적입니다. code.claude.com↗

다음 표는 스타일 지침을 판단하는 간단한 기준입니다.

포매터, 린터, 타입 검사기는 스타일을 문장으로 강요하는 대신 기계적으로 판정할 수 있게 해 줍니다. 그러므로 지침에는 “예쁘게 포맷한다”보다 실제 실행 명령과 실패했을 때의 처리 기대를 적는 편이 낫습니다. Claude Code의 모범 사례도 명확한 프로젝트 지침과 검증 가능한 개발 흐름을 권장합니다. code.claude.com↗

디렉터리 구조는 어떤 모습에서 시작할 수 있나요?

다음은 Codex와 Claude Code를 함께 고려할 때 사용할 수 있는 예시입니다. 이것은 필수 표준이 아니라, 공통 지침·상세 문서·영역별 예외를 구분하는 한 가지 출발점입니다.

repo/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── ARCHITECTURE.md
├── docs/
│   ├── design-docs/
│   ├── product-specs/
│   ├── runbooks/
│   └── generated/
├── src/
│   ├── feature-a/
│   └── feature-b/
├── tests/
└── .claude/
    ├── rules/
    │   ├── testing.md
    │   ├── code-style.md
    │   └── security.md
    └── settings.json

여기서 README.md는 사람이 저장소를 시작할 때 필요한 정보를, ARCHITECTURE.md는 시스템의 주요 경계와 구조를, docs/는 길고 세부적인 설계·제품·운영 지식을 담을 수 있습니다. src/와 tests/의 실제 모양은 프로젝트의 기존 구조를 따르는 것이 우선입니다. .claude/rules/는 Claude Code에 특화된 주제별 또는 경로별 규칙을 둘 수 있는 위치입니다. code.claude.com↗

루트에 파일이 많아지는 것이 걱정된다면, 핵심은 파일 이름의 개수가 아니라 역할의 구분입니다. 한 파일이 프로젝트 소개, 시스템 설계, 운영 대응, 세부 API 규약, 스타일 규칙을 모두 떠안으면 어느 정보가 현재 작업에 필수인지 알기 어려워집니다. 반대로 짧은 루트 안내가 필요한 상세 문서를 가리키면, 작업자는 필요한 깊이까지만 탐색할 수 있습니다.

기능별 폴더 안에 지침 파일을 놓는 경우에도 같은 원칙이 적용됩니다. 해당 기능에 전용 규칙이 없다면 추가하지 않고, 민감한 데이터 처리나 자동 생성 과정처럼 뚜렷한 이유가 있을 때만 둡니다. 빈번한 규칙 파일 증식은 구조를 설명하는 대신 구조 자체를 복잡하게 만들 수 있습니다.

두 도구를 함께 쓸 때 규칙 중복은 어떻게 줄이나요?

공통 개발 규약의 기준 파일을 AGENTS.md로 두고, 루트 CLAUDE.md에서 이를 가져온 다음 Claude Code에만 필요한 내용을 덧붙이는 방식이 가능합니다. 예시는 다음과 같습니다.

@AGENTS.md

## Claude Code 전용
- `src/payments/` 변경은 계획을 먼저 제시합니다.
- `.claude/rules/`의 경로별 규칙을 따릅니다.

이 구성은 테스트 명령, 공통 명명 규칙, 생성 파일 원칙을 두 파일에 반복해서 유지할 필요를 줄입니다. 동시에 Claude Code의 전용 규칙이나 .claude/rules/ 기반 구성도 유지할 수 있습니다. 단, 앞서 본 것처럼 Claude Code는 AGENTS.md를 자동으로 공통 지침으로 읽는 방식이 아니므로, 가져오기 또는 이에 준하는 연결을 실제로 설정해야 합니다. code.claude.com↗

공통 파일을 어디에 둘지는 팀의 도구 사용 비중과 기존 저장소 관례에 따라 달라질 수 있습니다. Codex를 주로 쓴다면 AGENTS.md를 기준으로 삼기 쉽고, Claude Code의 규칙 체계를 중심으로 운영한다면 CLAUDE.md를 기준으로 둘 수도 있습니다. 어느 선택이든 한 규칙의 권위 있는 원본을 정하고, 다른 파일에는 연결 또는 도구별 추가 사항만 두는 편이 핵심입니다.

개인별 선호는 팀 규약과 분리하는 것이 좋습니다. 개인 환경의 명령 별칭, 로컬 도구 선택, 개인적인 작업 방식은 개인용 재정의 파일이 더 적합할 수 있습니다. 반면 저장소를 복제한 사람이 동일하게 알아야 할 테스트 절차, 보안 제약, 코드 구조는 버전 관리되는 프로젝트 지침에 남겨야 합니다. Codex와 Claude Code 모두 프로젝트 수준과 개인 수준의 지침 구성을 지원합니다. openai.com↗code.claude.com↗

검증 명령은 왜 지침의 중심이 되어야 하나요?

코딩 에이전트의 제안이나 변경은 그럴듯해 보여도 정확성, 호환성, 보안성을 자동으로 보장하지 않습니다. Codex 관련 안내도 결과물의 사람 검토와 검증이 여전히 필요하다고 설명합니다. openai.com↗

그래서 좋은 저장소 지침은 ‘어떻게 코딩할지’뿐 아니라 ‘어떻게 확인할지’를 알려 줍니다. 가능한 범위에서 포맷, 린트, 타입 검사, 단위 테스트, 통합 테스트, 빌드 명령을 실제 실행 가능한 형태로 정리합니다. 모든 작업에 전체 검증을 요구하기 어려운 대형 저장소라면, 변경 위치별로 최소 검증과 전체 검증의 조건을 나누어 적을 수 있습니다.

예를 들어 문서 수정에는 링크 검사나 문서 빌드만 필요할 수 있고, 공개 API 계약 변경에는 단위 테스트와 통합 테스트가 함께 필요할 수 있습니다. 데이터베이스 스키마나 인프라 설정처럼 되돌리기 어려운 변경은 추가 검토 단계가 필요할 수 있습니다. 중요한 것은 도구가 위험도를 마법처럼 판별한다고 기대하는 것이 아니라, 팀이 이미 알고 있는 검증 경로를 저장소에 명시하는 일입니다.

생성 코드와 빌드 산출물도 검증 관점에서 분명히 구분해야 합니다. 직접 수정하면 안 되는 파일이라면 원본 위치와 생성 절차를 적고, 수정이 허용되는 산출물이라면 어떤 명령을 거쳐 갱신하는지 밝혀야 합니다. 비밀값과 환경별 개인 설정도 저장소에 넣지 않는 원칙, 예제 파일의 위치, 필요한 검증 절차를 명확히 해 두는 편이 안전합니다.

흔한 오해와 실패 패턴은 무엇인가요?

첫 번째 오해는 “지침을 많이 쓰면 더 잘 따른다”는 생각입니다. 실제로 긴 문서는 핵심 규칙을 묻히게 할 수 있습니다. 지침이 길어졌다면 중복된 설명, 이미 자동화된 규칙, 더 이상 유효하지 않은 예외를 제거하고, 상세 지식은 별도 문서로 옮기는 편이 낫습니다. code.claude.com↗openai.com↗

두 번째는 “모든 폴더에 지침 파일을 둬야 한다”는 생각입니다. 하위 지침은 특별한 제약이 있는 곳에만 유용합니다. 구체성이 없는 하위 파일은 단순히 읽어야 할 파일을 늘리고, 상위 규칙과의 관계를 불명확하게 만들 수 있습니다.

세 번째는 “스타일 규칙만 맞추면 된다”는 생각입니다. 형식이 일관되어도 테스트가 실행되지 않거나, 도메인 규칙을 위반하거나, 생성 파일을 직접 수정했다면 좋은 변경이라고 보기 어렵습니다. 스타일 자동화와 테스트·검토 절차는 서로 대체하는 관계가 아니라 함께 작동하는 안전장치입니다.

네 번째는 “도구가 문서의 모순을 알아서 해결한다”는 생각입니다. 상위와 하위 지침, 공통과 도구 전용 지침이 충돌하면 결과를 예측하기 어려워집니다. 같은 규칙은 한 곳에 두고, 하위 규칙은 적용 대상과 추가 조건을 명확히 적는 편이 좋습니다. Claude Code의 메모리 구성도 계층적 지침을 다루므로, 규칙 간 충돌을 만들지 않는 설계가 중요합니다. code.claude.com↗

마지막으로, 지침 파일을 품질 보증서로 보는 태도도 피해야 합니다. 지침은 에이전트와 사람의 판단을 돕는 문맥이지, 생성된 코드의 정확성·보안성·테스트 통과를 보장하는 장치는 아닙니다. 변경 내용의 검토와 필요한 검증은 계속 필요합니다. openai.com↗

우리 저장소에는 무엇부터 적용하면 될까요?

처음부터 폴더 구조를 전면 개편할 필요는 없습니다. 현재 저장소에서 반복적으로 발생하는 혼란을 기준으로 작은 개선부터 시작하는 편이 현실적입니다. 예를 들어 새 참여자가 테스트 명령을 찾지 못한다면 루트 지침에 명령을 추가합니다. 결제 모듈에서 매번 같은 실수가 난다면 해당 경로에만 구체 규칙을 둡니다. 설계 문서가 코드와 섞여 탐색이 어렵다면 docs/ 안에서 문서 종류를 먼저 구분할 수 있습니다.

점검 순서는 다음처럼 잡을 수 있습니다.

1. 현재 코드베이스에서 실제로 반복되는 파일 배치, 명명, 테스트 관례를 확인합니다.
2. 포매터·린터·타입 검사·테스트의 실행 명령과 실패 조건을 정리합니다.
3. 코드만으로 알기 어려운 도메인 제약, 수정 금지 영역, 생성 절차를 추립니다.
4. 루트의 AGENTS.md 또는 CLAUDE.md에 가장 중요한 내용만 짧게 작성합니다.
5. 일반 규칙으로 설명되지 않는 민감 영역에만 하위 지침 또는 경로별 규칙을 추가합니다.
6. 공통 규칙의 원본을 하나 정하고, 다른 도구용 파일에는 연결과 전용 규칙만 남깁니다.
7. 실제 작업에서 지침이 도움이 되었는지, 불필요하거나 모순된 문장이 없는지 주기적으로 검토합니다.

이 과정에서 ‘도구가 이해하기 좋은가’와 ‘사람이 유지하기 좋은가’를 대립시키지 않아도 됩니다. 짧고 정확한 문서, 예측 가능한 모듈 경계, 자동 실행 가능한 검증은 두 대상 모두에게 도움이 됩니다. 반대로 사람에게도 설명하기 어려운 구조를 지침 파일만으로 보완하려 하면 문서가 비대해질 가능성이 큽니다.

결론: 어떤 컨벤션을 선택해야 하나요?

Codex와 Claude Code에 적합한 디렉터리 컨벤션과 코드 스타일의 핵심은 특정 유행 구조를 채택하는 데 있지 않습니다. 기존 코드베이스의 관례를 일관되게 유지하고, 루트에는 짧은 안내를 두며, 상세 지식은 적절한 문서로 분리하고, 필요한 곳에만 범위가 좁은 규칙을 더하는 방식이 실용적입니다.

Codex에는 AGENTS.md, Claude Code에는 CLAUDE.md와 필요에 따른 .claude/rules/를 활용할 수 있습니다. 두 도구를 병행한다면 공통 규칙의 원본을 하나로 정하고 Claude Code에서 공통 파일을 명시적으로 연결하면 중복을 줄일 수 있습니다. 무엇보다 지침을 포매터·린터·타입 검사·테스트·사람의 검토와 결합해야 합니다. 제품의 지침 해석 방식은 버전에 따라 달라질 수 있으므로, 실제 운영 중인 도구의 공식 문서를 확인하면서 규칙을 작고 명확하게 유지하는 것이 바람직합니다. openai.com↗code.claude.com↗