전역 CLAUDE.md와 AGENTS.md에는 무엇을 써야 할까요?

전역 CLAUDE.md와 AGENTS.md는 모든 프로젝트에서 반복해서 적용할 개인의 작업 원칙을 담는 파일입니다.

Claude Code: ~/.claude/CLAUDE.md
Codex: ~/.codex/AGENTS.md

프로젝트가 React에서 Python으로 바뀌거나, 신규 서비스에서 레거시 시스템으로 바뀌어도 유지할 수 있는 내용이어야 합니다.

특정 저장소의 빌드 명령이나 아키텍처를 설명하는 곳이 아니라, 에이전트가 어떻게 판단하고 수정하며 검증할 것인지를 정하는 곳입니다.

전역 파일에는 판단 원칙을 씁니다

전역 원칙으로 적합한 내용은 다음과 같습니다.

수정하기 전에 관련 코드와 계약을 확인합니다.
불확실한 사실을 추측하지 않습니다.
요청을 충족하는 가장 단순한 변경을 선택합니다.
관련 없는 코드를 함께 개선하지 않습니다.
완료 여부를 확인할 방법을 먼저 정합니다.
검증 결과 없이 성공했다고 말하지 않습니다.
파괴적이거나 비용이 발생하는 작업은 승인 없이 실행하지 않습니다.

이 원칙들은 언어나 프레임워크보다 상위에 있는 작업 방식입니다.

카르파시가 지적한 것도 판단 실패였습니다

안드레이 카르파시는 코딩 에이전트가 잘못된 가정을 임의로 전제하고, 불필요하게 복잡하게 구현하며, 요청과 무관한 코드까지 수정하고, 검증 가능한 목표 없이 완료했다고 판단하는 문제를 지적했습니다.

이를 커뮤니티에서 다음 네 가지 원칙으로 정리했습니다.

코딩하기 전에 이해합니다.
가장 단순한 해결책을 선택합니다.
필요한 부분만 수정합니다.
검증할 수 있는 목표를 기준으로 완료합니다.

다만 공개된 Karpathy-inspired CLAUDE.md는 카르파시가 직접 작성한 공식 파일이 아닙니다. 그의 공개적인 관찰을 커뮤니티가 실무 지침으로 재구성한 자료이므로 그대로 복사하기보다 자신의 프로젝트와 위험 수준에 맞게 사용해야 합니다.

Marcos Hernanz도 X에 공개한 짧은 AGENTS.md에 다음 세 줄을 그대로 사용한다고 밝혔습니다.

# AGENTS.md
- Do not preserve backward compatibility.
- Choose the simplest implementation that fully meets the current requirements.
- Prefer established, well-maintained libraries over custom implementations.

이 원칙 역시 그대로 복사해서는 안 됩니다. 예를 들어 하위 호환을 유지하지 않는다는 규칙은 내부 실험에는 맞을 수 있지만, 외부 API·SDK나 영속 데이터가 있는 서비스에서는 실제 사용 중인 계약을 깨뜨릴 수 있습니다.

바로 사용할 수 있는 최소 전역 원칙

# 기본 작업 원칙

- 수정하기 전에 관련 코드, 호출부, 테스트, 인터페이스와 현재 변경 사항을 확인한다.
- 저장소나 공식 문서에서 확인할 수 있는 사실은 추측하지 않는다.
- 사실, 가정과 판단을 구분하며 중요한 불확실성은 먼저 알린다.
- 요청을 완전히 충족하는 가장 단순한 변경을 선택한다.
- 요청하지 않은 기능, 추상화와 관련 없는 리팩터링을 추가하지 않는다.
- 완료 전에 외부에서 확인 가능한 검증을 실행한다.
- 실행 결과 없이 Pass, Works 또는 Completed라고 말하지 않는다.
- 파괴적 작업, 공유 상태 변경, 권한 상승과 비용 발생 작업은 승인 없이 실행하지 않는다.
- 변경 내용, 검증 결과와 검증하지 못한 항목을 구분해 보고한다.

이 정도면 전역 원칙의 역할을 충분히 수행합니다.

세부 테스트 명령, API 계약과 디렉터리 구조는 프로젝트 파일에 따로 둡니다.

전역 파일에 넣지 않을 내용

다음 내용은 전역 파일에 적합하지 않습니다.

특정 저장소의 빌드·테스트 명령
특정 프레임워크의 코딩 규칙
API나 DB Schema 계약
특정 디렉터리의 수정 방법
이번 작업의 목표와 결과 형식
Release나 Migration의 단계별 절차

이런 내용은 프로젝트 파일, 경로별 Rule, Skill 또는 작업 프롬프트에 두어야 합니다.

규칙은 반복되는 문제가 있을 때 추가합니다

전역 파일을 처음부터 완성하려고 할 필요는 없습니다.

다음 조건을 만족할 때만 규칙을 추가하는 것이 좋습니다.

여러 프로젝트에서 같은 실수가 반복됩니다.
매번 같은 수정 지시를 다시 입력합니다.
에이전트가 알면서도 같은 판단 오류를 반복합니다.
코드나 프로젝트만 바뀌고 원칙 자체는 계속 유효합니다.

반대로 에이전트가 별도 지시 없이도 안정적으로 수행하는 내용, 기존 규칙과 중복되는 내용, 더 이상 유효하지 않은 내용은 삭제합니다.

전역 파일은 많은 것을 설명하는 문서가 아니라, 반복되는 판단 실패를 최소한의 원칙으로 교정하는 문서입니다.

저장소별 계약과 명령을 정리하는 방법은 다음 글인 프로젝트 CLAUDE.md와 AGENTS.md에는 무엇을 써야 할까요?에서 이어서 설명합니다.