Claude & Codex #2 AGENTS.md, CLAUDE.md, SKILL.md 작성 가이드

앞선 글에서는 Claude Code가 기능을 구현하고 Codex가 완성된 변경을 다시 보는 방식으로 역할을 나눴다.
하지만 구현과 Review를 분리하는 것만으로 두 Agent의 판단 기준까지 같아지지는 않는다.
예를 들어 프로젝트에서 외부 API 호출과 DB 반영을 다음처럼 분리했다고 해보자.

Provider API 호출
        ↓
응답 수신
        ↓
DB Transaction 시작
        ↓
Metadata 반영

외부 API 응답을 기다리는 동안 DB Transaction을 유지하지 않기 위한 설계다. Claude Code는 이 기준을 알고 기능을 구현했다. 반면 Codex가 설계 의도를 모른다면 Pull Request에서 다음과 같은 Review를 남길 수도 있다.

외부 API 호출과 Metadata 저장을 하나의 Transaction으로 묶는 편이 안전합니다.

코드만 놓고 보면 가능한 접근이다. 하지만 현재 프로젝트에서는 의도적으로 피하고 있는 구조다.
같은 Repository를 읽어도 어떤 Context를 가지고 있느냐에 따라 같은 코드를 다르게 판단할 수 있다.

같은 Repository만으로는 프로젝트 기준을 공유할 수 없다

Repository에는 현재 구현이 남아 있지만, 왜 그런 구조를 선택했는지, 앞으로도 어떤 경계를 지켜야 하는지까지 코드에 모두 드러나지는 않는다.

코드만으로 판단하기 어려운 것	예시
설계 이유	왜 외부 I/O와 DB Transaction을 분리했는가
책임 경계	인증을 Client와 Backend 중 어디에서 담당하는가
금지된 방향	Provider 전용 Type이 공통 Domain으로 들어가도 되는가
현재 기준	남아 있는 코드가 현재 Architecture인지 Legacy인지
검증 방법	변경 후 어떤 Build와 Test를 실행해야 하는가

이런 정보가 없다면 Agent는 Codebase를 탐색하면서 빠진 맥락을 스스로 추론한다. 문제는 Claude Code와 Codex가 항상 같은 전제로 추론하지는 않는다는 것이다. 그래서 여러 Agent가 같은 프로젝트에서 작업하려면 코드뿐 아니라 어떤 기준으로 코드를 이해하고 판단해야 하는지도 공유해야 한다.

여기서 Context Engineering이 필요해진다.

Agent가 어떤 기준으로 판단할지도 설계해야 한다

Context Engineering은 Prompt를 길게 만드는 것이 아니다.
Agent가 작업할 때 사용할 Instruction, Project Rule, 현재 Task, Code, Tool Result 같은 정보를 어떤 범위에서 제공하고 유지할지 설계하는 것에 가깝다.

Architecture
Project Rules
Current Task
Current Code
Tool Results
        ↓
      Agent
        ↓
   판단 → 실행

Anthropic 은 Claude Code의 Context Window가 대화, 읽은 파일, 명령 결과까지 계속 쌓이는 자원이라고 설명한다. Context가 불필요하게 커질수록 앞선 지침을 놓치거나 실수가 늘 수 있기 때문에 무엇을 넣을지뿐 아니라 무엇을 넣지 않을지도 중요하다.

그렇다면 프로젝트 정보를 가능한 많이 넣으면 될까?

오히려 좋은 Context는 그 반대에 가깝다.

좋은 Context는 Repository를 요약하는 문서가 아니다

Anthropic, OpenAI, Google, Meta의 공개 자료를 비교하면 사용하는 파일과 구현 방식은 다르지만 방향은 비슷하다.

사례	강조하는 내용	핵심
Anthropic	Build/Test 명령, 프로젝트 고유 Workflow, 비직관적인 규칙	항상 필요한 내용만 간결하게 유지
OpenAI	Repository Rule, Scope, Service별 Review 기준	공통 기준과 더 구체적인 기준을 가까운 위치에 배치
Google	Project Instruction, Coding Style, Module별 지침	Global → Project → Subdirectory로 Scope 분리
Meta	Quick Commands, Key Files, Non-Obvious Patterns, Reference	Compass, not encyclopedia

