Claude Code AGENTS.md 사용법: 여러 코딩 에이전트 지침 하나로 관리하기

Claude Code 2.1.277부터 프로젝트에 CLAUDE.md가 없으면 AGENTS.md를 대신 읽을 수 있다. Codex, Cursor, Gemini CLI처럼 AGENTS.md를 쓰는 도구와 Claude Code를 함께 사용하는 팀이라면 비슷한 지침 파일을 두 벌 유지하던 부담을 줄일 수 있는 변화다. 다만 “파일 이름만 바꾸면 모든 환경에서 똑같이 작동한다”는 뜻은 아니다. 어떤 파일이 우선하는지, 하위 폴더 지침이 언제 붙는지, 직접 로드가 지원되지 않는 환경은 무엇인지 알아야 안전하게 옮길 수 있다.

이 글은 2026년 9월 19일 확인한 공식 릴리스·메모리 문서·내장 플러그인 설명을 바탕으로 설정과 이전 방법을 정리한다. 기능은 9월 18일 v2.1.277에 포함됐다. 관련 Hacker News 토론은 확인 시점에 605점과 214개 댓글을 기록했지만, 이는 관심의 근거이지 품질 평가는 아니다.

무엇이 바뀌었나: AGENTS.md가 기본 대체 파일이 됐다

AGENTS.md는 빌드 명령, 테스트 순서, 코드 스타일, 보안 주의사항처럼 코딩 에이전트가 작업 전에 알아야 할 내용을 적는 일반 Markdown 파일이다. 사람용 소개 문서인 README를 길게 만들지 않으면서 여러 코딩 에이전트가 같은 저장소 규칙을 읽도록 하는 것이 목적이다. AGENTS.md 공개 사이트는 6만 개가 넘는 오픈소스 프로젝트가 이 형식을 사용한다고 안내한다.

Claude Code의 새 기본값은 CLAUDE.md 또는 CLAUDE.local.md가 프로젝트 경로에 있으면 기존 파일만 읽고, 둘 다 없을 때 AGENTS.md를 읽는 방식이다. 따라서 기존 Claude Code 프로젝트의 동작을 갑자기 바꾸지 않으면서, AGENTS.md만 있는 저장소에 들어갔을 때 별도 복사본 없이 지침을 받을 수 있다. 이는 CLAUDE.md 폐지나 완전한 파일 병합이 아니라 ‘우선순위가 있는 대체 읽기’다.

CLAUDE.md가 있으면 우선하고 없을 때 AGENTS.md와 하위 지침을 읽는 구조
CLAUDE.md가 있으면 우선하고, 없을 때 AGENTS.md와 하위 지침을 단계적으로 읽는 구조

기본 우선순위: 어떤 파일을 실제로 읽는가

저장소 상태기본값에서 읽는 파일권장 대응
AGENTS.md만 있음AGENTS.md그대로 사용하고 로드 문구 확인
AGENTS.md와 CLAUDE.md가 함께 있음CLAUDE.md 계열만둘 다 필요하면 설정을 변경하거나 @import 사용
CLAUDE.local.md가 있음CLAUDE.md 계열만개인 지침과 AGENTS.md를 함께 읽도록 설정
하위 패키지에 AGENTS.md가 있음해당 폴더 파일을 Read로 열 때 추가패키지별 명령과 범위만 적기

여기서 “프로젝트 경로”는 현재 작업 디렉터리와 그 위 디렉터리를 뜻한다. CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 가운데 하나라도 있으면 기본 대체 동작은 AGENTS.md를 건너뛴다. 반면 사용자 홈의 ~/.claude/CLAUDE.md, 조직 관리 파일, .claude/rules/는 이 판단을 막지 않으며 AGENTS.md와 함께 적용될 수 있다.

시작 전 준비: 버전과 실행 환경부터 확인

  1. 버전 확인: 터미널에서 claude --version을 실행해 2.1.277 이상인지 본다.
  2. 파일 목록 확인: 저장소 루트와 현재 작업 경로 위에 CLAUDE.md, CLAUDE.local.md, AGENTS.md가 각각 있는지 찾는다.
  3. 지원 환경 확인: Anthropic 기능 플래그를 가져오지 않는 세션, Bedrock·Vertex AI·Foundry 같은 제3자 공급자 세션, 텔레메트리를 끈 환경에서는 직접 읽기가 보이지 않을 수 있다.
  4. 첫 세션 주의: 지원 버전으로 설치·업그레이드한 직후 첫 세션에는 기능이 적용되지 않을 수 있다. 새 세션을 한 번 더 시작해 확인한다.
  5. 강제 규칙 분리: 지침 파일은 모델에 전달되는 문맥이지 접근 제어 장치가 아니다. 반드시 차단해야 하는 명령은 권한 정책이나 PreToolUse 훅으로 처리한다.

