agents-md: Claude Code AGENTS.md를 프로젝트 지침으로 불러오기
CLAUDE.md처럼 AGENTS.md 파일을 프로젝트 지침으로 불러오는 모드. /config에서 네 가지 모드를 고릅니다.
권한
- 도구 호출 가로채기Claude가 하는 모든 도구 호출을 볼 수 있고(tool.call / tool.check), 이를 차단하거나 변경할 수 있습니다.
- UI 변경Claude Code 화면에 밴드, 패널, 상태 텍스트, 토스트를 그립니다(ui.render / $.ui.*).
- 테스트 버전
- v2.1.310
- 마지막 테스트
- 필요 버전
- Claude Code ≥ 2.1.287
- 표시 위치
- 없음
Claude Code 안에서 설치:
git clone https://github.com/anthropics/claude-code
claude --plugin-dir ./claude-code/mods/agents-md이 모드는 무엇을 하나요?
agents-md는 Claude Code AGENTS.md 지원을 더하는 Anthropic의 모드입니다(anthropics/claude-code). 많은 저장소가 에이전트 지침을 AGENTS.md에 적어 두지만 Claude Code가 읽는 것은 CLAUDE.md입니다. 이 모드는 AGENTS.md 파일을 프로젝트 지침 파일로 Claude Code에 넘겨, 모델이 CLAUDE.md와 같은 위치에서 같은 틀로 보게 합니다.
옵션 하나, instructionFiles가 무엇을 불러올지 정합니다.
claude-md:CLAUDE.md만. 지금의 Claude Code와 같고 모드는 아무것도 더하지 않습니다.claude-md-or-agents-md(기본값): 자체CLAUDE.md가 없는 프로젝트는 대신AGENTS.md파일을 불러옵니다.claude-md-and-agents-md: 모든AGENTS.md를CLAUDE.md와 함께 불러옵니다.managed-only: 프로젝트와 본인의 지침 파일은 버리고, 조직의 관리형CLAUDE.md와 메모리만 남깁니다.
파일은 파일 시스템 루트부터 작업 디렉터리까지 올라가며 찾고, AGENTS.md와 .claude/AGENTS.md가 대상입니다. Claude가 하위 디렉터리의 파일을 읽으면 그 디렉터리의 AGENTS.md가 읽기 결과에 붙습니다. Claude Code가 중첩된 CLAUDE.md에 하는 것과 같습니다. 모드는 화면에 아무것도 그리지 않으며, 효과는 모델이 아는 내용에 나타납니다.
데모
녹화에서는 작은 데모 프로젝트에서 이 모드를 불러온 Claude Code를 시작합니다. 클립이 시작되기 전에 숨겨진 준비 줄이 프로젝트에 짧은 AGENTS.md를 만듭니다(규칙 두 개: 커밋 메시지는 DEMO-123 같은 티켓 ID로 시작하고, 커밋 전에 npm test를 실행). 프로젝트에 CLAUDE.md는 없습니다. 클립에서는 "Without reading any file: what does my AGENTS.md say about commit messages? One sentence."라고 묻습니다. Claude는 약 2초 만에, 도구 호출 없이 커밋 메시지가 DEMO-123 같은 티켓 ID로 시작한다고 답합니다. 파일이 이미 컨텍스트에 있기 때문입니다.
설치
설치 블록의 방법 중 아무거나 쓰면 됩니다. 모두 anthropics/claude-code 저장소에서 설치합니다. 이 저장소에는 이 플러그인을 나열한 marketplace.json이 없어서 설치 블록은 저장소 자체를 소스로 씁니다. 기본 모드는 설정이 필요 없습니다. AGENTS.md가 있고 CLAUDE.md가 없는 프로젝트에서 세션을 시작하면 됩니다.
$ install agents-md
Claude Code 2.1.287 이상 필요
작성자의 마켓플레이스에서 설치: anthropics/claude-code
1.설치하지 않고 사용해 보기
git clone https://github.com/anthropics/claude-code claude --plugin-dir ./claude-code/mods/agents-md한 세션에서만 모드를 불러옵니다. 설정에는 아무것도 추가되지 않습니다.
작동 방식
hooks/hooks.json에 나열된 모듈은 hooks/register.ts 하나뿐이고, hooks/ 아래의 나머지는 그것이 가져오는 작은 보조 모듈입니다. 불러오는 두 모드에서 prompt.context 훅은 Claude Code가 이미 불러온 지침 파일을 받아 $.fs.ancestors로 위쪽의 AGENTS.md를 찾고, 새 파일을 project 파일로 더한 목록을 돌려줍니다. 탐색 부분은 hooks/register.ts의 다음 코드입니다.
const found = isClaudeProject
? NONE
: await $.fs.ancestors({ names: Names.AGENTS_NAMES }).catch(() => {
isWalkFailed = true
return NONE
})
const added = Files.unseenFiles(Files.filesOf(found), handed)unseenFiles는 Claude Code가 이미 경로를 가진 파일, 또는 넘겨받은 프로젝트 파일과 본문이 같은 파일(예: AGENTS.md로 심볼릭 링크된 CLAUDE.md)을 뺍니다. Read의 tool.call 훅은 먼저 읽기가 끝나게 둔 뒤, 프로젝트 루트 아래의 파일이면 루트와 그 파일 사이 각 디렉터리의 AGENTS.md를 Contents of <path>: 형태로 붙입니다. 에이전트 루프마다 한 번만 붙입니다. fork용 agent.spawn 훅은 부모가 이미 보낸 집합을 복사해, fork가 같은 파일을 두 번 받지 않게 합니다.
사용자 지정
옵션은 /config의 "Project instructions" 행이며 네 값 중에서 고르는 선택기입니다. 직접 설정하려면 사용자 설정, --settings, 관리형 설정에 적습니다(프로젝트의 .claude/settings.json은 플러그인 옵션으로 읽히지 않습니다).
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}claude --plugin-dir mods/agents-md로 실행하면 같은 항목의 키는 "agents-md"입니다. 예전 키 projectInstructions는 instructionFiles가 기본값이 아닌 값으로 설정되기 전까지 계속 인정됩니다. 작성자의 README는 AGENTS.md가 CLAUDE.md와 여전히 다른 여덟 가지를 나열합니다. 예를 들어 --add-dir 디렉터리는 AGENTS.md를 제공하지 않고, /memory도 이 파일들을 알지 못합니다.
권한 및 안전
플러그인이 실행할 수 있는 모든 파일을 읽었습니다. plugin.json, hooks/hooks.json, hooks/register.ts, 그것이 가져오는 hooks/ 아래의 모든 보조 모듈, 그리고 테스트입니다. package.json, 설치 스크립트, 바이너리, 번들된 코드는 없고 소스에 ASCII가 아닌 문자도 없습니다.
- 파일을 읽습니다.
$.fs.ancestors가 디렉터리를 거슬러 올라가며AGENTS.md와.claude/AGENTS.md를 읽습니다(CLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md가 있는지도 확인합니다). 그 내용이 프로젝트 지침으로 모델에 전달되므로, 믿을 수 없는AGENTS.md는CLAUDE.md처럼 Claude를 좌우할 수 있습니다. - 환경 변수를 읽습니다.
HOME,USERPROFILE,CLAUDE_CODE_SIMPLE,CLAUDE_CODE_DISABLE_ATTACHMENTS이며,~경로를 풀고 Claude Code가 아무것도 첨부하지 않는 실행에서 첨부를 건너뛰는 용도뿐입니다. 환경 변수를 쓰지는 않습니다. - 도구 호출을 가로챕니다.
Read의tool.call훅과 fork용agent.spawn훅은 호출이 끝나기를 기다렸다가 결과를 돌려주며, 읽기가 성공했을 때만 컨텍스트를 덧붙입니다. 호출을 거부하지는 않습니다.claude plugin validate는 두 훅에.catch가 없다고 알립니다. - 텔레메트리. 개수와 고정된 선택지(모드, 파일 수와 가져오기 수, 총 길이, 몇 가지 플래그)로
$.telemetry.log와$.telemetry.mark를 호출합니다. README에 따르면 경로와 본문은 담기지 않으며, Anthropic의 telemetry 플러그인이 없으면 버려집니다. 그 플러그인은 확인하지 않았습니다. - 네트워크, 프로세스, 쓰기, 데몬이 없습니다.
fetch, 셸,$.fs쓰기, 백그라운드 타이머를 쓰지 않습니다.$.ui.log로 디버그 로그 한 줄no CLAUDE.md found; AGENTS.md loaded: <paths>만 남깁니다. - 라이선스. 저장소의
LICENSE.md는 "© Anthropic PBC. All rights reserved"이며 사용은 Anthropic 상업 약관을 따릅니다. 그래서 이 페이지는redistributable: false이고, 코드를 링크만 할 뿐 미러링하지 않습니다.
claude plugin validate는 오류를 보고하지 않았습니다. 나온 것은 플러그인 디렉터리의 "아이콘 없음" 비차단 경고, 위의 .catch 없음 두 건, README에 설치 줄이 없다는 조언뿐입니다. 작성자의 테스트 5개는 Claude Code 2.1.310에서 모두 통과했습니다.
- 도구 호출 가로채기
- Claude가 하는 모든 도구 호출을 볼 수 있고(tool.call / tool.check), 이를 차단하거나 변경할 수 있습니다.
- UI 변경
- Claude Code 화면에 밴드, 패널, 상태 텍스트, 토스트를 그립니다(ui.render / $.ui.*).
호환성 및 문제 해결
macOS의 Claude Code 2.1.310에서 확인했습니다(validate, 테스트, 데모 녹화). README는 이를 내장 플러그인(agents-md@builtin)으로 설명하므로, 이를 포함한 Claude Code에서는 이미 불러오고 있을 수 있습니다. /plugin이 내장 항목을 보여 주며 거기서 끌 수 있습니다. AGENTS.md가 읽히지 않는다면 다음을 확인하세요.
- 루트부터 작업 디렉터리 사이에
CLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md가 있는지. 기본 모드에서는 하나만 있어도 모드가 물러납니다. /config의 옵션이claude-md나managed-only가 아닌지.--bare나--safe-mode실행, 또는CLAUDE_CODE_DISABLE_CLAUDE_MDS가 설정된 경우 Claude Code는 지침 파일을 불러오지 않습니다.CLAUDE_CODE_DISABLE_ATTACHMENTS가 있으면 중첩 첨부가 생략됩니다.- 씬 클라이언트에서는 아무것도 찾지 못합니다. 작업 공간 파일이 원격에 있기 때문입니다.
- 옵션을 바꾼 뒤 새 파일은 Claude Code가 다음에 만드는 컨텍스트에서 도착합니다. 다음 턴,
/clear, 또는 압축 뒤입니다.
자주 묻는 질문
- 이 모드 없이도 Claude Code가 AGENTS.md를 읽나요?
- 모드의 README에 따르면 엔진은 CLAUDE.md만 불러오고, 플러그인이 그 위에 AGENTS.md를 더합니다. 옵션을 claude-md로 두면 플러그인은 아무것도 더하지 않고 CLAUDE.md는 평소처럼 불러옵니다.
- CLAUDE.md와 AGENTS.md가 둘 다 있으면 어떻게 되나요?
- 기본값인 claude-md-or-agents-md에서는 루트부터 작업 디렉터리 사이 어디에든 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 있으면 모드가 손을 떼니다. claude-md-and-agents-md에서는 둘 다 불러오되, CLAUDE.md가 이미 가져오거나 링크한 AGENTS.md는 건너뜁니다.
- AGENTS.md 내용이 어딘가로 전송되나요?
- 코드는 네트워크 호출도 명령 실행도 하지 않습니다. 개수(파일 수, 가져오기 수, 총 길이, 모드)만 telemetry에 넘기며, README에 따르면 이 기록은 Anthropic의 telemetry 플러그인이 설치된 환경에만 존재하고 경로나 파일 내용은 담기지 않습니다.
- 모드는 어떻게 바꾸나요?
- /config의 "Project instructions" 행에서 값을 고르거나, 사용자 설정의 pluginConfigs 아래에 instructionFiles를 지정합니다. 바꾸면 모듈이 다시 로드되고, 엔진이 다음에 만드는 컨텍스트부터 새 모드가 적용됩니다.
- 이 코드를 내 플러그인에 재사용해도 되나요?
- 복사해서 쓸 수는 없습니다. 저장소의 LICENSE.md는 모든 권리 보유이며 Anthropic 상업 약관을 따른다고 적혀 있으므로, 이 페이지는 코드를 링크만 하고 미러링하지 않습니다.
# 관련 모드
추천Context Inspector
Claude Code 컨텍스트 창을 무엇이 채우는지, 재읽기와 중복이 얼마나 되는지, 압축이 무엇을 남겼는지 보여 줍니다.
- 상태 표시줄
- 패널
- 토스트
- 파일 쓰기
- 도구 호출 가로채기
- 프롬프트 읽기
- UI 변경
- 명령어/도구 추가
v2.1.303에서 테스트됨
더 보기: 타이머, 할 일, 스탠드업.