Anthropic 은 CLAUDE.md에서 코드만 읽어 알 수 있는 내용이나 일반적인 언어 Convention, 긴 Tutorial과 파일별 설명을 제외하도록 권장한다.

OpenAI 의 AGENTS.md도 Root에서 현재 Working Directory까지 계층적으로 적용할 수 있고, Code Review Rule은 Repository 전체 규칙과 Service별 규칙을 가까운 위치에 나눠둘 수 있다.

Google Gemini CLI 역시 Global, Project, Subdirectory와 Just-in-Time Context를 지원해 특정 영역의 지침을 실제 필요할 때 가져올 수 있다.

Meta 는 대규모 Codebase의 Context 파일을 약 25~35줄로 유지하면서 Quick Commands, 핵심 파일, 코드에서 알아내기 어려운 Pattern, 관련 문서에 집중했고 이를 “Compass, not encyclopedia” 라고 설명한다.

공통점은

Agent가 Codebase를 읽어 쉽게 알아낼 수 있는 내용보다, 모르고 작업하면 실제 판단이 달라질 정보를 남긴다.

모든 Context를 한 파일에 넣지 않는 이유

다음 정보는 모두 개발 과정에서 필요할 수 있다.

왜 Client에서 인증을 처리하는가
외부 I/O는 DB Transaction 밖에서 실행한다
Claude Code는 구현 후 전체 Diff를 확인한다
Migration은 이미 적용된 파일을 수정하지 않는다
Architecture 변경 시 관련 문서를 함께 확인한다 
이번 Issue에서는 증분 동기화를 구현한다

하지만 같은 종류의 정보는 아니다.

질문	Context	역할
왜 이렇게 설계했는가?	Architecture 문서	설계 이유와 Trade-off
프로젝트에서 무엇을 지켜야 하는가?	`AGENTS.md`	반복되는 프로젝트 기준
Claude Code는 어떻게 작업해야 하는가?	`CLAUDE.md`	Claude 전용 Workflow
특정 코드에서만 필요한가?	`.claude/rules/`	특정 Path에 적용되는 규칙
특정 작업 방법을 재사용하는가?	`SKILL.md`	필요할 때 불러오는 지식과 절차
이번에 무엇을 만들어야 하는가?	Issue / Prompt	현재 Task의 요구사항

이 표 전체가 Anthropic이나 OpenAI가 정해놓은 공식 문서 구조라는 뜻은 아니다.
이 글에서는 정보의 대상과 적용 범위, 수명에 따라 Context를 나누고 같은 내용을 여러 곳에서 관리하지 않기 위해 이렇게 구성한다.

AGENTS.md에는 반복되는 프로젝트 기준을 둔다

Architecture 경계나 Security 규칙을 매 Prompt마다 다시 작성한다고 생각해보자.

외부 API는 DB Transaction 밖에서 호출하고,
Provider 전용 Type은 공통 Domain에 넣지 말고,
API Contract를 변경하면 호출 측도 같이 수정하고,
Token은 로그에 남기지 말고...

작업마다 복사하다 보면 어느 Prompt에서는 규칙이 빠질 수 있고, 시간이 지나면서 서로 다른 버전의 기준이 전달될 수도 있다.
그래서 작업이 바뀌어도 계속 유지되어야 하는 판단 기준을 Repository Context로 옮긴다.

## Architecture
- Keep external network I/O outside DB transactions.
- Preserve the existing client / backend responsibility boundary.
- Do not leak Provider-specific types into the common domain.
- Do not change a cross-module API contract on only one side.

## Security
- Never commit passwords, API keys, OAuth secrets, or tokens.
- Never write credentials or sensitive values to logs.

## Verification
- Run the required Build and Test for every affected module.
- Do not report completion while required checks are failing.

Codex는 Project Root부터 현재 Working Directory까지 관련 AGENTS.md를 합쳐 Instruction으로 사용하므로 Repository 전체 기준과 더 구체적인 Module 기준을 나눠둘 수 있다.

좋은 Rule은 해석보다 판정에 가깝다

다음 규칙은 틀린 말은 아니다.

Architecture를 지켜라.
보안을 확인해라.
기존 구조를 유지해라.
Test를 충분히 해라.

하지만 실제 코드를 봤을 때 무엇을 위반으로 판단해야 하는지가 없다.

