Claude Code 9월 업데이트 총정리 - AGENTS.md 지원·/doctor prompt-audit·모델 잠금(deniedModels)·플러그인 디렉터리 포털까지, 지금 바꿔볼 설정 🛠️

안녕하세요! Mojangcam입니다 😎

지난주에 Claude Opus 5.5 출시 소식을 전하면서 "v2.1.280부터 기본 모델이 바뀌었다"고 말씀드렸죠. 그런데 Opus 5.5 뉴스에 가려서 조용히 지나간 업데이트가 9월에 꽤 많았어요. v2.1.277부터 v2.1.283까지 일주일 사이에 버전이 7개나 올라갔거든요.

그중에서 "이건 내 설정을 한 번 들여다봐야겠다" 싶은 것만 골라 정리해 볼게요. 이번 편에서 다루는 건 이 다섯 가지예요.

• AGENTS.md 지원 (v2.1.277) - 이제 CLAUDE.md 없이도 다른 코딩 에이전트용 지시 파일을 그대로 읽어요
• /doctor prompt-audit (v2.1.283) - 내 CLAUDE.md·스킬·에이전트에 낡은 지시가 남아 있는지 점검
• 모델 잠금 설정 deniedModels·availableModelsMatch (v2.1.283) - 팀 관리자용, 새 모델이 나와도 자동으로 풀리지 않게
• 플러그인 디렉터리 제출 포털 (9월 25일 공개) - 내가 만든 플러그인·MCP 커넥터를 Claude 디렉터리에 올리는 길
• 그 밖의 소소한 변화 - 커밋 서명 끄기, 넓은 터미널 본문 폭, 서드파티 프로바이더 오토 모드 기본값 등

왜 이게 중요하냐면요. 모델 뉴스는 안 봐도 며칠 뒤에 다 알게 되지만, 설정 키가 새로 생기고 기본 동작이 바뀌는 건 모르고 지나가면 그냥 손해거든요. 특히 AGENTS.md는 Cursor·Codex 같은 다른 도구와 프로젝트를 같이 쓰는 분에게, prompt-audit는 CLAUDE.md를 오래 굴려온 분에게 바로 도움이 됩니다 🙌

📌 확인한 환경

• Claude Code v2.1.283 (2026-09-25 배포, 이 글을 쓰는 9월 28일 기준 npm 최신) - 공식 체인지로그와 문서(code.claude.com/docs) 기준으로 정리했어요
• 제가 글을 준비한 라즈베리파이에는 v2.1.282까지 설치돼 있어서, v2.1.283 기능(prompt-audit·모델 잠금)은 문서 기준으로 설명하고 실행 화면은 발행 전에 윈도우 PC에서 캡처할 예정이에요
• Claude 구독(Pro·Max·Team) 기준. Amazon Bedrock·Vertex AI·Microsoft Foundry로 쓰시는 분은 AGENTS.md 절의 주의 사항을 꼭 보세요

버전부터 맞추고 시작할게요.

claude update
claude --version

📌 한눈에 보기 - 9월 셋째·넷째 주 업데이트 표

🧩 1. AGENTS.md 지원 - CLAUDE.md 없이도 프로젝트 지시를 읽어요 (v2.1.277)

🧠 뭐가 달라졌나

AGENTS.md는 여러 AI 코딩 도구가 함께 읽기로 한 공통 지시 파일이에요. 지금까지 Claude Code는 CLAUDE.md만 봤기 때문에, 팀에서 AGENTS.md로 규칙을 관리하면 CLAUDE.md에 @AGENTS.md를 적어 두거나 심볼릭 링크를 걸어야 했죠.

v2.1.277부터는 그런 우회 없이 저장소에 AGENTS.md만 있으면 Claude가 프로젝트 지시로 읽어요. 공식 문서의 기본 동작을 표로 옮기면 이렇습니다.

하나씩 뜯어볼게요 💡