완료 기준은 단순히 파일이 존재하는 것이 아니다. 기본 모드라면 대화 시작부에 AGENTS.md loaded에 해당하는 안내가 나타나고, 프로젝트 지침의 핵심 내용을 Claude가 설명할 수 있어야 한다.

가장 단순한 설정: AGENTS.md 하나만 쓰는 저장소

저장소 루트에 다음처럼 짧고 검증 가능한 내용을 둔다. 제품 소개나 장문의 아키텍처 문서를 복사하기보다, 에이전트가 작업 중 판단해야 하는 명령과 경계를 우선한다.

# Project instructions

## Setup
- Install: pnpm install --frozen-lockfile
- Dev server: pnpm dev

## Checks
- Unit tests: pnpm test
- Type and lint: pnpm check

## Boundaries
- Do not edit generated files under dist/
- Never commit .env files or real customer data
- Ask before changing database migrations

그 다음 저장소 루트에서 Claude Code를 새로 시작한다. 시작 안내에서 AGENTS.md가 로드됐는지 보고, “이 프로젝트에서 변경하면 안 되는 경로와 완료 전 실행할 검사를 요약해 줘”처럼 파일 내용을 재현하는 질문으로 확인한다. 실제 테스트 명령은 프로젝트에서 검증된 명령만 적어야 한다. 존재하지 않는 명령을 권장 형태라는 이유로 만들어 넣으면 에이전트가 잘못된 검사를 반복한다.

/config에서 네 가지 모드를 고르는 법

Claude Code 세션에서 /config를 입력하고 Project instructions 항목을 연다. 공식 문서의 네 값은 다음과 같다.

  • claude-md-or-agents-md: 기본값. CLAUDE.md 계열이 있으면 그것을, 없으면 AGENTS.md를 읽는다.
  • claude-md-and-agents-md: 두 종류를 함께 읽는다. 각 디렉터리에서 CLAUDE.md가 먼저, AGENTS.md가 뒤에 놓인다.
  • claude-md: AGENTS.md를 읽지 않고 기존 Claude 전용 파일만 사용한다.
  • managed-only: 조직이 관리하는 CLAUDE.md와 자동 메모리 중심으로 제한한다. 개인·프로젝트 파일을 줄여야 하는 통제 환경에 맞는다.

설정 변경은 다음 메시지부터 적용된다. 팀 저장소의 .claude/settings.json에 이 플러그인 옵션을 넣어도 읽히지 않는다는 점이 중요하다. 사용자 설정 ~/.claude/settings.json, --settings로 지정한 파일, 또는 관리형 설정에 둬야 한다.

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}
Project instructions 네 가지 선택과 별도의 강제 안전 게이트 구조
Project instructions의 네 가지 선택과 지침 밖의 강제 안전 게이트

기존 두 파일을 하나로 정리하는 안전한 이전 순서

  1. 중복을 비교한다. CLAUDE.md와 AGENTS.md의 빌드·테스트·스타일·금지 규칙을 표로 놓고 의미가 같은 항목을 표시한다.
  2. 공통 규칙을 AGENTS.md로 옮긴다. 여러 도구가 함께 써도 되는 명령, 완료 조건, 저장소 구조, 데이터 경계를 남긴다.
  3. Claude 전용 내용만 분리한다. 특정 Claude 기능이나 모드가 꼭 필요하면 CLAUDE.md에 @AGENTS.md를 먼저 적고 아래에 전용 내용을 둔다.
  4. 한 가지 호환 방식을 고른다. 직접 로드가 지원되는 환경만 쓴다면 CLAUDE.md를 제거할 수 있다. Bedrock 등 제한 환경이 섞여 있다면 import 파일을 유지하는 편이 안전하다.
  5. 예전 우회책을 제거한다. SessionStart 훅이 AGENTS.md 전체를 출력했다면 이중 주입을 피하도록 없앤다. 심볼릭 링크는 유지해도 한 번만 읽지만 Windows 팀은 import가 더 예측 가능하다.
  6. 새 세션에서 검증한다. 기존 세션을 이어 쓰지 말고 새로 열어 로드 상태와 핵심 규칙을 확인한다.

CLAUDE.md에 @AGENTS.md를 넣는 방식은 여전히 유효하다. 직접 읽기를 지원하지 않는 세션에서도 작동하고, Claude 전용 보충 지침을 같은 파일에 이어 쓸 수 있다. 단순히 “AGENTS.md를 읽어라”라고 문장으로 지시하는 것보다 import가 확실하다.