❌ 추상적인 규칙	⭕ 판정 가능한 규칙
Architecture를 지킨다	외부 Provider API는 DB Transaction 밖에서 호출한다
보안을 확인한다	Token과 Credential을 코드·로그에 남기지 않는다
기존 구조를 유지한다	Provider 전용 Type을 공통 Domain으로 노출하지 않는다
API 변경을 확인한다	Contract 변경 시 영향을 받는 호출 측도 함께 수정한다
Test를 한다	변경된 Module에 정의된 Build와 Test를 실행한다

OpenAI도 Code Review Rule을 작성할 때 단순한 주의 문구보다 문제가 되는 조건과 안전한 처리 방향을 구체적으로 작성하는 예시를 제공한다. Rule을 작성한 뒤에는 하나만 확인하면 된다.

Agent가 이 문장을 실제 코드와 비교해서 위반 여부를 판단할 수 있는가?

판단하기 어렵다면 아직 충분히 구체적이지 않은 것이다.

설계 이유까지 AGENTS.md에 넣을 필요는 없다

다음 한 줄만 있어도 Agent는 구현이나 Review에서 Rule을 적용할 수 있다.

External network I/O must run outside DB transactions.

하지만 왜 이런 Rule이 생겼는지를 설명하려면 이야기가 길어진다.

외부 API 응답 시간은 통제하기 어려움
              ↓
Transaction 안에서 외부 호출
              ↓
DB Connection과 Transaction 유지 시간 증가
              ↓
외부 I/O와 DB 반영 분리

이건 Rule보다 Architecture의 판단 과정과 Trade-off에 가깝다.

그래서 둘을 나눈다.

Context	답하는 질문
`docs/architecture.md`	왜 이렇게 설계했는가?
`AGENTS.md`	그래서 무엇을 지켜야 하는가?

긴 설계 설명은 Architecture 문서에 남기고, AGENTS.md에는 실제 작업에서 계속 사용할 기준만 둔다.

이렇게 해야 같은 Architecture 설명을 AGENTS.md, CLAUDE.md, Rules에 반복해서 복사한 뒤 한쪽만 바뀌는 문제도 줄일 수 있다.

CLAUDE.md에는 Claude가 반복해서 필요한 것만 둔다

CLAUDE.md는 Anthropic의 공식 가이드에서 작성 기준이 특히 구체적이다.

Claude Code는 CLAUDE.md를 Conversation 시작 시 읽기 때문에 여러 작업에 넓게 적용되는 내용만 넣고 짧고 사람이 읽을 수 있게 유지하도록 권장한다. Anthropic은 각 줄마다 “이 내용을 제거하면 Claude가 실수할까?”를 확인하고 아니라면 제거하라고 안내한다.

✅ 넣기 좋은 내용	❌ 줄이는 것이 좋은 내용
Claude가 추측하기 어려운 Bash 명령	코드를 읽으면 알 수 있는 정보
기본값과 다른 Code Style	일반적인 언어 Convention
Test 방법과 선호 Test Runner	상세 API Documentation
Branch·PR Workflow	자주 변경되는 정보
프로젝트 고유 Architecture 결정	긴 Tutorial
개발 환경의 특이사항	파일별 Codebase 설명
자주 발생하는 Gotcha	`Clean Code를 작성한다` 같은 자명한 지시

Anthropic 은 CLAUDE.md가 너무 커지면 실제 규칙이 묻힐 수 있다고 설명하며, Claude가 계속 같은 실수를 한다면 파일이 너무 길거나 표현이 모호한지 확인하고 정기적으로 불필요한 내용을 제거하라고 권장한다.

AGENTS.md와 CLAUDE.md는 왜 따로 둘까

이 글에서는 둘의 책임을 다음처럼 나눈다.

`AGENTS.md`	`CLAUDE.md`
프로젝트 공통 기준	Claude Code의 작업 방식
Architecture Boundary	작업 전 확인 절차
Security·Verification 기준	구현 후 Self Review
여러 Agent가 공유할 Rule	Claude에게만 필요한 Workflow

예를 들어 CLAUDE.md는 이렇게 작성할 수 있다.

@AGENTS.md

## Development Workflow

Before editing:
1. Read the related task.
2. Inspect the existing implementation.
3. Read relevant architecture documents.
4. Identify affected modules.

After editing:
1. Run Build and Test for affected modules.
2. Review the complete diff.
3. Report changed files and verification results.