• 기본은 "둘 중 하나" : CLAUDE.md가 하나라도 있으면 AGENTS.md는 무시돼요. 둘을 같이 읽게 하려면 아래 설정을 바꿔야 해요
• ~/.claude/CLAUDE.md는 카운트 안 함 : 내 홈 폴더의 개인 CLAUDE.md, 조직의 관리 CLAUDE.md, .claude/rules/는 "CLAUDE.md가 있다"는 판정에 들어가지 않고 AGENTS.md와 함께 계속 로드돼요
• 세션 시작 시 알려줌 : 대화 창에 no CLAUDE.md found; AGENTS.md loaded: /경로/AGENTS.md 한 줄이 떠요
• 하위 폴더도 같은 규칙 : Claude가 하위 폴더 파일을 Read 도구로 열 때, 그 폴더에 CLAUDE.md 계열이 없으면 그 폴더의 AGENTS.md를 읽어요
• 읽지 않는 것 : AGENTS.local.md, AGENTS.override.md, .agents/ 폴더 안의 파일

🛠️ 둘 다 읽게 하기 - /config의 Project instructions

세션에서 /config를 열고 Project instructions 항목을 고르면 돼요. 값은 네 가지예요.

설정 파일로 고정하고 싶으면 ~/.claude/settings.json에 이렇게 적어요. 내장 플러그인 agents-md의 옵션이라 pluginConfigs 아래에 들어가는 게 포인트예요.

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

• agents-md@builtin : AGENTS.md 읽기를 담당하는 내장 플러그인 ID. /plugin에서 이 플러그인을 끄면 AGENTS.md 지원 자체가 꺼져요
• instructionFiles : 위 표의 네 값 중 하나
• 이 키는 사용자 설정·--settings·관리 설정에서만 먹어요. 프로젝트의 .claude/settings.json이나 settings.local.json에 넣으면 무시됩니다
• 바꾸면 다음 메시지부터, 그리고 새 세션마다 적용돼요

💡 우회법을 쓰고 있었다면 정리하기

💬 주의 1 - Bedrock·Vertex·Foundry : v2.1.281 전에는 이런 환경(그리고 텔레메트리를 끈 세션)에서 AGENTS.md를 못 읽었어요. v2.1.281 이상으로 올리면 돼요.

💬 주의 2 - CLAUDE.local.md 함정 : "AGENTS.md로 팀 규칙을 관리하는 프로젝트에 내 개인 메모용 CLAUDE.local.md를 추가"하면, 그 순간 Claude는 AGENTS.md를 안 읽어요. 이때는 Project instructions를 claude-md-and-agents-md로 바꿔 주세요.

제대로 읽혔는지는 /memory나 /context에서 AGENTS.md 경로가 보이는지로 확인해요 (v2.1.280부터 목록에 표시돼요).

🛠️ 2. /doctor prompt-audit - 낡은 지시가 남아 있는지 점검하기 (v2.1.283)

🧠 왜 필요한가

CLAUDE.md는 한 번 쓰고 잊기 쉬운 파일이에요. 그런데 그 사이 모델은 Opus 4 → 5 → 5.5로 바뀌었죠. 옛 모델을 달래려고 넣었던 "반드시!! 꼭!!" 식의 강조, 이제는 없는 파일 경로, 서로 모순되는 규칙 두 개가 그대로 남아 있으면 오히려 지시 준수율이 떨어져요. 프롬프트 잘 쓰는 법 글에서도 "모호하거나 충돌하는 지시가 가장 큰 적"이라고 했었죠.

v2.1.283 체인지로그 원문은 이래요.

Added /doctor prompt-audit (also /checkup prompt-audit) to audit your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models

같은 버전에서 개선 항목으로 "낡은 경로, 없는 명령, 서로 모순되는 지시 파일을 보고서 맨 위에 올리고, Claude Code 문서에 있는 thinking 키워드는 지우지 않는다"는 내용도 들어갔어요.