모노레포에서는 하위 지침을 작게 유지한다

루트 AGENTS.md에는 전 저장소 공통 규칙을 두고, apps/web/AGENTS.md나 packages/api/AGENTS.md에는 해당 영역에서만 유효한 명령을 적는다. Claude Code는 기본 모드에서 하위 디렉터리의 텍스트 파일을 Read 도구로 열 때 그 경로의 AGENTS.md를 붙인다. 가까운 지침이 더 구체적인 작업 문맥을 제공하지만, 서로 모순되는 규칙을 많이 만들면 모델이 임의로 선택할 수 있다.

좋은 하위 파일은 “이 패키지는 Vitest를 쓴다”, “이 디렉터리의 생성 코드는 직접 수정하지 않는다”, “변경 후 이 명령을 실행한다”처럼 범위와 확인 방법이 분명하다. 루트 파일의 공통 보안 규칙을 매 패키지에 복사하면 토큰을 낭비하고 수정 불일치를 만든다.

세 가지 실용 예시와 검토 기준

1. Codex와 Claude Code를 함께 쓰는 소규모 팀

목표는 빌드와 PR 규칙을 한 파일에서 공유하는 것이다. AGENTS.md에 공통 명령과 완료 체크리스트를 두고, CLAUDE.md가 없다면 기본 대체 모드를 사용한다. 검토할 때 두 도구가 같은 테스트 명령과 금지 경로를 설명하는지 확인한다. 모델별 말투나 추론 방식까지 같아질 것이라고 기대하면 안 된다.

2. 개인 설정과 팀 규칙을 함께 유지하는 개발자

팀 규칙은 AGENTS.md에 커밋하고 개인 메모는 CLAUDE.local.md에 둔다. 기본값에서는 local 파일 때문에 AGENTS.md가 빠지므로 Project instructions를 claude-md-and-agents-md로 바꾼다. 검토 기준은 개인 지침이 팀의 보안·테스트 규칙을 덮어쓰지 않는지, 두 파일 모두 다음 메시지에서 적용되는지다.

3. 여러 패키지를 가진 모노레포

루트에는 공통 설치와 CI 기준, 하위 파일에는 패키지별 검사만 둔다. 루트에서 새 세션을 시작한 뒤 서로 다른 두 패키지의 파일을 각각 읽게 하고 적용 명령을 질문한다. 기대 산출물은 패키지마다 다른 검사 목록이며, 읽지 않은 하위 디렉터리 규칙을 이미 적용했다고 주장하면 실패로 본다.

자주 막히는 상황과 해결 순서

  • AGENTS.md가 로드되지 않는다: 먼저 버전을 확인하고, 현재 경로 위에 CLAUDE.md나 CLAUDE.local.md가 숨어 있는지 찾는다. 그다음 /config 항목과 내장 agents-md 플러그인 활성 상태를 본다.
  • 설정 항목 자체가 없다: 첫 업그레이드 세션을 닫고 새 세션을 시작한다. 그래도 없으면 Bedrock·Vertex·Foundry, 텔레메트리 비활성, 조직 훅 제한 여부를 확인하고 CLAUDE.md의 @AGENTS.md import로 우회한다.
  • 두 파일이 충돌한다: 둘 다 읽기 모드에서 같은 주제의 규칙을 한 파일로 합치고, Claude 전용 예외만 별도로 남긴다. 더 구체적이라는 이유로 상충 규칙을 방치하지 않는다.
  • /memory에서 AGENTS.md가 보이지 않는다: 직접 로드된 AGENTS.md는 Memory files 목록에 표시되지 않는 것이 공식 차이점이다. 시작 안내나 프로젝트 지침 요약으로 확인한다.
  • --add-dir의 지침이 빠진다: 추가 디렉터리의 AGENTS.md는 현재 직접 로드 대상이 아니다. 필요한 내용을 import하거나 작업 루트 구조를 조정한다.

보안과 비용: 지침 파일은 통제 장치가 아니다

AGENTS.md와 CLAUDE.md는 모델에 전달되는 지침이다. “운영 DB를 수정하지 말 것”이라고 써도 기술적으로 명령 실행을 차단하지 않는다. 파괴적 명령, 비밀 파일, 외부 네트워크, 배포 권한은 샌드박스·권한 정책·PreToolUse 훅·CI 보호 규칙으로 막아야 한다. 지침에는 안전한 기본 흐름과 승인 조건을 적고, 실제 강제는 별도 계층이 맡는 것이 좋다.

