AI 개발

AGENTS.md·CLAUDE.md 작성법: AI 에이전트에게 규칙 가르치기

Hyeon.dev 2026. 10. 30. 14:04

회사에서도 AI 코딩 에이전트용 규칙 파일을 쓰고 있습니다. 거창한 원칙보다는 AI가 자꾸 잊어버리는 규칙을 적어 둡니다.

목차

  1. 한눈에 보기
  2. AGENTS.md와 CLAUDE.md의 차이
  3. 실제 AGENTS.md 해부
  4. 규칙이 실제로 작동한 장면
  5. 좋은 규칙의 조건 4가지
  6. 규칙과 기억은 따로 둔다
  7. 처음 쓰는 사람을 위한 템플릿
  8. 직접 해보니
  9. 마무리
  10. 자주 묻는 질문 (FAQ)

AI 코딩 에이전트는 대화를 새로 시작할 때마다 프로젝트의 사정을 모릅니다. 매번 같은 설명을 반복하지 않으려면 "이 저장소에서는 이렇게 일한다"는 규칙을 파일로 적어 두고 에이전트가 읽게 해야 합니다. 그 파일이 AGENTS.md와 CLAUDE.md입니다. 제 블로그 도구 저장소에 실제로 둔 규칙 파일을 예로 들어, 무엇을 어떻게 적었고 실제로 어떻게 작동했는지 정리합니다.

한눈에 보기

  • AGENTS.md: 여러 AI 코딩 도구가 공통으로 읽는 규칙 파일 관례
  • CLAUDE.md: Claude Code가 읽는 규칙 파일
  • 위치: 프로젝트 루트에 두면 그 저장소에만, 사용자 홈의 ~/.claude/CLAUDE.md는 모든 프로젝트에 적용
  • 좋은 규칙: 구체적인 행동으로, 확인 가능한 기준으로, 이유와 함께, 금지에는 대신 할 일까지
  • 규칙과 기억은 따로: "항상 이렇게 하라"는 규칙 파일에, "지금 상황·이번에 배운 함정"은 기억 파일에

AGENTS.md와 CLAUDE.md의 차이

두 파일은 하는 일이 같습니다. 에이전트가 작업을 시작할 때 읽고 따르는 규칙을 적어 두는 파일입니다. 차이는 어떤 도구가 읽느냐와 어디에 두느냐입니다.

파일 읽는 도구 위치 적용 범위
AGENTS.md 여러 AI 코딩 도구가 공통으로 읽는 관례 프로젝트 루트 그 저장소
CLAUDE.md Claude Code 프로젝트 루트 그 저장소
~/.claude/CLAUDE.md Claude Code 사용자 홈 모든 프로젝트

▲ 규칙 파일 위치와 적용 범위

도구마다 읽는 파일과 우선순위가 다르므로, 실제로 쓰는 도구의 문서를 한 번 확인하고 시작하는 것이 안전합니다.

실제 AGENTS.md 해부

제 블로그 도구는 OpenCode에서 도는 AI가 오케스트레이터로 작업 명세를 쓰고, 작업자 AI인 Claude Code가 구현하는 구조로 만들었습니다. 저장소 루트의 AGENTS.md는 오케스트레이터가 지킬 규칙이고, 전체 내용은 다음과 같습니다.

# TistoryBlogMaker

## For the orchestrator (OpenCode / Sisyphus)

- Delegate implementation work to the `claude_worker` tool. Give it a self-contained spec: goal, files in scope, acceptance criteria, the tests to run, and what must not change.
- After the worker returns, verify yourself: run the tests and read the diff. Send follow-ups with `resumeSessionId` instead of starting over.
- Use explore/librarian for read-only research; do not edit files yourself unless the user asks.
- If the worker reports a rate limit, an auth problem, or a billing check failure, stop and tell the user. Never retry through another model or provider.