🛠️ 실행하기

세션 안에서 한 줄이면 돼요.

/doctor prompt-audit

• /doctor : 설치 상태·설정 파일 오류·안 쓰는 스킬/MCP/플러그인·느린 훅을 점검하는 기존 명령. 별칭은 /checkup
• prompt-audit : 여기에 "CLAUDE.md·스킬·에이전트·커맨드 파일의 지시 내용 점검"을 추가하는 하위 명령
• /doctor는 먼저 결과를 보여주고, 바꾸기 전에 확인을 받아요. 그냥 돌려보고 마음에 안 들면 거절하면 됩니다
• 터미널에서 claude doctor로 치면 세션을 열지 않고 읽기 전용 진단만 출력해요 (이건 prompt-audit 없이 설치 진단만)

[이미지: /doctor prompt-audit 실행 결과 - 낡은 경로·모순 지시 항목이 위에 나열된 보고서 화면]

💬 헷갈리기 쉬운 것 : /claude-api prompt-audit라는 비슷한 이름의 명령도 있어요 (v2.1.221부터). 그건 내 앱 코드 안의 프롬프트·도구 설명(Claude API를 호출하는 코드)을 점검하는 거고, 이번 /doctor prompt-audit는 Claude Code 설정 파일(CLAUDE.md·스킬·에이전트·커맨드)을 점검하는 거예요. 대상이 달라요.

💡 점검 뒤에 볼 것

• /context로 CLAUDE.md·rules·스킬이 실제로 로드됐는지 확인 (파일이 안 읽힌 건지, 읽혔는데 안 따르는 건지 구분)
• CLAUDE.md는 "팀에 새로 온 사람에게 알려줄 것"만 남기고, 절대 하면 안 되는 것은 권한 규칙이나 훅으로 강제하세요. 공식 문서도 CLAUDE.md는 "컨텍스트일 뿐 강제 설정이 아니다"라고 못 박고 있어요

🧩 3. 모델 잠금 설정 - deniedModels · availableModelsMatch (v2.1.283, 팀 관리자용)

🧠 어떤 문제를 푸나

Opus 5.5 글에서 본 것처럼, 새 모델이 나오면 opus 별칭이 자동으로 새 모델을 가리켜요. 관리자 입장에서는 이게 곤란할 수 있죠. 허용 목록 availableModels에 claude-opus-5라고 적어 뒀는데, 이 항목은 뒤에 세그먼트가 하나 더 붙은 후속 버전(Opus 5.5)도 함께 허용하거든요. 그래서 검증도 안 한 새 모델이 다음 날 전 직원 터미널에서 돌아갈 수 있어요.

v2.1.283에서 이걸 막는 관리 설정 두 개가 생겼어요.

🛠️ 예시 - Opus·Sonnet은 허용, Opus 5.5만 막기

관리 설정 파일(managed-settings.json 등)에 이렇게 적어요.

{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-opus-5-5"]
}

• deniedModels의 claude-opus-5-5 : 날짜가 붙은 ID, 프로바이더별 ID 등 "모든 표기"의 Opus 5.5를 막아요
• 막힌 모델은 /model 목록에서 사라지고, /model claude-opus-5-5처럼 직접 치면 거절돼요
• --model·ANTHROPIC_MODEL·model 설정으로 막힌 모델을 지정하면 시작할 때 버리고 Default 옵션으로 대체해요
• Default가 막힌 모델을 가리키면 같은 계열의 최신 허용 버전 → Sonnet → Haiku 순으로 내려가고, 그것도 없으면 세션이 시작을 거부해요

💬 개인 사용자는 해당 없어요. 두 키는 관리 설정에서만 읽혀요. ~/.claude/settings.json이나 프로젝트 설정, --settings에 넣으면 경고와 함께 무시됩니다. 혼자 쓰는 분은 지난 글의 model·modelSettings 설정으로 충분해요.