파일이 길수록 세션 문맥을 더 사용한다. 반복 설명과 오래된 명령은 지우고, “무엇을 실행하며 어떤 결과를 통과로 볼지”에 집중한다. 모노레포는 하위 파일로 범위를 좁히되 공통 규칙을 복제하지 않는다.

최종 체크리스트

  • Claude Code가 2.1.277 이상인지 확인했다.
  • 루트와 상위 경로의 CLAUDE.md, CLAUDE.local.md, AGENTS.md를 모두 확인했다.
  • 기본 대체, 둘 다 읽기, Claude 전용, 관리형 전용 중 팀에 맞는 모드를 골랐다.
  • 지원되지 않는 공급자나 첫 업그레이드 세션의 제한을 고려했다.
  • 새 세션에서 로드 안내와 핵심 규칙 요약을 확인했다.
  • 지침과 강제 보안 제어를 분리했다.
  • 예전 import·심볼릭 링크·SessionStart 우회책의 중복 여부를 점검했다.

여러 코딩 에이전트를 오갈 때 가장 실용적인 출발점은 공통 빌드·테스트·보안 규칙을 AGENTS.md에 모으고, Claude 전용 내용만 최소한으로 남기는 것이다. 설치와 패키징까지 팀 단위로 재사용하고 싶다면 Claude Code 플러그인 만들기 가이드도 함께 참고할 수 있다.

English version: Claude Code AGENTS.md Guide: Share One Instruction File Across Coding Agents

공식 자료

자료 확인일: 2026년 9월 19일

댓글

댓글 쓰기

이 블로그의 인기 게시물

Diagram Design 사용법: Claude Code·Codex로 다이어그램 만드는 순서

이미지
Diagram Design은 Claude Code나 Codex 같은 코딩 에이전트에 다이어그램 제작 규칙을 더하는 외부 스킬·플러그인입니다. 별도의 웹 편집기에서 도형을 끌어다 놓는 방식이 아니라, 설명할 구조와 목적을 전달하면 에이전트가 HTML·SVG 기반 결과물을 만들도록 돕습니다. 자동화 흐름을 문서에 넣고 싶은데 상자 배치와 색상 정리에 시간을 쓰고 있다면 살펴볼 만합니다. 다만 보기 좋은 그림과 정확한 설계는 다릅니다. 여기서는 설치부터 첫 요청, 결과 검토와 내보내기까지 구분해 정리합니다. 자료 확인: 2026년 9월 16일 · 공식 README·사용 가이드 기반 안내입니다. 먼저 알아둘 세 가지 Diagram Design 자체가 AI 모델은 아닙니다. 사용할 코딩 에이전트가 먼저 준비돼 있어야 합니다. 처음에는 작은 흐름 하나를 정적 HTML로 만든 뒤 검토하는 편이 좋습니다. 공개 저장소라는 사실과 모델 사용료가 무료라는 말은 다릅니다. 1. 어떤 작업에 쓰면 좋을까? 공식 문서는 아키텍처, 흐름도, 시퀀스, 데이터 모델 등 여러 유형을 제공합니다. 기본 결과는 정적 HTML이며, Mermaid·draw.io·Excalidraw 자료를 선택한 크기와 상세도에 맞춰 다시 그리는 기능도 안내합니다. 모든 요소를 그대로 옮기는 단순 변환과는 다릅니다. 설명할 내용 선택 기준 문의 처리나 업무 자동화 순서 처리 단계와 분기가 보이는 흐름도 앱·서버·데이터베이스의 관계 구성 요소와 연결을 보여주는 아키텍처 시간 순서에 따른 요청과 응답 메시지 순서를 구분하는 시퀀스 옵션 두 개의 장단점 그림보다 비교표가 명확할 수 있음 공식 갤러리의 콘텐츠 사이트 아키텍처 예제. © 2025 Cathryn Lavery, MIT License. 원본 예제 보기 이 예제는 단순한 상자 나열이 아닙니다. Reader에서 들어온 요청, Astro Origin이 읽는 MDX 문서와 CMS, 다시 돌아가는 응답을 선 종류와 라벨로 구분합니다. 자신의 결과물에서도 ...
자세한 내용 보기

OpenAI Agents API란? 관리형 에이전트 실행 환경 이해하기

