본 글은 AI를 활용해 초안을 작성하고, 작성자가 직접 검토·수정·보완하였습니다.
Claude Code나 Codex 같은 Coding Agent를 처음 사용할 때는 대부분 채팅창에 직접 요청하는 방식으로 시작합니다.
“이 기능을 구현해주세요.”
“이 코드가 어떤 역할을 하는지 설명해주세요.”
그런데 실제 개발 업무에서 반복해서 사용하다 보면 매번 비슷한 내용을 Agent에게 알려주고 있다는 것을 발견하게 됩니다.
이 프로젝트는 Kotlin + Spring Boot를 사용합니다.
Controller에는 비즈니스 로직을 작성하지 않습니다.
Controller는 Application Service를 호출합니다.
JPA Entity를 API Response로 직접 반환하지 않습니다.
...
Coding Agent를 가끔 사용한다면 매번 알려줘도 큰 문제는 없습니다.
하지만 개발 환경의 일부로 사용하기 시작하면 이런 정보를 매번 Prompt에 넣는 방식은 비효율적입니다.
어떤 정보는 프로젝트에서 작업하는 동안 항상 알아야 하고, 어떤 정보는 특정 코드 영역에서만 필요합니다.
코드 분석이나 리뷰처럼 특정 작업에서만 사용하는 절차도 있습니다.
외부 시스템의 데이터가 필요할 수도 있고, 복잡한 작업은 별도의 Agent에게 나누어 맡길 수도 있습니다.
이를 위해 Claude Code와 Codex에서는 다음과 같은 설정을 제공합니다.
AGENTS.md
CLAUDE.md
Rules
SKILL.md
Subagent
MCP이 글에서는 각각 어떤 역할을 하는지 살펴보고, 마지막에는 Claude Code와 Codex를 함께 사용할 때 설정을 어떻게 구성하면 좋은지 정리해보겠습니다.
먼저 큰 그림부터 살펴보겠습니다
각 기능의 역할부터 간단히 정리하면 다음과 같습니다.
| 구분 | Claude Code | Codex | 역할 |
| 프로젝트 기본 지침 | CLAUDE.md | AGENTS.md | 프로젝트에서 항상 알아야 하는 규칙 |
| 영역별 개발 지침 | .claude/rules/*.md + paths | 디렉터리별 AGENTS.md | 특정 코드 영역의 규칙 |
| 작업 Workflow | SKILL.md | SKILL.md | 특정 작업을 수행하는 방법 |
| 전문 작업자 | Subagent | Subagent / Custom Agent | 별도 Context에서 특정 업무 수행 |
| 외부 시스템 연동 | MCP | MCP | 외부 Tool과 데이터 연결 |
| 명령 실행 정책 | Permissions | .codex/rules/*.rules | 명령 실행 허용·승인·차단 |
조금 단순화하면 다음처럼 볼 수 있습니다.
AGENTS.md / CLAUDE.md = Policy
Rules = Scoped Policy
SKILL.md = Workflow
Subagent = Worker
MCP = Integration이 기능들은 서로 대체하는 관계가 아닙니다.
CLAUDE.md와 AGENTS.md가 프로젝트의 기본적인 행동 원칙을 알려준다면, Skill은 특정 작업을 수행하는 절차를 알려줍니다. Subagent는 작업을 별도의 작업자에게 분리하고, MCP는 Agent가 외부 시스템을 사용할 수 있도록 기능을 확장합니다.
설정은 어디에 두느냐에 따라 범위가 달라집니다
각 기능을 보기 전에 먼저 Scope, 즉 설정의 적용 범위를 알아둘 필요가 있습니다.
크게 다음과 같이 생각할 수 있습니다.
사용자 전역
→ 내가 사용하는 여러 프로젝트에서 공통으로 적용
프로젝트
→ 현재 프로젝트에서 적용
개인 프로젝트
→ 현재 프로젝트에서 나에게만 적용
예를 들어 다음은 특정 프로젝트와 상관없는 개인적인 작업 방식입니다.
코드를 설명할 때 호출 흐름까지 함께 설명합니다.
이런 내용은 사용자 전역 설정에 적합합니다.
반면 아래 내용은 특정 프로젝트의 Architecture 규칙입니다.
Controller는 Application Service만 호출합니다.
이런 내용은 프로젝트 설정에 두는 것이 적절합니다.
~는 현재 사용자의 Home Directory입니다
설정 경로를 보다 보면 다음 표현이 자주 등장합니다.
~/.claude/
~/.codex/
~/.agents/여기서 ~는 현재 OS 사용자의 Home Directory를 의미합니다.
예를 들어 macOS의 Home Directory가 다음과 같다면,
/Users/jhk
다음 경로는
~/.codex/AGENTS.md
실제로는 다음 파일을 의미합니다.
/Users/jhk/.codex/AGENTS.md
따라서 ~/.claude, ~/.codex, ~/.agents 아래의 설정은 현재 사용자의 전역 설정으로 이해하면 됩니다.
Claude Code와 Codex의 설정 Scope
먼저 주요 경로를 한 번에 비교해보겠습니다.
Claude Code
| 기능 | 사용자 전역 | 프로젝트 | 개인 프로젝트 |
| 기본 지침 | ~/.claude/CLAUDE.md | CLAUDE.md 또는 .claude/CLAUDE.md | CLAUDE.local.md |
| 설정 | ~/.claude/settings.json | .claude/settings.json | .claude/settings.local.json |
| Rules | ~/.claude/rules/ | .claude/rules/ | - |
| Skills | ~/.claude/skills/ | .claude/skills/ | - |
| Subagents | ~/.claude/agents/ | .claude/agents/ | - |
| MCP | User Scope | .mcp.json | Local Scope |
Claude Code는 사용자 전역, 프로젝트, 개인 프로젝트 Scope를 비교적 명확하게 구분합니다.
예를 들어 모든 프로젝트에서 공통으로 사용할 작업 방식은 다음 위치에 둘 수 있습니다.
~/.claude/CLAUDE.md
특정 프로젝트의 규칙은 다음처럼 프로젝트 안에 둡니다.
my-project/
└── CLAUDE.md
현재 프로젝트에서 나에게만 필요한 지침은 CLAUDE.local.md로 분리할 수 있습니다.
Codex
| 기능 | 사용자 전역 | 프로젝트 |
| 기본 지침 | ~/.codex/AGENTS.md | AGENTS.md |
| 설정 | ~/.codex/config.toml | .codex/config.toml |
| Skills | ~/.agents/skills/ | .agents/skills/ |
| Custom Agents | ~/.codex/agents/ | .codex/agents/ |
| Command Rules | ~/.codex/rules/ | .codex/rules/ |
| MCP | ~/.codex/config.toml | .codex/config.toml |
Codex는 사용자 전역 설정과 프로젝트 설정을 중심으로 구성됩니다.
여기서 한 가지 특이한 점이 있습니다.
다른 Codex 설정은 대부분 .codex 아래에 있는데 Skills만 .agents/skills를 사용합니다.
오타가 아닙니다.
왜 Skill 경로만 다를까요?
Codex의 다음 설정은 Codex라는 제품 자체의 설정입니다.
.codex/config.toml
.codex/agents/
.codex/rules/
반면 Skill은 Codex만의 독자적인 포맷이 아니라 Agent Skills라는 Open Format을 기반으로 합니다.
Skill의 기본 구조는 다음과 같습니다.
code-analysis/
├── SKILL.md
├── scripts/
├── references/
└── assets/Agent Skills가 표준화하는 핵심은 Skill의 형식입니다. SKILL.md에 어떤 Metadata와 Instruction을 작성하는지, Script나 Reference 같은 Resource를 어떻게 함께 구성하는지를 정의합니다.
저장 경로 자체는 강제하지 않습니다.
다만 여러 Coding Agent가 동일한 Skill을 공유하기 위한 경로로 다음 Convention이 사용되고 있습니다.
.agents/skills/
~/.agents/skills/
대표적으로 다음 Coding Agent들이 .agents/skills를 지원합니다.
Codex
Cursor
GitHub Copilot CLI
Gemini CLI
Windsurf
따라서 Codex에서는 다음처럼 구분해서 이해할 수 있습니다.
.codex/
→ Codex 자체 설정
.agents/skills/
→ Agent 간 재사용할 수 있는 Skill그런데 Claude Code는 왜 .claude/skills를 사용할까요?
Claude Code 역시 Agent Skills 형식을 지원하지만 기본 Skill 경로는 다음과 같습니다.
~/.claude/skills/
.claude/skills/
즉 같은 Agent Skills 형식을 사용하더라도 Skill을 발견하는 위치는 제품마다 다릅니다.
공통
→ SKILL.md 기반 Agent Skills 형식
Claude Code
→ .claude/skills/
Codex
→ .agents/skills/Anthropic이 왜 .agents/skills 대신 .claude/skills를 기본 경로로 선택했는지에 대한 별도의 설계 이유는 공식적으로 설명되어 있지 않습니다.
확실한 것은 Skill의 형식은 공통이지만 Discovery Path는 제품별 구현에 따라 다르다는 점입니다.
이 차이는 뒤에서 두 Coding Agent가 같은 Skill을 공유할 때 다시 활용할 수 있습니다.
프로젝트 기본 지침: CLAUDE.md와 AGENTS.md
새로운 개발자가 팀에 합류했다고 생각해보겠습니다.
프로젝트를 전달하고 “기능 하나 추가해주세요”라고 하면 바로 일을 시작하기 어렵습니다.
프로젝트 구조와 테스트 방법, 팀에서 지키는 Architecture와 Convention을 먼저 알아야 합니다.
Coding Agent도 마찬가지입니다.
예를 들어 다음 두 구조는 모두 기술적으로 가능합니다.
Controller
↓
RepositoryController
↓
Application Service
↓
Repository하지만 우리 프로젝트에서는 반드시 Application Service를 거쳐야 할 수 있습니다.
이런 프로젝트 지침을 Claude Code에서는 CLAUDE.md, Codex에서는 AGENTS.md에 작성합니다.
예를 들면 다음과 같습니다.
# Architecture
이 프로젝트는 Kotlin + Spring Boot를 사용합니다.
Controller에는 비즈니스 로직을 작성하지 않습니다.
Controller는 Application Service를 호출합니다.
JPA Entity를 API Response로 직접 반환하지 않습니다.
# Testing
코드를 변경했다면 관련 테스트를 실행합니다.
./gradlew test쉽게 말하면 Coding Agent를 위한 프로젝트 개발 가이드입니다.
AGENTS.md는 Codex 전용 파일이 아닙니다
Codex가 AGENTS.md를 직접 사용하는 것은 맞지만 AGENTS.md 자체는 Codex 전용 포맷이 아닙니다.
AGENTS.md는 여러 Coding Agent에게 프로젝트 지침을 전달하기 위한 Open Format입니다.
흔히 Agent를 위한 README라고 설명합니다.
대표적으로 다음 Coding Agent들이 AGENTS.md를 지원합니다.
OpenAI Codex
Cursor
Gemini CLI
Google Jules
GitHub Copilot Coding Agent
Windsurf
JetBrains Junie이외에도 여러 Coding Agent와 개발 도구가 AGENTS.md 생태계를 지원하고 있습니다.
즉 다음처럼 이해할 수 있습니다.
AGENTS.md
→ 특정 Coding Agent 전용 설정이 아니라
여러 Agent가 공유할 수 있는 프로젝트 지침 포맷README와 비교하면 역할도 조금 다릅니다.
README.md
→ 사람이 프로젝트를 이해하기 위한 문서
AGENTS.md
→ Agent가 프로젝트에서 작업하기 위한 지침README에 이미 잘 작성된 설치 방법이나 Architecture 문서가 있다면 AGENTS.md에 다시 복사할 필요는 없습니다.
프로젝트 실행 방법은 README.md를 참고합니다.
상세 Architecture는 docs/architecture.md를 참고합니다.처럼 기존 문서를 연결하면 중복 관리도 줄일 수 있습니다.
다만 모든 Coding Agent가 AGENTS.md를 직접 읽는 것은 아닙니다.
대표적인 예가 Claude Code입니다.
Claude Code는 기본적으로 CLAUDE.md를 사용합니다.
따라서 Claude Code와 Codex에서 프로젝트 지침을 공유하고 싶다면 CLAUDE.md에서 AGENTS.md를 Import할 수 있습니다.
@AGENTS.md
## Claude Code
Claude Code에서만 필요한 추가 지침을 작성합니다.이렇게 구성하면 공통 프로젝트 규칙은 AGENTS.md 하나에서 관리하면서 AGENTS.md를 지원하는 다른 Coding Agent에서도 그대로 활용할 수 있습니다.
AGENTS.md
↗ ↑ ↖
Codex Cursor Gemini CLI
│
│ import
↓
CLAUDE.md
│
Claude Code영역별 개발 지침은 Claude와 Codex가 다릅니다
프로젝트 규모가 커지면 모든 규칙을 하나의 CLAUDE.md나 AGENTS.md에 넣는 것도 부담이 됩니다.
예를 들어 다음과 같은 Monorepo가 있다고 하겠습니다.
commerce/
├── backend/
└── frontend/Backend에는 JPA 규칙이 필요하고 Frontend에는 React 규칙이 필요합니다.
Claude Code와 Codex는 이런 영역별 지침을 서로 다른 방식으로 관리합니다.
Claude Code: .claude/rules/
Claude Code에서는 .claude/rules/에 규칙을 주제별로 나눌 수 있습니다.
.claude/
└── rules/
├── api.md
├── jpa.md
└── testing.md
특히 paths를 이용하면 특정 파일에만 Rule을 적용할 수 있습니다.
---
paths:
- "src/api/**/*.kt"
---
# API Rules
- 요청 값에 Validation을 적용합니다.
- 공통 Error Response 형식을 사용합니다.
- Controller에는 비즈니스 로직을 작성하지 않습니다.
즉 Claude Code는 파일 경로를 기준으로 개발 규칙의 Scope를 지정할 수 있습니다.
Codex: 디렉터리별 AGENTS.md
Codex에는 Claude의 Path-scoped Rules와 직접 대응하는 개발 Rules 기능이 없습니다.
대신 프로젝트의 여러 디렉터리에 AGENTS.md를 둘 수 있습니다.
commerce/
├── AGENTS.md
│
├── backend/
│ └── AGENTS.md
│
└── frontend/
└── AGENTS.md
Root AGENTS.md에는 공통 규칙을 작성합니다.
# Project Rules
- 변경 후 관련 테스트를 실행합니다.
- 기존 Architecture를 유지합니다.
backend/AGENTS.md에는 Backend 전용 규칙을 작성할 수 있습니다.
# Backend Rules
- Kotlin + Spring Boot를 사용합니다.
- Controller에서 Entity를 직접 반환하지 않습니다.
- JPA 변경 시 Transaction Boundary를 확인합니다.여기서 “하위 AGENTS.md”라는 별도의 파일 종류가 있는 것은 아닙니다.
그냥 하위 디렉터리에 위치한 일반 AGENTS.md입니다.
Codex는 사용자 전역 지침을 읽은 뒤 프로젝트 Root부터 현재 작업 디렉터리까지의 AGENTS.md를 순서대로 읽습니다.
예를 들어 다음처럼 Backend 디렉터리에서 Codex를 실행하면,
cd commerce/backend
codex
개념적으로 다음 지침이 사용됩니다.
~/.codex/AGENTS.md
↓
commerce/AGENTS.md
↓
commerce/backend/AGENTS.md
따라서 두 제품의 차이를 다음처럼 이해할 수 있습니다.
Claude Code
→ 어떤 파일을 작업하는가?
→ paths 기반 Rule
Codex
→ 어느 디렉터리에서 작업하는가?
→ AGENTS.md 계층Codex의 AGENTS.override.md
Codex에는 AGENTS.override.md도 있습니다.
같은 디렉터리에 다음 두 파일이 모두 존재한다면,
AGENTS.md
AGENTS.override.md
Codex는 해당 디렉터리에서 AGENTS.override.md를 사용합니다.
예를 들어 Legacy 영역에 완전히 다른 규칙을 적용하고 싶다면 다음처럼 구성할 수 있습니다.
project/
├── AGENTS.md
│
└── legacy/
└── AGENTS.override.md즉 해당 디렉터리에서 기본 AGENTS.md 대신 다른 지침을 사용하고 싶을 때 사용할 수 있습니다.
Codex의 .codex/rules/는 다른 기능입니다
여기서 특히 주의해야 할 부분이 있습니다.
Codex에도 다음 경로가 있습니다.
~/.codex/rules/
.codex/rules/하지만 이것은 Claude Code의 .claude/rules/와 같은 개발 지침 기능이 아닙니다.
Codex Rules는 Sandbox 밖에서 명령을 실행할 때 허용할지, 사용자에게 확인할지, 차단할지를 제어하는 실행 정책입니다.
예를 들면 다음과 같습니다.
prefix_rule(
pattern = ["gh", "pr", "view"],
decision = "prompt",
justification = "PR 조회는 실행 전에 확인합니다.",
)정리하면 이름만 같을 뿐 역할은 다릅니다.
| 구분 | Claude Code Rules | Codex Rules |
| 목적 | 영역별 개발 지침 | 명령 실행 정책 |
| 프로젝트 위치 | .claude/rules/ | .codex/rules/ |
| 형식 | Markdown | .rules |
| Path 기반 개발 규칙 | 지원 | 해당 기능 아님 |
| 명령 승인/차단 | Permissions가 담당 | Rules가 담당 |
Skill은 특정 작업을 수행하는 방법입니다
프로젝트의 Policy와 특정 작업의 절차는 분리하는 것이 좋습니다.
예를 들어 다음은 프로젝트 규칙입니다.
Controller에서는 Entity를 직접 반환하지 않습니다.
반면 다음은 코드 분석이라는 작업의 수행 방법입니다.
Caller
→ Callee
→ Transaction
→ Query
→ Concurrency
→ Test
이런 반복적인 Workflow를 정의하는 것이 Skill입니다.
code-analysis/
└── SKILL.md---
name: code-analysis
description: 코드의 실행 흐름과 관련 구조를 분석할 때 사용합니다.
---
# Instructions
1. 대상 파일을 확인합니다.
2. Caller와 Callee를 확인합니다.
3. Transaction Boundary를 확인합니다.
4. Persistence 접근을 확인합니다.
5. 동시성 문제를 확인합니다.
6. 관련 Test를 확인합니다.
따라서 다음처럼 구분하면 됩니다.
| 구분 | 질문 |
| CLAUDE.md / AGENTS.md | 프로젝트에서 항상 알아야 할 것은 무엇인가? |
| Rules / 영역별 지침 | 이 코드 영역에서 지켜야 할 것은 무엇인가? |
| Skill | 이 작업을 어떤 절차로 수행할 것인가? |
Skill과 Subagent는 무엇이 다를까요?
둘의 차이는 사람에게 비유하면 이해하기 쉽습니다.
Skill은 일을 하는 방법이고, Subagent는 그 일을 맡는 작업자입니다.
예를 들어 code-review Skill은 다음을 정의합니다.
어떤 순서로 코드를 읽을 것인가?
어떤 문제를 우선 확인할 것인가?
어떤 형태로 결과를 작성할 것인가?반면 code-reviewer Subagent는 코드 리뷰라는 역할을 맡은 별도의 작업자입니다.
큰 코드베이스를 분석할 때 Main Agent 하나가 코드 탐색, 테스트 분석, 로그 확인까지 모두 수행하면 Main Context에 많은 중간 정보가 쌓일 수 있습니다.
이런 작업을 다음처럼 분리할 수 있습니다.
Main Agent
│
├── Explorer
│ → 코드 구조 조사
│
├── Test Reviewer
│ → 테스트 분석
│
└── Concurrency Reviewer
→ 동시성 분석
Claude Code의 Custom Subagent는 다음 위치에 둘 수 있습니다.
~/.claude/agents/
.claude/agents/
Codex의 Custom Agent는 다음 위치를 사용합니다.
~/.codex/agents/
.codex/agents/Claude Code는 Markdown, Codex는 TOML 기반으로 정의합니다.
즉 역할은 비슷하지만 설정 Format까지 동일한 것은 아닙니다.
MCP는 Agent가 외부 시스템을 사용할 수 있게 합니다
MCP는 Model Context Protocol의 약자입니다.
앞의 기능들과 관계를 정리하면 다음과 같습니다.
AGENTS.md / CLAUDE.md
→ 어떻게 행동해야 하는가?
Rules
→ 특정 영역에서 어떤 규칙을 지켜야 하는가?
Skill
→ 특정 작업을 어떻게 수행해야 하는가?
Subagent
→ 누가 그 작업을 담당하는가?
MCP
→ 어떤 외부 기능과 데이터를 사용할 수 있는가?
MCP를 사용하면 Coding Agent에서 GitHub, Notion, Jira, Sentry, Database 같은 외부 시스템을 연결할 수 있습니다.
Coding Agent
│
│ MCP
▼
MCP Server
│
▼
External SystemSkill과 MCP 역시 대체 관계가 아닙니다.
예를 들어 GitHub Pull Request를 리뷰한다면 MCP는 PR과 변경 파일을 가져오는 Capability를 제공하고, Code Review Skill은 가져온 데이터를 어떤 절차로 분석할지 정의하는 Workflow가 됩니다.
GitHub MCP
↓
PR 데이터 조회
↓
Code Review Skill
↓
정해진 절차로 분석MCP 설정 위치
MCP는 Claude Code와 Codex 모두 지원하지만, 설정을 저장하는 방식은 다릅니다.
Claude Code
Claude Code의 MCP는 User, Project, Local 세 가지 Scope로 나뉩니다.
| Scope | 저장 위치 | 적용 범위 |
| User | ~/.claude.json | 모든 프로젝트에서 사용 |
| Project | .mcp.json | 현재 프로젝트에서 사용, 팀 공유 가능 |
| Local | ~/.claude.json | 특정 프로젝트에서 나만 사용 |
User와 Local은 같은 ~/.claude.json에 저장되지만 적용 범위가 다릅니다.
예를 들어 모든 프로젝트에서 GitHub MCP를 사용하고, order-service 프로젝트에서만 개인용 DB MCP를 사용한다고 하겠습니다.
{
"mcpServers": {
"github": {
"type": "stdio",
"command": "github-mcp-server"
}
},
"projects": {
"/Users/jhk/projects/order-service": {
"mcpServers": {
"order-db": {
"type": "stdio",
"command": "order-db-mcp"
}
}
}
}
}
여기서 최상위 mcpServers는 User Scope입니다.
github
→ 어떤 프로젝트에서 Claude Code를 실행해도 사용
반면 projects 아래에 저장된 MCP는 Local Scope입니다.
order-db
→ /Users/jhk/projects/order-service 에서만 사용
Project Scope는 별도의 .mcp.json 파일을 사용합니다.
order-service/
├── CLAUDE.md
├── .mcp.json
└── src/
예를 들어 팀 전체가 사용하는 MCP라면 다음처럼 작성할 수 있습니다.
{
"mcpServers": {
"internal-api": {
"type": "stdio",
"command": "internal-api-mcp"
}
}
}
.mcp.json은 프로젝트에 포함해 팀과 공유할 수 있습니다.
결국 order-service에서 Claude Code를 실행했을 때 다음 세 설정이 함께 적용될 수 있습니다.
User
~/.claude.json
└── github
→ 모든 프로젝트에서 사용
Local
~/.claude.json
└── order-service
└── order-db
→ 이 프로젝트에서 나만 사용
Project
order-service/.mcp.json
└── internal-api
→ 이 프로젝트에서 팀과 공유
즉 Claude Code의 MCP Scope는 다음처럼 기억하면 됩니다.
User
→ 어디서든 내가 사용하는 MCP
Local
→ 특정 프로젝트에서 나만 사용하는 MCP
Project
→ 특정 프로젝트에서 팀과 공유하는 MCPCodex
Codex는 MCP를 별도의 .mcp.json 파일로 분리하지 않고 config.toml에서 관리합니다.
사용자 전역
~/.codex/config.toml
프로젝트
.codex/config.toml예를 들어 다음처럼 MCP Server를 등록할 수 있습니다.
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
따라서 두 제품의 MCP 설정 위치를 정리하면 다음과 같습니다.
| 구분 | Claude | CodeCodex |
| 사용자 전역 | ~/.claude.json | ~/.codex/config.toml |
| 프로젝트 공유 | .mcp.json | .codex/config.toml |
| 프로젝트 개인 설정 | ~/.claude.json의 프로젝트별 설정 | 별도의 Local MCP Scope 없음 |
Claude Code는 MCP 자체에 User / Project / Local Scope가 있고, Codex는 기존 config.toml 설정 계층 안에서 MCP를 관리한다는 차이가 있습니다.
결국 무엇을 어디에 작성해야 할까요?
지금까지의 내용을 실제 상황에 대입하면 다음처럼 정리할 수 있습니다.
프로젝트 전체에서 항상 지켜야 하는 Architecture
→ CLAUDE.md / AGENTS.md
특정 코드 영역에서만 지켜야 하는 Convention
→ Claude Rules
→ Codex의 디렉터리별 AGENTS.md
코드 분석이나 리뷰처럼 반복되는 작업 절차
→ SKILL.md
별도의 Context에서 전문 작업 수행
→ Subagent
GitHub, Notion 등 외부 기능 사용
→ MCP전체 관계를 다시 보면 다음과 같습니다.
프로젝트 기본 Policy
AGENTS.md / CLAUDE.md
↓
영역별 Policy
Claude Rules / Codex AGENTS.md 계층
↓
작업별 Workflow
SKILL.md
↓
필요하면 작업 분리
Subagent
↓
외부 Capability
MCPClaude Code와 Codex를 함께 사용한다면
두 Coding Agent를 같은 프로젝트에서 사용한다면 가장 중요한 원칙은 같은 내용을 두 번 관리하지 않는 것입니다.
모든 설정을 하나로 합칠 필요는 없습니다.
공통으로 사용할 수 있는 것은 하나의 원본으로 관리하고, 제품별 구조가 다른 기능만 따로 관리하면 됩니다.
공통 프로젝트 지침은 AGENTS.md를 기준으로 관리합니다
AGENTS.md는 Codex뿐 아니라 여러 Coding Agent가 지원하는 Open Format이므로 공통 프로젝트 Policy의 기준 파일로 두기 좋습니다.
my-project/
├── AGENTS.md
├── CLAUDE.md
└── ...Codex와 AGENTS.md를 지원하는 Agent는 이 파일을 직접 사용합니다.
Claude Code에서는 다음처럼 Import합니다.
@AGENTS.md
## Claude Code
Claude Code에서만 필요한 추가 지침을 작성합니다.
따라서 공통 Policy의 실제 원본은 AGENTS.md 하나입니다.
AGENTS.md
↗ ↑ ↖
Codex Cursor Gemini CLI
│
│ import
↓
CLAUDE.md
│
Claude Code공통 Skill은 .agents/skills를 원본으로 관리합니다
Skill 역시 여러 Coding Agent가 공유할 수 있는 Agent Skills 형식을 사용합니다.
따라서 다음처럼 .agents/skills를 공통 Skill의 원본으로 둘 수 있습니다.
.agents/
└── skills/
├── code-analysis/
│ └── SKILL.md
└── code-review/
└── SKILL.md
Codex를 비롯해 .agents/skills를 지원하는 Agent는 이 경로를 직접 사용합니다.
Claude Code는 기본적으로 .claude/skills를 사용하므로 필요한 Skill을 Symbolic Link로 연결할 수 있습니다.
mkdir -p .claude/skills
ln -s ../../.agents/skills/code-analysis \
.claude/skills/code-analysis
구조적으로는 다음과 같습니다.
.agents/skills/code-analysis
▲
│ symbolic link
│
.claude/skills/code-analysis
이렇게 하면 Skill 원본은 하나만 유지하면서 여러 Coding Agent에서 같은 Skill을 사용할 수 있습니다.
개인 Skill도 같은 방식으로 별도의 Repository에서 관리할 수 있습니다.
~/agent-skills/
├── code-analysis/
├── code-review/
└── spring-analysis/
각 Agent가 기대하는 위치에 Symbolic Link를 연결하면 됩니다.
ln -s ~/agent-skills/code-analysis \
~/.claude/skills/code-analysis
ln -s ~/agent-skills/code-analysis \
~/.agents/skills/code-analysis나머지는 Agent별로 관리합니다
Subagent와 MCP처럼 제품마다 Format이 다른 설정까지 억지로 하나로 만들 필요는 없습니다.
Claude Subagent
→ .claude/agents/*.md
Codex Custom Agent
→ .codex/agents/*.tomlMCP도 마찬가지입니다.
Claude
→ .mcp.json
Codex
→ .codex/config.tomlMCP Endpoint나 Token을 제공하는 환경 변수 같은 값은 공유할 수 있지만, 설정 파일 자체는 제품별 Format에 맞게 관리하는 편이 단순합니다.
Claude의 Path-scoped Rules와 Codex의 Command Rules 역시 이름만 비슷할 뿐 역할이 다르므로 각각 관리합니다.
최종 프로젝트 구조
지금까지의 내용을 하나의 프로젝트에 적용하면 다음처럼 정리할 수 있습니다.
my-project/
│
├── AGENTS.md
│ # 공통 프로젝트 Policy
│
├── CLAUDE.md
│ # @AGENTS.md + Claude 전용 지침
│
├── .agents/
│ └── skills/
│ # 공통 Skill 원본
│ ├── code-analysis/
│ │ └── SKILL.md
│ └── code-review/
│ └── SKILL.md
│
├── .claude/
│ ├── settings.json
│ │
│ ├── rules/
│ │ # Claude 영역별 개발 규칙
│ │
│ ├── skills/
│ │ # 공통 Skill Symbolic Link
│ │
│ └── agents/
│ # Claude Subagents
│
├── .codex/
│ ├── config.toml
│ │ # Codex 설정 + MCP
│ │
│ ├── rules/
│ │ # Codex 명령 실행 정책
│ │
│ └── agents/
│ # Codex Custom Agents
│
└── .mcp.json
# Claude Project MCP
Monorepo에서 Codex의 영역별 지침이 필요하다면 해당 디렉터리에 AGENTS.md를 추가할 수 있습니다.
my-project/
├── AGENTS.md
│
├── backend/
│ └── AGENTS.md
│
└── frontend/
└── AGENTS.md
사용자 전역 설정은 다음처럼 구분됩니다.
$HOME
│
├── .claude/
│ ├── CLAUDE.md
│ ├── settings.json
│ ├── rules/
│ ├── skills/
│ └── agents/
│
├── .codex/
│ ├── AGENTS.md
│ ├── config.toml
│ ├── rules/
│ └── agents/
│
└── .agents/
└── skills/마치며
Coding Agent를 처음 사용할 때는 좋은 Prompt를 작성하는 것이 가장 중요해 보입니다.
하지만 실제 프로젝트에서 반복해서 사용하다 보면 문제는 점차 Prompt 작성이 아니라 Context 관리로 바뀝니다.
어떤 정보는 항상 제공해야 하고, 어떤 정보는 특정 코드 영역에서만 필요합니다. 특정 작업에서만 필요한 절차는 Skill로 분리할 수 있고, 별도의 조사나 분석은 Subagent에게 맡길 수 있습니다. 외부 시스템이 필요하다면 MCP로 Capability를 확장할 수 있습니다.
결국 다음 정도로 기억하면 됩니다.
항상 알아야 하는 것
→ AGENTS.md / CLAUDE.md
특정 코드 영역에서 지켜야 하는 것
→ Claude Rules
→ Codex의 AGENTS.md 계층
특정 작업의 수행 방법
→ SKILL.md
별도의 작업자에게 맡길 것
→ Subagent
외부 시스템을 사용할 것
→ MCP
그리고 Claude Code와 Codex를 함께 사용한다면 공통화할 수 있는 영역과 제품별 설정을 구분하는 것이 중요합니다.
프로젝트 Policy는 AGENTS.md를 중심으로 공유하고, 재사용 가능한 Workflow는 Agent Skills로 작성해 하나의 원본으로 관리할 수 있습니다.
반대로 Rules, Subagent, MCP처럼 각 제품의 설정 방식이나 의미가 다른 기능은 제품별로 관리하는 편이 명확합니다.
결국 Coding Agent 환경을 잘 구성한다는 것은 긴 Prompt 하나를 만드는 일이 아니라,
"어떤 Context를 언제 제공할 것인지, 무엇을 공통화하고 무엇을 제품별로 분리할 것인지 설계하는 것입니다."
Coding Agent가 단순한 코드 생성 도구를 넘어 실제 개발 환경의 일부가 되고 있는 만큼, 코드 자체뿐 아니라 Agent가 프로젝트를 이해하고 작업할 수 있도록 Context를 어떻게 구성할 것인지도 중요한 개발 환경 설계 요소가 됩니다.