💬 관리자라면 하나 더 : v2.1.283 미만 버전은 이 두 키를 그냥 무시해요. 그래서 공식 문서는 requiredMinimumVersion을 함께 걸어 구버전이 시작되지 않게 하라고 권해요.

🧩 4. 플러그인 디렉터리 제출 포털 - 내가 만든 걸 Claude 디렉터리에 올리기 (9월 25일)

🧠 뭐가 열렸나

9월 25일 Anthropic이 디렉터리 제출 포털(claude.ai/directory/manage)을 열었어요. 여기서 올린 플러그인은 claude.ai 웹·데스크톱·모바일 앱과 Cowork의 Customize 페이지에서 찾을 수 있고, 추가한 플러그인은 그 사람의 Claude Code 세션에서도 쓸 수 있어요. 예전에 Claude Console 폼으로 받던 플러그인 제출은 이제 지원이 끝났고, 포털로 옮기라고 안내하고 있어요.

제출 유형은 두 가지예요.

• 누가 낼 수 있나 : Pro·Max·Team·Enterprise 유료 플랜. Team·Enterprise는 Owner(또는 Directory 권한을 받은 멤버). 파트너 프로그램 신청 같은 건 없어요
• 스킬만 단독 제출은 불가 : 플러그인 번들에 담아야 해요. 로컬 MCP 서버(MCPB 데스크톱 확장)도 디렉터리에서 더 안 받고, 플러그인에 포함시켜야 해요
• 내 MCP 서버가 있으면 둘 다 제출 : 플러그인이 참조하는 원격 MCP 서버는 따로 MCP 커넥터로도 올려야 서버 상태·도구별 사용량 대시보드와 플러그인 페어링이 생겨요

🛠️ 플러그인 번들 제출 순서 (공식 문서 요약)

1. 터미널에서 먼저 검사: 플러그인 폴더가 있는 위치에서 claude plugin validate ./<플러그인-폴더>
2. claude.ai에 GitHub 계정 연결 (포털이 "이 계정이 저장소에 push 권한이 있나"를 확인해요)
3. 포털에서 Submit new → Plugin bundle 선택
4. Source 단계: 저장소 URL(owner/repo), 플러그인 경로(루트가 아니면), 따라갈 브랜치·태그 입력 → Validate. 커밋 하나에 대한 결과라서 push하면 다시 검증
5. Listing details: plugin.json과 README에서 자동으로 읽어요. 바꾸려면 파일을 고치고 재검증
6. Data handling(개인정보·외부 전송·보관 기간·18세 미만 대상 여부) → Compliance(연락 이메일 + 4개 동의) → Submit for review
7. 통과한 버전은 Publish를 눌러 게시 요청. 기본은 Anthropic 검토자가 게시하고, 이후 버전은 자동 게시 설정에 따라 알아서 올라가요

• 업데이트 : 첫 제출 뒤에는 추적 브랜치에 머지만 하면 디렉터리가 커밋을 가져가 검사·게시해요 (GitHub push 웹훅 또는 주기 확인). plugin.json에 version을 쓰고 있다면 릴리스마다 올려 주세요
• 제한 : 조직당 24시간에 제출 10건(초안·철회도 카운트). 같은 저장소+폴더는 먼저 제출한 조직이 소유
• 게시 후 통계 : 플러그인 페이지 Usage 탭에 설치 수, 버전별 분포, 스킬·MCP 서버별 실행 횟수, 에러율. 리스팅이 몇 번 노출됐고 어떤 검색어로 들어왔는지도 보여요

💬 MCP 자체가 궁금하신 분은 MCP 새 스펙(2026-07-28) 총정리를 먼저 보시면 좋아요. 디스코드 봇 시리즈에서 만든 기능을 스킬로 묶어 플러그인으로 올리는 편도 언젠가 해보고 싶네요.