Do not commit or push unless explicitly requested.

Claude Code는 CLAUDE.md에서 @path 형식으로 다른 파일을 Import할 수 있다.
따라서 같은 Project Rule을 두 파일에 복사하기보다:

AGENTS.md
→ 프로젝트 공통 기준

CLAUDE.md
→ AGENTS.md 연결
→ Claude 전용 Workflow 추가

처럼 구성할 수 있다. 이 구분은 제품이 강제하는 공식 표준이라기보다 공통 기준의 Source of Truth를 하나로 유지하기 위한 프로젝트 설계다.

항상 필요하지 않은 Context는 따로 뺀다

CLAUDE.md에 Claude가 사용할 모든 정보를 넣을 필요도 없다.
예를 들어 DB Migration 규칙은 Migration 파일을 수정할 때는 중요하지만 일반 Service를 수정할 때는 필요하지 않다.

---
paths:
  - "backend/src/main/resources/db/migration/**"
---

# Database Migration Rules

- Never modify an already-applied production migration.
- Add a new migration for schema changes.
- Verify both upgrade and fresh-install paths.

Claude Code 는 Child CLAUDE.md를 해당 Directory의 파일을 읽을 때 가져올 수 있고, Rules 역시 특정 영역에 필요한 지침을 분리하는 데 사용할 수 있다.

Google 역시 비슷하게 Global, Project, Subdirectory 와 Just-in-Time Context 를 사용한다. 특정 Component의 지침을 모든 요청에 넣는 대신 해당 영역을 실제로 다룰 때 필요한 Context를 가져오는 방식이다.

핵심은 파일을 여러 개 만드는 것보다 어떤 정보가 언제 필요한지 나누는 것이다.

반복 작업은 Skill로 분리할 수 있다

다음 한 줄은 Skill이 아니다.

외부 API는 DB Transaction 밖에서 호출한다.

프로젝트 안에서 항상 지켜야 하는 Rule이다. 반면 다음처럼 여러 단계의 작업을 반복한다면 성격이 달라진다.

Architecture 변경 확인
        ↓
관련 문서 확인
        ↓
README 영향 확인
        ↓
코드와 문서 비교
        ↓
필요한 문서 수정

구분	답하는 질문
Rule	무엇을 지켜야 하는가?
Skill	특정 작업을 어떻게 수행하는가?

Anthropic 은 Skill을 Project·Team·Domain에 특화된 지식과 반복 Workflow를 제공하는 수단으로 설명한다. Skill의 Description 은 평소 Context에 있지만 전체 내용은 실제로 Skill이 사용될 때 로드되기 때문에, 가끔 필요한 절차를 항상 CLAUDE.md에 넣지 않아도 된다.

OpenAI의 Skill도 같은 방식으로 이름과 Description을 먼저 제공하고, 실제로 선택됐을 때 전체 SKILL.md를 읽는 Progressive Disclosure를 사용한다.

Skill은 언제 사용할지 드러나야 한다

다음 Description은 정보가 부족하다.

description: Architecture skill

대신:

description: Update architecture documentation after changes to module boundaries, data flow, or public API contracts.

처럼 무엇을 하는지와 언제 필요한지가 드러나는 편이 낫다.

Anthropic은 description을 Claude가 Skill을 자동으로 적용할지 판단하는 정보로 사용하며, OpenAI 역시 Description에 Scope와 Trigger를 명확하게 쓰도록 권장한다.

Project Context와 이번 Task도 분리한다

프로젝트 Context를 잘 구성했다고 Issue나 Prompt가 필요 없어지는 것은 아니다. 둘은 수명이 다르다.

Project Context	Task Context
여러 작업에서 계속 유지	이번 작업에서만 필요
Architecture·Security·Build 기준	Goal·Scope·Acceptance Criteria
`AGENTS.md`, `CLAUDE.md`	Issue / Prompt

예를 들어:

Provider Token은 Backend에 저장하지 않는다.
→ Project Context

Metadata 동기화에 증분 갱신을 추가한다.
→ Task Context

Project Rule을 Issue마다 반복하면 다음 작업에서 빠질 수 있다. 반대로 이번 기능에서만 필요한 요구사항을 AGENTS.md에 넣으면 이후 작업에서도 공통 Rule처럼 남는다.