이미지
모델에 질문을 한 번 보내는 것과, 파일을 읽고 도구를 호출하며 여러 단계의 작업을 끝내는 에이전트를 운영하는 것은 다른 문제입니다. 후자에서는 작업 기록, 실행 권한, 중간 실패, 결과물 보관까지 설계해야 합니다. OpenAI Agents API는 Codex의 에이전트 하네스를 OpenAI가 관리하는 API로 사용할 수 있게 하는 선택지 입니다. OpenAI는 2026년 9월 10일 Agents API 공개 베타를 발표했습니다. 이 글에서는 설치 명령을 나열하기보다 무엇을 맡길 수 있는지, Agents SDK·Responses API와 어떻게 다른지, 어떤 작은 업무로 도입 여부를 판단하면 좋을지 살펴봅니다. 자료 확인: 2026년 9월 16일 · 공식 발표와 개발자 문서 기준 먼저 기억할 핵심 관리형 하네스는 모델 자체가 아니라 작업을 이어 가고 도구를 쓰도록 조율하는 실행 기반입니다. 실행 환경을 선택할 수 있어도 도구 권한, 외부 시스템 접근, 승인 기준은 개발자가 정해야 합니다. 긴 작업에 유용한 선택지이지만, 단발성 호출까지 모두 옮길 필요는 없습니다. 1. 관리형 하네스는 무엇을 관리할까? 하네스는 에이전트가 입력을 받고, 필요한 도구를 사용하고, 중간 결과를 다음 단계에 반영하도록 돕는 실행 틀입니다. 공식 개요는 세션, 작업 조율, 컨텍스트 압축, 복구를 OpenAI가 관리하고 애플리케이션은 도구와 실행 환경을 제공하거나 선택한다고 설명합니다. 따라서 “더 강한 모델을 호출하는 API”보다는 에이전트 운영 책임을 나누는 방식 으로 이해하는 편이 정확합니다. Agent: 사용할 모델, 지시문, 도구와 MCP 서버를 정하는 구성입니다. Environment: 파일을 다루고 명령을 실행하는 선택적 샌드박스나 컴퓨터 환경입니다. Session: 여러 차례 입력을 받으며 작업을 이어 갈 수 있는 지속적인 에이전트 인스턴스입니다. Events와 items: 세션에 전달된 입력과 생성된 출력을 추적하는 자료입니다. 예를 들어 첫 요청에...
자세한 내용 보기

Notion Agent Skills 사용법: 팀의 반복 업무를 재사용 가능한 지침으로 만드는 법

이미지
AI에게 매번 같은 형식의 회의 요약, 검토, 초안을 요청한다면 프롬프트를 복사해 붙이는 방식은 오래 버티기 어렵습니다. 누군가가 잘 만든 요청문은 개인의 노하우로 남고, 팀원마다 결과 형식도 달라지기 쉽습니다. 2026년 9월 15일 공개된 Notion 3.7의 Agent Skills 는 이 문제를 “재사용 가능한 지침 페이지”로 풀려는 기능입니다. 한 번 정의한 업무 방식과 참고 자료를 스킬로 저장하고, 필요할 때 Notion Agent가 불러 쓰도록 합니다. 이 글은 Notion을 이미 문서·데이터베이스 허브로 쓰는 팀이 스킬을 어디에 쓰면 좋은지, 기존 Custom Agent와 어떻게 구분할지, 권한과 비용을 무엇부터 점검할지를 설명합니다. 회의록 정리 스킬에 넣을 지침서 예시. 기능 설명보다 어떤 입력을 받고 어떤 기준을 지킬지 먼저 정합니다. 먼저 이해할 것: 스킬은 ‘반복 가능한 일하는 방식’이다 Notion은 스킬을 특정 유형의 일을 수행하도록 Notion AI를 가르치는 재사용 가능한 지침이라고 설명합니다. 스킬의 본체는 특별한 코드 파일이 아니라 Notion 페이지 입니다. 따라서 기존 문서처럼 제목을 붙이고, 소유자를 정하고, 동료와 공유하고, 수정 이력을 관리할 수 있습니다. 예를 들어 “월간 사업 검토를 우리 팀의 지표 순서로 작성한다”, “제품 제안서를 디자인·개발 기준으로 비평한다”, “신규 입사자 체크리스트를 회사 정책에 맞게 만든다” 같은 규칙을 한 페이지에 담습니다. 핵심은 단순한 템플릿과 다릅니다. 템플릿이 빈 문서의 모양을 복제한다면, 스킬은 Agent가 요청을 해석할 때 참고할 판단 기준과 작업 순서 를 제공합니다. 평소에는 Agent 채팅에서 / 를 입력해 원하는 스킬을 고르고, 필요한 맥락을 덧붙여 실행할 수 있습니다. 자동 사용은 설명(Description)이 있는 스킬 데이터베이스의 스킬에서 기본적으로 켜집니다. 독립된 스킬 페이지는 먼저 스킬 데이터베이스로 옮기고 설명을 추가해야 하며, Agent는 이 설...
자세한 내용 보기