💡 5. 그 밖의 소소한 변화 - 알아두면 좋은 것들

커밋·PR 서명 끄기 (v2.1.281)

Claude Code가 커밋 메시지 끝에 붙이는 Co-Authored-By: Claude ... 줄과 PR 설명의 "Generated with Claude Code" 문구를 한 번에 숨길 수 있어요.

{
  "attribution": false
}

• 세부 조절도 가능해요: attribution.commit(커밋 트레일러), attribution.pr(PR 설명), attribution.sessionUrl(클라우드·Remote Control 커밋의 세션 링크)
• 어느 설정 파일에나 넣을 수 있어요. 회사 규정으로 서명을 남겨야 하는 분은 건드리지 마세요

넓은 터미널 본문 폭 제한 (v2.1.282)

와이드 모니터에서 터미널을 전체 화면으로 쓰면 Claude 답변이 한 줄에 200자씩 늘어져 읽기 힘들죠. maxProseWidth 설정 키로 본문(prose) 폭을 제한할 수 있어요. 코드 블록이 아니라 설명 문단에만 적용돼요. 값 형식은 공식 설정 레퍼런스의 maxProseWidth 항목을 확인하고 넣어 주세요.

서드파티 프로바이더도 오토 모드로 시작 (v2.1.283)

8월 글에서 Pro·Max·Team의 기본 권한 모드가 오토 모드로 바뀐 걸 정리했는데, 이번엔 Bedrock·Vertex·Foundry 등 서드파티 프로바이더로 접속한 세션과 텔레메트리를 끈 세션도 권한 모드를 따로 정하지 않았다면 오토 모드로 시작해요. 예전 방식이 좋다면 permissions.defaultMode를 명시하면 그게 우선이에요.

그 외 한 줄씩

• v2.1.278: 오토 모드 분류기가 기본으로 서버 측에서 돌아가고, /status에 "Auto mode server" 행이 생겼어요
• v2.1.283: /model 목록과 Default 모델 이름에서 "(1M context)" 표기가 빠졌어요. 기능이 빠진 게 아니라 이름만 정리된 거예요
• v2.1.283: --system-prompt와 --system-prompt-file을 같이 줄 수 있게 됐어요 (파일 내용이 먼저 옴). 자동화 스크립트에서 claude -p 쓰시는 분에게 유용해요
• v2.1.283: claude plugin validate가 잘못된 플러그인·마켓플레이스 이름, 폴더 밖 경로를 이제 제대로 잡아요. 4장 포털 제출 전에 한 번 돌리세요

📌 지금 바꿔볼 설정 체크리스트

1. claude update → claude --version이 2.1.283 이상인지 확인
2. 다른 AI 코딩 도구와 프로젝트를 공유한다면: AGENTS.md 하나로 합치고, CLAUDE.md에 남긴 우회용 문장·SessionStart 훅은 정리. 둘 다 유지하려면 /config → Project instructions → claude-md-and-agents-md
3. CLAUDE.md를 두 달 이상 안 열어봤다면: /doctor prompt-audit 한 번. 제안을 보고 낡은 경로·모순 규칙만 정리 (강제해야 하는 건 권한·훅으로 이동)
4. 커밋에 Claude 서명이 싫다면: ~/.claude/settings.json에 "attribution": false
5. Bedrock·Vertex 사용자: 갑자기 오토 모드로 시작한다면 permissions.defaultMode를 원하는 값으로 명시
6. 팀 관리자: 새 모델 자동 반영이 부담이면 관리 설정에 deniedModels 또는 availableModelsMatch: "exact" + requiredMinimumVersion
7. 플러그인·MCP 서버를 만들어 둔 분: claude plugin validate 통과시키고 claude.ai/directory/manage에서 제출

📌 자주 나는 에러·헷갈리는 점

1. AGENTS.md가 있는데 Claude가 내용을 몰라요