네 줄밖에 안 되지만 줄마다 의도가 분명합니다.

  1. 구현은 작업자에게 맡기고, 명세를 함께 준다. 오케스트레이터가 직접 코드를 쓰지 않고 작업자 AI에게 넘깁니다. 이때 목표, 범위(건드릴 파일), 완료 조건(돌릴 테스트), 하지 말 것을 빠짐없이 적은 명세를 줍니다. 작업자가 다른 맥락 없이 명세만 읽고도 일할 수 있어야 합니다.
  2. 결과는 직접 검증하고, 후속 지시는 같은 세션으로. 작업자의 "완료" 보고를 그대로 믿지 않고 테스트를 실행하고 diff를 읽습니다. 고칠 점이 있으면 새로 시작하지 않고 같은 작업자 세션에 이어서 지시해 맥락을 유지합니다.
  3. 조사는 읽기 전용 에이전트로, 직접 수정은 하지 않는다. 코드를 찾아보거나 자료를 조사하는 일은 파일을 고칠 수 없는 에이전트에게 맡깁니다. 오케스트레이터 자신도 제가 시키지 않으면 파일을 직접 고치지 않습니다.
  4. 한도·인증·결제 문제가 생기면 멈추고 알린다. 사용량 한도에 걸리거나 인증, 결제 확인에서 막히면 그 자리에서 멈추고 저에게 알립니다. 다른 모델이나 서비스로 몰래 우회하지 않습니다.

규칙이 실제로 작동한 장면

이 저장소의 오케스트레이터는 백로그 파일의 한 줄을 고치는 일까지 작업자에게 넘겼습니다. "직접 파일을 고치지 않는다"는 규칙을 그대로 따른 것입니다.

여기에는 장단점이 분명히 있었습니다.

  • 장점: 모든 변경이 명세와 보고를 거칩니다. 무엇을 왜 바꿨는지 기록이 남고, 검증 단계도 빠지지 않습니다.
  • 단점: 작은 수정에도 왕복이 생겨 느립니다. 작업자를 한 번 호출하는 데 짧게는 5초, 길게는 몇 분이 걸립니다. 한 줄짜리 수정이라면 직접 고치는 편이 훨씬 빠릅니다.

어느 쪽이 맞는지는 상황에 따라 다릅니다. 이 저장소는 기록이 남는 쪽으로 정해 두었지만, 속도가 중요하다면 "한 줄 이하의 문서 수정은 직접 해도 된다" 같은 예외를 규칙에 적어 두는 방법도 있습니다.

"직접 검증한다"는 규칙도 실제로 효과가 있었습니다. 작업자가 실행 권한이 없어 테스트를 돌리지 못하고 넘긴 결과를 오케스트레이터가 직접 실행해 테스트 30개가 통과하는 것을 확인했습니다. 작업자가 쓴 글 초안의 사실 오류 두 개도 검토 단계에서 잡았습니다. 자세한 이야기는 AI 코딩 에이전트에게 일 맡기는 법에 정리했습니다.

전역 CLAUDE.md의 언어 규칙

프로젝트마다 다른 규칙은 저장소에 두고, 어디서나 같은 규칙은 사용자 홈의 ~/.claude/CLAUDE.md에 둡니다. 제가 전역 파일에 넣은 규칙 중 하나가 응답 언어입니다.

# 응답 언어

- 사용자에게 보이는 모든 텍스트(작업 중간의 짧은 진행 안내, 질문, 최종 요약 포함)는 항상 한국어로 쓴다.
- 코드, 명령어, 파일 경로, 고유 명사는 원문 그대로 둔다.
- 대화가 길어지거나 요약된 뒤에도 이 규칙을 유지한다.

"한국어로 답해"라고만 적으면 두 가지가 흔들립니다. 하나는 코드나 파일 경로까지 번역하려 드는 경우이고, 다른 하나는 대화가 길어지면 슬그머니 영어로 돌아가는 경우입니다. 그래서 예외(코드·경로는 원문 그대로)와 지속 조건(대화가 길어지거나 요약된 뒤에도)까지 적었습니다. 규칙이 흔들리는 지점을 미리 막아 두는 것입니다.

좋은 규칙의 조건 4가지

  1. 구체적인 행동으로 쓴다. "꼼꼼하게 검증하라"보다 "테스트를 실행하고 diff를 읽어라"가 낫습니다. 에이전트가 그대로 따라 할 수 있는 행동이어야 합니다.
  2. 확인 가능한 기준을 준다. "잘 동작하면 완료"가 아니라 "npm test가 통과하면 완료"처럼, 지켰는지 아닌지를 누구나 판단할 수 있어야 합니다.
  3. 이유를 함께 적는다. 이유가 있으면 에이전트가 규칙에 딱 맞지 않는 상황에서도 의도에 맞게 판단합니다. 사람이 나중에 규칙을 고칠 때도 왜 생긴 규칙인지 알 수 있습니다.
  4. 금지에는 대신 할 일을 붙인다. "다른 모델로 재시도하지 마라"만 있으면 에이전트는 막힌 채 다른 방법을 찾습니다. "멈추고 사용자에게 알려라"까지 적어야 행동이 정해집니다.

규칙과 기억은 따로 둔다

