이전 글에서는 AGENTS.md, CLAUDE.md, Rules, Skills에 어떤 정보를 나눠 담아야 하는지 정리했다.
이번에는 Android와 Backend가 함께 있는 모노레포에 Context를 구성한다. 공통 Architecture와 개발 규칙은 Root에 두고, 특정 Module에서만 필요한 기준은 더 가까운 위치로 나눈다. 마지막에는 파일을 만드는 데서 끝내지 않고 Claude Code와 Codex가 의도한 Context를 읽고 같은 기준으로 프로젝트를 해석하는지까지 확인한다.
처음부터 AGENTS.md, CLAUDE.md, .claude/rules/, SKILL.md를 전부 만들 필요는 없다. 먼저 두 Agent가 현재 Repository를 어떻게 이해하는지 확인한 뒤, 반복해서 설명해야 하거나 코드만으로 판단하기 어려운 기준부터 Context로 남긴다.
Claude Code와 Codex를 같은 Repository에서 실행한다
Context를 구성하기 전에 Claude Code와 Codex CLI가 개발 환경에서 정상적으로 동작하는지 확인한다.
Claude Code 설치
Windows PowerShell에서는 다음 명령으로 Claude Code를 설치할 수 있다.
irm https://claude.ai/install.ps1 | iexCMD에서는 다음 명령을 사용한다.
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd설치 방법은 변경될 수 있으므로 설치 시점에는 공식 문서를 함께 확인하는 편이 좋다. Claude Code 공식 Quickstart
Claude Code 설치
설치가 끝나면 Terminal에서 claude를 실행하고 로그인한다.
claude
Claude Code 로그인 방식 선택
로그인까지 완료되면 Terminal에서 Claude Code를 사용할 수 있다.
Claude Code 로그인 완료
Codex 설치
같은 Windows 환경에 Codex CLI도 설치한다. OpenAI Codex GitHub
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"설치 후 codex를 실행하고 로그인한다.
codexWindows에서는 Codex가 파일과 명령에 접근할 수 있는 범위를 제한하는 Sandbox 설정도 나타난다.
Codex Windows Sandbox 설정
Sandbox의 목적은 Codex를 관리자 권한으로 계속 실행하는 데 있지 않다. Agent가 시스템 전체를 자유롭게 수정하지 못하도록 파일 접근과 명령 실행 범위를 제한하는 데 있다.
설치가 끝났다면 Git과 두 CLI가 정상적으로 등록됐는지만 확인한다.
git --version
claude --version
codex --version프로젝트는 따로 등록하지 않는다
Claude Code나 Codex에 Repository를 별도로 등록하는 과정은 없다. 작업할 Directory로 이동한 뒤 CLI를 실행하면 해당 위치를 기준으로 Codebase를 탐색한다.
Claude Code는 다음처럼 실행한다.
cd D:\dev\project
claudeCodex도 같은 방식으로 시작할 수 있다.
cd D:\dev\project
codexRepository가 다음과 같은 모노레포라면 Root에서 Android와 Backend를 포함한 전체 구조를 탐색할 수 있다.
project/
├── android/
├── backend/
├── infra/
├── docs/
└── README.md다만 Repository를 읽을 수 있다는 사실만 확인하고 바로 기능 구현을 맡기지는 않는다. 먼저 파일을 수정하지 않은 상태에서 현재 프로젝트를 어떻게 이해하는지 확인한다.
아직 파일은 수정하지 마.
현재 Repository를 읽고 프로젝트 구조와 현재 상태만 분석해줘.
다음을 확인해줘.
1. 최상위 Directory 구조
2. android 모듈의 역할
3. backend 모듈의 역할
4. infra의 역할
5. docs에 있는 문서와 각 문서의 역할
6. 사용 중인 주요 기술 Stack
7. 현재 Git branch
8. 현재 Working Tree 상태
분석 결과만 알려줘.
파일 생성/수정/삭제, Git commit, merge, push는 하지 마.이 단계에서 보는 것은 답변을 얼마나 그럴듯하게 작성하는지가 아니다. Repository에 있는 근거를 바탕으로 현재 상태를 제대로 구분하는지를 확인한다.
Android와 Backend의 책임을 구분하는지, 아직 구현하지 않은 기능을 현재 기능처럼 설명하지 않는지, Git 상태를 추측하지 않고 명령으로 확인하는지가 판단 기준이다.
Claude Code 프로젝트 분석
같은 요청을 Codex에도 전달한다.
Codex 프로젝트 분석
여기서 비교하는 것은 Context가 전혀 없는 상태가 아니다. 두 Agent는 이미 Source Code, README, docs/, 현재 대화와 Tool Result를 Context로 사용할 수 있다.
아직 추가하지 않은 것은 AGENTS.md와 CLAUDE.md처럼 프로젝트의 판단 기준을 명시적으로 전달하는 Project Instruction이다.
두 Agent 모두 Repository 구조를 읽을 수 있더라도 현재 Architecture까지 같은 방식으로 이해한다는 보장은 없다.
코드만으로는 현재 Architecture를 판단하기 어렵다
예를 들어 현재 프로젝트에서 Provider 인증과 API 호출은 Android가 담당하고, Backend는 전달받은 Metadata를 관리한다고 하자.
Provider 인증 / Provider API 호출
↓
Android
↓
Metadata
↓
Backend이 구조는 Android나 Backend Framework가 강제하는 방식이 아니라 프로젝트에서 선택한 Architecture다.
Repository에 과거 Backend OAuth 코드가 남아 있다면 Agent는 기존 코드를 근거로 새로운 Provider 인증도 Backend에 추가해야 한다고 판단할 수 있다.
코드에는 현재 사용 중인 구현뿐 아니라 이전 방식의 코드, Migration 중인 코드, 앞으로 제거할 코드가 함께 남을 수 있기 때문이다.
사람은 이전 작업 과정과 설계가 변경된 이유를 알고 있지만 Agent는 Repository 안에서 그 근거를 찾아야 한다. 이 차이를 매번 Prompt로 설명하기보다, 여러 작업에서 반복해서 필요한 판단 기준을 Repository의 Project Context로 관리한다.
공통 프로젝트 기준은 AGENTS.md에 둔다
두 Agent가 공통으로 알아야 하는 내용부터 Root AGENTS.md에 정리한다.
project/
├── AGENTS.md
├── android/
├── backend/
├── infra/
├── docs/
└── README.mdAGENTS.md에는 코드만 보고 판단하면 잘못 이해하기 쉬운 내용을 우선해서 넣는다.
| 구분 | AGENTS.md에 두는 내용 |
|---|---|
| Architecture | Android와 Backend의 책임, Module Boundary |
| Provider | 인증 위치, API 호출 위치, Token 처리 기준 |
| API | Module 간 Contract와 변경 시 주의사항 |
| Security | Credential, Secret, 민감정보 처리 기준 |
| Git | Commit, Merge, Push 등 Agent가 임의로 수행하면 안 되는 작업 |
| Documentation | Architecture 문서, Roadmap, 현재 구현의 구분 |
| Review | Architecture, Regression, Security 등 변경 시 확인할 기준 |
상세한 설계 배경까지 AGENTS.md에 복사할 필요는 없다. 설계 이유와 의사결정 기록은 기존 docs/에서 관리하고, Agent가 개발과 Review 과정에서 반복해서 적용해야 할 규칙만 AGENTS.md에 둔다.
docs/
→ 왜 이런 구조를 선택했는가
AGENTS.md
→ 현재 개발과 Review에서 무엇을 지켜야 하는가이렇게 역할을 나누면 Architecture 설명이 바뀔 때 여러 Context 파일의 같은 내용을 함께 수정해야 하는 문제도 줄어든다.
모노레포에서는 Module 규칙을 분리한다
Root AGENTS.md 하나로 시작할 수 있지만 Android와 Backend의 세부 규칙까지 모두 넣으면 파일이 빠르게 커진다.
Android에는 StorageClient, Room Cache, 공통 Storage UI처럼 Android에서만 필요한 기준이 있고, Backend에는 File / FileLocation, JPA, Transaction Boundary처럼 별도의 규칙이 있다.
Android 화면을 수정하는 작업에서 Backend의 JPA 규칙까지 함께 볼 이유는 없다.
공통 규칙은 Root에 두고 Module에 종속된 내용만 하위 AGENTS.md로 분리한다.
project/
├── AGENTS.md
├── CLAUDE.md
│
├── android/
│ ├── AGENTS.md
│ └── CLAUDE.md
│
├── backend/
│ ├── AGENTS.md
│ └── CLAUDE.md
│
├── infra/
└── docs/각 파일의 역할은 다음처럼 나눈다.
| 파일 | 역할 |
|---|---|
Root AGENTS.md |
Architecture, API, Security, Git, Documentation 등 공통 규칙 |
android/AGENTS.md |
StorageClient, Room Cache, 공통 Storage UI, Android 검증 규칙 |
backend/AGENTS.md |
Domain, JPA, Transaction, Provider Boundary, Backend 검증 규칙 |
Root CLAUDE.md |
Claude Code가 구현할 때 따르는 공통 Workflow |
Module CLAUDE.md |
해당 Module의 AGENTS.md 연결과 Claude 전용 지침 |
이렇게 나누면 프로젝트 전체에서 공유해야 할 기준과 특정 Module에서만 필요한 규칙이 섞이지 않는다.
다만 Module에 파일을 배치했다고 Claude Code와 Codex가 같은 방식으로 이를 읽는 것은 아니다.
Codex는 Root에서 현재 Working Directory까지 읽는다
Codex는 세션을 시작할 때 Project Root에서 현재 Working Directory까지 내려오면서 AGENTS.md를 찾는다.
예를 들어 Root에서 Codex를 실행하면:
cd D:\dev\project
codexRoot AGENTS.md까지가 기본 Project Instruction Chain에 포함된다.
Root에서 실행했다고 해서 android/AGENTS.md와 backend/AGENTS.md를 처음부터 모두 읽는 것은 아니다.
Android 전용 규칙까지 적용하려면 Android를 Working Directory로 잡는다.
cd D:\dev\project\android
codex또는 Root에서 다음처럼 실행할 수도 있다.
codex --cd android이 경우 다음 두 파일이 Root에서 가까운 순서로 합쳐진다.
project/AGENTS.md
+
project/android/AGENTS.md현재 Working Directory에 가까운 지침이 뒤에 들어가기 때문에 Root에는 프로젝트 공통 기준을 두고, 더 구체적인 Module 기준은 하위 AGENTS.md에 둘 수 있다.
같은 Directory에 AGENTS.override.md가 있다면 Codex는 일반 AGENTS.md보다 이를 먼저 선택한다. 특별한 Override가 필요하지 않다면 기본 AGENTS.md 구조만 사용해도 충분하다.
OpenAI — Custom instructions with AGENTS.md
Claude Code는 CLAUDE.md를 계층적으로 읽는다
Claude Code의 탐색 방식은 조금 다르다.
Android Directory에서 Claude Code를 실행하면 현재 Directory에서 상위로 올라가며 발견한 CLAUDE.md를 모두 읽는다.
cd D:\dev\project\android
claude따라서 다음 Context가 함께 들어간다.
project/CLAUDE.md
+
project/android/CLAUDE.mdRoot에서 Claude Code를 실행한 경우에는 Root CLAUDE.md로 시작한다. 이후 Claude가 android/의 파일을 읽으면 해당 Directory의 CLAUDE.md가 그 시점에 추가된다.
즉 Root와 Module로 Context를 나누는 원칙은 같지만, 현재 세션에 어떤 파일이 들어오는지는 두 Agent의 Context Discovery 방식에 따라 다르다.
Anthropic — How Claude remembers your project
Claude Code는 CLAUDE.md에서 공통 규칙을 연결한다
Codex는 AGENTS.md를 Project Instruction으로 사용하고 Claude Code는 CLAUDE.md를 사용한다.
같은 Architecture 규칙을 두 파일에 다시 작성하지 않고 Root CLAUDE.md에서 AGENTS.md를 Import한다.
@AGENTS.md그 아래에는 Claude Code가 구현을 진행할 때 필요한 Workflow만 추가한다.
Issue 확인
↓
관련 코드와 Architecture 확인
↓
영향 받는 Module 확인
↓
구현
↓
Build / Test / Lint
↓
Self Review
↓
변경 내용과 검증 결과 보고Architecture, Security, API Boundary처럼 프로젝트 전체가 공유하는 규칙은 AGENTS.md에서 관리하고, Claude Code의 작업 순서와 완료 조건처럼 Claude에만 필요한 내용은 CLAUDE.md에 둔다.
Module의 CLAUDE.md도 Architecture를 다시 복사하는 파일로 만들지 않는다.
Android에서는 다음 정도만 두고 Root CLAUDE.md와 현재 Module의 AGENTS.md를 함께 사용하도록 연결한다.
@AGENTS.md
# Android Claude Code
Follow this directory's `AGENTS.md` together with the root `CLAUDE.md`.
Do not duplicate Android architecture, cache, or build rules here.여기서 @AGENTS.md가 어느 파일을 가리키는지도 알아둘 필요가 있다.
Claude Code의 Import에서 상대 경로는 Terminal의 현재 Working Directory가 아니라 Import를 작성한 CLAUDE.md 파일을 기준으로 해석된다.
따라서 Root CLAUDE.md의:
@AGENTS.md는:
project/AGENTS.md를 가져오고, android/CLAUDE.md의 같은 Import는:
project/android/AGENTS.md를 가져온다.
project/
├── AGENTS.md
├── CLAUDE.md → @AGENTS.md
│
└── android/
├── AGENTS.md
└── CLAUDE.md → @AGENTS.md같은 규칙을 AGENTS.md, Root CLAUDE.md, Module CLAUDE.md에 반복해서 작성하면 어느 문서가 현재 기준인지 관리하기 어려워진다.
Context 파일을 여러 단계로 나누더라도 같은 정보의 Source of Truth는 한곳에 두는 편이 낫다.
Context를 만들었다면 어떤 파일이 읽혔는지 확인한다
파일을 만들었다는 사실만으로 Context 구성이 끝난 것은 아니다.
먼저 현재 세션에 어떤 Instruction 파일이 들어왔는지, 그다음 Agent가 해당 규칙을 의도대로 이해했는지를 확인한다.
어떤 Context가 로드됐는가?
↓
그 Context를 어떻게 해석했는가?Codex에서 AGENTS.md 확인
Codex는 먼저 현재 Working Directory에서 어떤 Instruction Source가 활성화됐는지 확인할 수 있다.
예를 들어 Backend의 Context를 확인하려면:
codex --cd backend --ask-for-approval never "Show which instruction files are active."Root와 Backend의 Context가 모두 적용됐다면 다음 순서의 Instruction Source가 확인되어야 한다.
project/AGENTS.md
↓
project/backend/AGENTS.mdCodex는 세션을 시작할 때 Instruction Chain을 다시 구성한다. AGENTS.md를 수정했거나 Working Directory를 바꿨다면 새 세션에서 다시 확인하는 편이 안전하다.
어떤 파일이 들어왔는지 확인했다면 이제 규칙의 해석이 맞는지 확인한다.
파일을 수정하지 않은 상태에서 AGENTS.md와 관련 문서를 읽고 Architecture를 다시 설명하도록 요청한다.
아직 어떤 파일도 수정하지 마.
현재 Repository의 AGENTS.md와
AGENTS.md에서 참조하는 관련 문서를 읽고
프로젝트 구조와 개발 규칙을 분석해줘.
다음을 설명해줘.
1. Android와 Backend의 책임 차이
2. Provider 인증은 어디에서 담당하는지
3. Provider API는 어디에서 직접 호출하는지
4. Backend가 Provider access token이나 refresh token을 저장해도 되는지
5. 현재 구현된 영역과 향후 구현될 영역의 차이
6. File과 FileLocation의 책임 차이
7. 외부 Network I/O와 DB Transaction 규칙
8. Roadmap의 기능을 현재 구현으로 간주해도 되는지
9. 요청하지 않은 commit, push, merge를 수행해도 되는지
각 답변의 근거가 된 규칙이나 문서도 함께 알려줘.
파일 수정, commit, push, merge는 하지 마.
Codex AGENTS.md 검증
여기서 확인할 것은 단순히 AGENTS.md를 읽었다는 답변이 아니다.
Provider 인증 위치, Backend의 Token 저장 여부, Transaction Boundary처럼 틀리면 구현 방향 자체가 달라지는 기준을 정확하게 재현하는지를 본다.
Provider 인증을 Backend의 책임으로 설명하거나 Roadmap에 적힌 기능을 현재 구현된 기능으로 판단한다면 기능 개발을 시작하기 전에 Context부터 다시 확인해야 한다.
Claude Code에서 CLAUDE.md 확인
Claude Code에서도 같은 검증을 진행한다.
Android Module의 Context를 확인한다면 해당 Directory에서 Claude Code를 실행한다.
cd D:\dev\project\android
claude현재 세션에 어떤 Context가 포함되어 있는지는 /context에서 확인할 수 있다.
/contextRoot와 Android의 CLAUDE.md가 Memory Files에 나타나는지 먼저 확인한다.
파일 이름이 목록에 있다고 끝내지는 않는다. Android 규칙 자체도 다시 설명하게 한다.
파일은 수정하지 마.
현재 적용된 Root 규칙과 Android 전용 규칙을 구분해서 설명해줘.
특히 다음 항목을 확인해줘.
- Provider 인증 위치
- Provider API 호출 위치
- StorageClient 역할
- 공통 Storage UI 구조
- Room Cache 역할
- Android 검증 명령
각 항목의 근거가 되는 Context도 함께 알려줘.Backend에서도 같은 방식으로 File / FileLocation, StorageSource, Transaction Boundary, JPA, Provider Boundary와 Build/Test 규칙을 확인한다.
이 검증을 기능을 개발할 때마다 반복할 필요는 없다.
처음 Context 구조를 만들었거나 Root와 Module의 계층을 크게 변경했을 때, Architecture Boundary가 바뀌었을 때 다시 확인하면 된다.
Rules와 Skills는 필요할 때 추가한다
이전 글에서는 .claude/rules/와 SKILL.md까지 다뤘지만 프로젝트에 Context를 구성한다고 모든 기능을 처음부터 사용할 필요는 없다.
현재 필요한 Context가 다음 정도라면 여기서 시작한다.
AGENTS.md
CLAUDE.md
android/AGENTS.md
android/CLAUDE.md
backend/AGENTS.md
backend/CLAUDE.md.claude/rules/는 특정 Directory나 코드 종류에서만 필요한 Claude Code 규칙이 많아졌을 때 분리한다.
SKILL.md 역시 같은 지식이나 작업 절차를 반복해서 사용할 이유가 생겼을 때 추가한다.
아직 발생하지 않은 작업까지 예상해서 Rules와 Skills부터 만들면 Agent가 읽어야 할 Context와 사람이 관리해야 할 파일만 늘어난다.
Context를 잘 구성한다는 것은 파일을 많이 만드는 것이 아니라, 코드만으로 판단하기 어렵고 여러 작업에서 반복해서 필요한 정보를 적절한 범위에 남기는 것이다.
같은 Repository를 읽는 것만으로는 충분하지 않다
Claude Code와 Codex를 Repository에서 실행하는 것 자체는 어렵지 않다.
차이는 두 Agent가 그 Repository를 어떤 기준으로 해석하느냐에서 생긴다.
코드는 현재 구현을 보여주지만 왜 그런 구조를 선택했는지, 어떤 경계를 앞으로도 유지해야 하는지까지 모두 설명하지 않는다.
특히 이전 구현과 새로운 구현이 함께 남아 있거나 여러 Module의 책임이 나뉘는 프로젝트에서는 같은 코드를 읽고도 서로 다른 Architecture를 추론할 수 있다.
그래서 프로젝트 공통 기준은 AGENTS.md에 두고, Claude Code는 CLAUDE.md를 통해 같은 기준을 공유하도록 구성했다. Android와 Backend처럼 책임과 구현 방식이 다른 영역은 Module 단위로 나누고, 각 Agent가 어떤 Context를 읽는지도 직접 확인했다.
이 구조를 기반으로 다음 단계에서는 구현과 Review 역할을 개발 흐름에 연결한다.
GitHub Issue
↓
Claude Code
↓
Implementation
↓
Build / Test / Self Review
↓
Pull Request
↓
GitHub Actions
↓
Codex Code Review
↓
Human Approval
↓
Merge이번 단계에서 만든 것은 이 Workflow 전체의 자동화가 아니다.
먼저 Claude Code와 Codex가 같은 Repository를 보면서 서로 다른 프로젝트를 상상하지 않도록 판단 기준과 Context의 범위를 맞춘 것이다.
Agent가 Architecture를 잘못 이해한 상태에서는 더 좋은 모델이나 더 빠른 코드 생성도 근본적인 해결책이 되지 않는다. 잘못된 기준으로 더 많은 코드를 만들 뿐이다.
기능 구현을 맡기기 전에 프로젝트가 지켜야 할 경계를 Repository 안에 남겨두고, 그 기준이 Agent에게 제대로 전달되는지 확인해야 하는 이유가 여기에 있다.