• 원인 : 작업 폴더나 상위 폴더 어딘가에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md가 있어서 그것만 읽고 있음 (홈의 ~/.claude/CLAUDE.md는 제외). 또는 v2.1.277 미만, 또는 /plugin에서 agents-md 내장 플러그인을 꺼둔 상태
• 해결 : 상위 폴더까지 CLAUDE.md 계열을 찾아보고, 유지하려면 Project instructions를 claude-md-and-agents-md로. /memory에서 AGENTS.md 경로가 보이면 성공. /config에 Project instructions 항목 자체가 없으면 그 세션은 AGENTS.md를 못 읽는 세션이니 CLAUDE.md에 @AGENTS.md를 적어 주세요

2. 업그레이드 직후 첫 세션에서만 AGENTS.md가 안 읽혀요

• 원인 : v2.1.276 이하에서 올라온 첫 세션은 일부 경우 아직 CLAUDE.md만 읽어요
• 해결 : 세션을 한 번 종료하고 다시 열면 그다음부터 읽어요

3. /doctor prompt-audit를 쳤는데 모르는 명령이라고 해요

• 원인 : v2.1.283 미만
• 해결 : claude update. 업데이트가 안 되면 claude doctor로 설치 상태(중복 설치·PATH)를 먼저 점검

4. settings.json에 deniedModels를 넣었는데 경고가 뜨고 무시돼요

• 원인 : 관리 설정 전용 키를 사용자·프로젝트 설정에 넣음
• 해결 : 개인 사용이면 model·modelSettings로 원하는 모델을 고정하세요. 조직이면 IT 담당자에게 managed-settings.json 반영을 요청

5. 포털에서 "Couldn't find that repository, branch, tag, or commit"

• 원인 : 비공개 저장소인데 GitHub 계정이 연결되지 않았거나 push 권한이 없음. 포털은 볼 수 없는 저장소의 존재 여부를 알려주지 않아요
• 해결 : claude.ai에서 GitHub 연결 → 저장소 write 권한 확인 → 비공개면 "소스 업로드 동의"와 Claude GitHub App 설치 후 다시 Validate

📌 관련 글

• Claude Code 입문 - 설치부터 첫 실행까지 - 아직 안 깔았다면 여기부터
• Claude Code 오토 모드가 기본값이 됐어요 - 권한 모드와 permissions.defaultMode
• 클로드 코드 모델 변경·effort 설정 완전 정리 - 개인용 model·modelSettings 설정
• 클로드 Opus 5.5 출시! Claude Code 기본 모델 교체 - v2.1.280 변화
• MCP 새 스펙(2026-07-28) 총정리 - 플러그인에 들어가는 MCP 서버 이해하기
• AI 코딩 프롬프트 잘 쓰는 법 - prompt-audit 뒤에 CLAUDE.md 다시 쓰기

📌 마무리

오늘은 Opus 5.5에 가려 조용히 지나간 Claude Code 9월 업데이트를 정리했어요. 요약하면 이래요.

• AGENTS.md를 직접 읽으니 다른 도구와 규칙 파일 하나로 합칠 수 있고, 둘 다 읽게 하려면 /config의 Project instructions만 바꾸면 돼요
• /doctor prompt-audit는 오래된 CLAUDE.md의 대청소 도구. 바꾸기 전에 물어보니 부담 없이 한 번 돌려보세요
• deniedModels·availableModelsMatch는 관리자용. 개인은 기존 model 설정으로 충분해요
• 플러그인 디렉터리 포털이 열렸으니, 만들어 둔 스킬·MCP 서버가 있다면 유료 플랜 계정으로 바로 제출할 수 있어요

다음 Claude Code 소식은 아마 Sonnet 5.5·Haiku 5.5가 나올 때가 될 것 같아요. 그전에 10월 1일 파이썬 3.15 정식 출시가 먼저 오니, 그 후속 글로 돌아올게요. 기대해주세요 🙌