그래서 Prompt에서 줄여야 하는 것은 이번 작업의 요구사항이 아니라 매번 반복되는 프로젝트 설명이다.

하나의 기능에서는 Context가 이렇게 연결된다

Metadata 동기화 기능을 예로 들면 각 Context의 역할이 더 명확해진다.

Context	들어갈 내용
`docs/architecture.md`	외부 I/O와 DB Transaction을 분리한 이유
`AGENTS.md`	외부 I/O는 Transaction 밖에서 실행
`AGENTS.md`	Provider 전용 Type은 공통 Domain에 노출하지 않음
`CLAUDE.md`	구현 전 Architecture 확인, 구현 후 Build/Test/Diff Review
`.claude/rules/`	Migration 파일을 수정할 때만 Migration Rule 적용
`SKILL.md`	Architecture 변경 시 관련 문서까지 갱신하는 절차
GitHub Issue	이번에는 Metadata 증분 동기화를 구현

모든 정보를 항상 읽히는 하나의 파일에 넣지 않는다.
공통 판단 기준은 지속적으로 제공하고, 상세한 설계 이유와 특정 작업 절차는 필요할 때 가져오며, 현재 요구사항은 Task에 남긴다.

Context 파일을 작성할 때 확인할 기준

앞의 내용을 실제 작성 기준으로 압축하면 다음 정도면 충분하다.

작성 기준	확인할 질문
코드에서 알기 어려운 정보를 우선한다	Agent가 Codebase에서 쉽게 알아낼 수 있는가?
판정 가능한 Rule을 쓴다	실제 코드와 비교해 위반 여부를 알 수 있는가?
같은 내용을 복사하지 않는다	이미 Source of Truth가 있는가?
적용 범위를 좁힌다	모든 작업에서 정말 필요한가?
긴 설명은 별도 문서로 보낸다	항상 읽어야 하는 정보인가?
Task Context와 분리한다	이번 작업이 끝난 뒤에도 유효한가?
오래된 Context를 정리한다	현재 Codebase와 여전히 일치하는가?
실제 실패를 보고 보완한다	Agent가 반복해서 잘못 판단하는 지점인가?

Meta의 사례도 이 원칙을 잘 보여준다. Context 파일을 약 25~35줄의 Navigation Guide로 유지하고, Quick Commands, Key Files, Non-Obvious Patterns, See Also에 집중했다. 또한 오래된 Context가 없는 Context보다 더 위험할 수 있기 때문에 주기적으로 Freshness를 검증했다.

처음부터 모든 예외를 예상해 Rule 수십 개를 만들 필요는 없다.

핵심 기준으로 시작
        ↓
실제 개발
        ↓
반복되는 실패 발견
        ↓
Context 보완
        ↓
오래된 규칙 정리

Context도 한 번 작성하고 끝나는 설정 파일이 아니라 프로젝트와 함께 관리해야 하는 자산에 가깝다.

파일을 많이 만드는 것이 목적은 아니다

AGENTS.md, CLAUDE.md, Rules, Skills를 모두 만드는 것이 Context Engineering은 아니다.
각 Context는 결국 하나의 질문에 답한다.

질문	Context
왜 이렇게 설계했는가?	Architecture
무엇을 지켜야 하는가?	`AGENTS.md`
Claude Code는 어떻게 작업해야 하는가?	`CLAUDE.md`
특정 코드에서만 필요한가?	Rules
특정 작업 방법을 재사용하는가?	Skills
이번에 무엇을 만들어야 하는가?	Issue / Prompt

앞선 글에서는 Agent의 역할을 어떻게 나눌 것인가를 정했다.
이번에는 그 Agent들이 어떤 프로젝트 기준을 가지고 판단하게 할 것인가를 정리했다.

같은 Repository를 공유하는 것만으로는 부족하다. 구현 Agent와 Review Agent가 같은 프로젝트를 서로 다른 Architecture로 이해하지 않도록 판단 기준까지 공유해야 한다.

이제 남은 문제는 이 Context를 실제 Repository의 어디에 배치할 것인가다.
다음 글에서는 Root와 Android, Backend처럼 Module별로 AGENTS.md와 CLAUDE.md를 구성하고, 어떤 Context가 어떤 범위에 적용되는지, Claude Code와 Codex가 실제로 의도한 지침을 읽고 있는지 확인하는 과정을 정리한다.