규칙 파일에 모든 것을 적다 보면 금방 길어지고, 무엇이 규칙인지 흐려집니다. 그래서 저는 성격이 다른 두 가지를 나눠 둡니다.

  • 규칙 파일(AGENTS.md, CLAUDE.md): "항상 이렇게 하라." 상황이 바뀌어도 계속 지킬 원칙입니다.
  • 기억(memory) 파일: "지금 상황이 이렇다", "이번에 이런 함정을 겪었다." 시간이 지나면 바뀌거나, 특정 작업에서 배운 사실입니다.

▲ 규칙 파일과 기억 파일 비교

실제로 기억 파일에 남긴 것은 블로그 운영 현황, 그리고 작업 중 겪은 함정들입니다. 예를 들어 PowerShell 스크립트에 Del이라는 함수를 만들어 호출했더니, PowerShell은 별칭이 함수보다 우선하기 때문에 함수 대신 기본 별칭 Del(= Remove-Item, 파일 삭제 명령)을 실행했습니다. 넘긴 인수가 경로가 아니라 CSS 선택자여서 "드라이브를 찾을 수 없습니다" 오류만 나고 지워진 파일은 없었지만, 자칫 위험할 뻔한 일이었습니다. 또 Windows PowerShell 5.1에서 한글이 든 스크립트를 실행하려면 파일을 UTF-8 BOM으로 저장해야 글자가 깨지지 않는다는 점도 남겨 두었습니다. 이런 내용은 "항상 지킬 원칙"이라기보다 겪어 본 사실이므로 규칙 파일이 아니라 기억에 둡니다.

처음 쓰는 사람을 위한 템플릿

처음부터 완벽하게 쓸 필요는 없습니다. 아래 정도로 시작해서 에이전트가 자주 어기는 것을 하나씩 더해 가면 됩니다.

# 프로젝트 이름

## 작업 방식
- 작업을 시작하기 전에 바꿀 파일 목록을 먼저 알려 준다.
- 완료 조건: npm test가 통과해야 한다. 실행하지 못했다면 그 사실을 보고한다.

## 하지 말 것
- 커밋하지 않는다. (사람이 검토한 뒤 직접 커밋한다)
- 지정하지 않은 설정 파일을 수정하지 않는다. 필요하면 이유를 적어 먼저 묻는다.
- 테스트를 건너뛰거나 지우지 않는다. 실패하면 원인을 보고한다.

## 보고 형식
- 바꾼 파일, 실행한 명령과 결과, 하지 못한 일을 적는다.

직접 해보니

가장 크게 달라진 것은 매번 프롬프트로 하던 지시가 줄었다는 점입니다. 예전에는 대화를 시작할 때마다 같은 당부를 반복했는데, 이제는 파일에 한 번 적어 두면 됩니다. 그래서 규칙 파일은 처음부터 다 채우기보다, 프롬프트로 자꾸 반복하게 되는 것부터 하나씩 옮겨 적는 편이 맞다고 생각합니다.

마무리

AGENTS.md와 CLAUDE.md는 에이전트에게 매번 반복하던 설명을 파일 하나로 옮겨 두는 도구입니다. 규칙은 구체적인 행동과 확인 가능한 기준으로 쓰고, 이유와 대신 할 일을 함께 적습니다. 지금 상황이나 겪어 본 함정은 규칙과 섞지 말고 기억으로 따로 둡니다. 규칙이 지켜지면 작은 일까지 절차를 거치느라 느려질 수 있다는 점도 알고 정하는 것이 좋습니다.

자주 묻는 질문 (FAQ)

Q. 규칙은 얼마나 길게 써야 하나요?

짧을수록 좋습니다. 처음에는 꼭 필요한 몇 줄로 시작하고, 에이전트가 실제로 자주 어기는 것부터 하나씩 추가합니다. 길어질수록 규칙끼리 부딪히거나 중요한 규칙이 묻히기 쉽습니다.

Q. AGENTS.md와 CLAUDE.md가 둘 다 필요한가요?

쓰는 도구가 어떤 파일을 읽는지에 따라 정하면 됩니다. 여러 도구를 함께 쓰는데 내용이 겹친다면, 한쪽에 내용을 두고 다른 쪽에서는 그 파일을 참조하라고 적어 두는 방식도 가능합니다. 구체적인 방법은 쓰는 도구의 문서를 확인하세요.

 

이 글은 AI(Claude)가 초안을 쓰고, 제가 경험과 의견을 채운 뒤 검토해 발행했습니다. 글에 들어간 도식도 AI와 함께 만들었습니다.