코드나라

클로드 코드 에이전트 만들기(claude code custom agents): 같은 지시를 되풀이할 때 만들고 호출 기록이 0이어도 바로 지우지 않는다

코드짜는아빠 — Fri, 23 Oct 2026 18:00:16 +0900

에이전트 파일을 쓰기 전에 같은 지시로 같은 일을 몇 번이나 맡겼는지부터 세어 보자. 클로드 코드 에이전트(공식 문서 이름은 클로드 코드 서브에이전트)는 마크다운 파일 하나로 만들어진다. 따질 건 그 전에 넷. 같은 일을 같은 지시로 되풀이하고 있나, description 이 이 에이전트 하나만 골라내나, 어느 프로젝트에 둘까, 도구는 무엇만 줄까? 만들어 두고 안 쓰는 에이전트도 공짜는 아니다. description 이 컨텍스트를 차지하니까. 그래도 호출 기록이 0이라는 이유만으로 바로 지우지는 말 것. 프로젝트가 바뀌면 다시 불릴 수 있다. 출처는 Claude Code 서브에이전트 문서 · .claude 폴더 문서, 2026-10-21 조회.

1. 만들 이유: 같은 일을 같은 지시로 되풀이할 때 (2026-10-21 공식 문서 기준)

공식 문서의 기준은 짧다. 같은 종류의 일꾼을 같은 지시로 자꾸 띄우고 있다면 그때 커스텀 서브에이전트를 정의하라는 것. 한 번 하고 말 일이면 대화에서 바로 시키면 된다.

모범 사례 목록의 첫 줄은 범위 쪽 기준이다. 에이전트 하나는 한 가지 일을 잘하게 만들 것. 지금 대화 안에서 같은 절차를 다시 쓰고 싶은 거라면 서브에이전트보다 스킬이 맞을 수 있다. 둘 중 고르는 기준은 15편에.

2. description: 이 에이전트 하나만 골라내게 쓴다

Claude는 요청 내용과 각 서브에이전트의 description, 지금 맥락을 보고 어디에 맡길지 정한다. 그러니 description 이 곧 자동 위임의 규칙이다. 문서 모범 사례의 표현으로는 「서브에이전트 하나를 골라내는 description」, 알맞은 서브에이전트로 가도록 구체적으로 쓰라는 것. 공식 예시 code-reviewer 의 description 한 줄.

Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.

무엇을 하는지(코드 검토)와 언제 부를지(코드를 쓰거나 고친 직후)가 한 줄에 다 들어 있다. 「코드를 도와준다」 같은 한 줄이면 비슷한 에이전트가 여럿일 때 어느 쪽인지 가를 말이 없다. 알아서 맡기게 하고 싶다면 「use proactively」 같은 말을 넣는 게 문서의 안내.

3. 남는 에이전트의 비용: 안 불러도 description 은 컨텍스트를 차지한다

만들어 둔 서브에이전트의 description 은 컨텍스트를 차지한다. 그래서 문서의 당부는 짧게. 내장 서브에이전트를 뺀 나머지 description 을 합쳐 15,000 토큰을 넘으면 시작할 때 합계 토큰 수와 함께 경고가 뜬다. 경고가 떠도 서브에이전트는 전부 불러온다. 자세한 지시는 본문, 곧 시스템 프롬프트로. 본문은 그 서브에이전트가 돌 때만 불러오니까.

부를 때의 비용도 있다. 서브에이전트마다 도는 동안 자기 토큰을 쓰고 끝나면 결과가 메인 대화로 돌아온다. 자세한 결과를 돌려주는 서브에이전트를 여럿 돌리면 컨텍스트를 꽤 먹는다는 게 문서의 경고.

4. 둘 곳: 모든 프로젝트에서 쓸 것만 ~/.claude/agents/ 에

~/.claude/agents/ 에 둔 서브에이전트는 내 모든 프로젝트에서, 프로젝트의 .claude/agents/ 에 둔 것은 그 프로젝트에서만 쓰인다. 플러그인으로 받은 서브에이전트는 그 플러그인을 켠 곳에서 직접 만든 것과 함께 자동으로 올라온다. 같은 이름끼리의 순위 표는 18편에. 그러니 특정 기술 스택에서만 쓸 에이전트라면 그 스택을 쓰는 프로젝트의 .claude/agents/ 에 두는 쪽. 다른 프로젝트에서는 그 description 이 실리지 않는다.

플러그인 서브에이전트라면 하나 더. 보안상 이유로 hooks · mcpServers · permissionMode 필드를 무시한다. 그 필드가 필요하면 파일을 .claude/agents/ 나 ~/.claude/agents/ 로 옮기라는 게 문서의 안내. 옮기기 전에 그 세 필드가 무엇을 돌리고 어디에 연결하는지부터 읽어 볼 것. 옮기는 순간 막혀 있던 것이 다시 켜진다.

5. 도구: tools 에 필요한 것만 적는다

모범 사례 셋째 줄은 꼭 필요한 권한만 주라는 것. 공식 예시 둘이 그 차이를 보여 준다. 검토 담당 code-reviewer 는 Edit · Write 를 뺐고 버그를 고치는 debugger 는 코드를 고쳐야 하니 Edit 를 넣었다. tools 를 비워 두면 쓸 수 있는 도구를 전부 물려받는다. 필드 설명과 다시 위임 막기는 18편에.

6. 지우기 전에: 호출 기록을 세되 0을 「앞으로도 안 씀」으로 읽지 않는다

안 쓰는 것 같은 에이전트를 지우기 전에 실제 호출부터 세 볼 수 있다. Claude Code는 대화 기록 전체를 ~/.claude/projects/<project>/<session>.jsonl 에 남긴다. 메시지 · 도구 호출 · 도구 결과가 다 들어간 파일. 서브에이전트 쪽 대화는 <session>/subagents/ 아래에 따로.

# 남아 있는 대화 기록 파일 수(따로 치워 둔 이전 기록 파일도 포함)
ls ~/.claude/projects/<project>/*.jsonl | wc -l

여기서 두 가지를 조심한다. 첫째, 이 파일은 기본 30일이 지나면 지워진다(cleanupPeriodDays). 센 숫자는 남아 있는 기간의 호출 수일 뿐. 둘째, 호출이 어느 필드에 어떤 꼴로 남는지는 위 두 공식 문서에 나와 있지 않다. 에이전트 이름으로 찾으면 호출이 아닌 줄까지 걸릴 수 있으니 걸린 줄을 열어 보고 세는 게 안전하다. 걸린 줄이나 폴더 이름(집 경로가 들어간다)은 다른 곳에 붙여 넣지 말고 센 숫자만 옮길 것. 이 파일에는 도구 결과가 그대로 남아서 읽었던 키나 토큰이 들어 있을 수 있다.

그리고 숫자가 0이어도 그걸 「앞으로도 안 씀」으로 읽지는 말 것. 기록은 지난 프로젝트들이 무엇을 불렀는지만 말해 준다. 다음 프로젝트가 다른 스택이면 지금 0인 에이전트가 그때 필요해질 수도. 지우는 대신 그 스택을 쓰는 프로젝트의 .claude/agents/ 로 옮겨 두는 길도 있다. Claude가 그 서브에이전트를 쓰지 못하게만 하려면 설정의 permissions.deny 에 Agent(<이름>) 을 넣으면 된다. 이름은 에이전트 파일 frontmatter 의 name 값.

{
  "permissions": {
    "deny": ["Agent(<AGENT_NAME>)"]
  }
}

실제로 겪은 일

9월 9일, Claude가 지난 세션 기록(트랜스크립트) 441개를 전부 뒤져 커스텀 에이전트 호출을 셌다. 외부 묶음으로 설치해 둔 60개 가운데 실제로 불린 건 code-reviewer(31회)와 security-reviewer(20회) 둘뿐. 그래서 나머지를 정리하려 했지만 철회했다. 내가 짚은 건 프로젝트마다 쓰는 기술 스택이 달라지는 구조라는 점. 호출 이력 0은 「앞으로도 안 씀」이 아니었다.

만들기 전 점검표: 클로드 코드 에이전트 만들기

같은 일을 같은 지시로 여러 번 맡겼나. 한 번뿐이면 대화에서 시킨다.
지금 대화 안에서 다시 쓸 절차라면 스킬이 더 맞지 않나.
description 한 줄에 무엇을 하는지와 언제 부를지가 다 있나. 비슷한 에이전트와 겹치지 않나.
자세한 지시를 본문으로 옮겼나. 시작할 때 15,000 토큰 경고가 뜨지 않나.
특정 스택 전용이면 그 프로젝트의 .claude/agents/ 에 두었나.
tools 에 필요한 도구만 적었나. 고치지 않을 에이전트에 Edit · Write 가 들어 있지 않나.
지우기 전에 남은 기록(기본 30일)으로 호출을 셌나. 0이라도 다음 프로젝트에서 쓸 일이 없는지 따져 봤나.

같이 읽을 글

18편 — 클로드 코드 서브에이전트 사용법(claude code subagents): .claude/agents/ 에 파일 하나로 만들고 검토는 쓴 쪽과 다른 서브에이전트에 맡긴다: 파일 위치 · frontmatter · 부르기 · 도구 제한을 단계별로. 이 글의 점검을 마친 뒤 실제로 만들 때.
15편 — claude code skills vs agents · 클로드 코드 스킬 vs 서브에이전트: 지금 대화에서 다시 쓸 절차는 스킬, 결과만 받을 일은 서브에이전트: 에이전트를 만들기 전에 스킬로 둘 일인지 가르는 기준.

다음 글은 클로드 코드 코덱스 차이. Claude Code와 Codex를 둘 다 쓸 때 어떤 일을 어느 쪽에 맡길지 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

클로드 코드 서브에이전트 사용법(claude code subagents): .claude/agents/ 에 파일 하나로 만들고 검토는 쓴 쪽과 다른 서브에이전트에 맡긴다

코드짜는아빠 — Wed, 21 Oct 2026 14:25:57 +0900

같은 종류의 일을 매번 같은 지시로 맡기고 있다면 그 지시를 서브에이전트 파일 하나로 만들어 두면 된다. 클로드 코드 서브에이전트 사용법은 세 걸음. 프로젝트의 .claude/agents/(나만 쓰려면 ~/.claude/agents/)에 마크다운 파일을 하나 두고 맨 위 frontmatter 에 name · description 을 적은 뒤 그 아래에 서브에이전트가 따를 지시를 쓴다. 그다음엔 Claude가 description 을 보고 알아서 맡기거나 내가 이름 · @ 로 직접 맡긴다. 작업은 서브에이전트의 컨텍스트 창 안에서 돌고 메인 대화로 돌아오는 건 요약뿐. 쓸 도구는 tools 로 좁힌다. 빼 두면 쓸 수 있는 도구를 전부 물려받으니까. 여기에 우리 기준 하나를 더하면, 검토는 쓴 쪽과 다른 서브에이전트에 맡기고 그 서브에이전트는 결과물을 고치지 않고 찾은 것만 돌려준다. 출처는 Claude Code 서브에이전트 문서, 2026-10-21 조회.

서브에이전트는 자기 컨텍스트에서 일하고 요약만 돌려준다 (2026-10-21 공식 문서 기준)

공식 문서는 서브에이전트를 정해진 종류의 일을 맡는 전문 조수라고 부른다. 자기 컨텍스트 창, 자기 시스템 프롬프트, 정해진 도구, 따로 된 권한을 가지고 도는 조수. 검색 결과 · 로그 · 파일 내용처럼 다시 안 볼 출력이 메인 대화를 덮을 것 같을 때 쓰라고 문서는 안내한다. 그 일은 서브에이전트 컨텍스트 안에서 끝나고 메인 대화로는 요약만 돌아온다. 한 가지 더, 서브에이전트가 보내는 요청도 메인 대화와 같은 사용 한도에 잡힌다는 점.

만들지 않아도 들어 있는 내장 서브에이전트 가운데 자주 보이는 셋. Explore(코드베이스 검색 · 분석)와 Plan(플랜 모드에서 계획 전에 맥락 모으기)은 읽기 전용이라 Write · Edit 가 막혀 있다. general-purpose 는 서브에이전트가 쓸 수 있는 도구를 전부 받는다. 스킬과 어떻게 나눠 쓰는지는 15편에.

1단계: 서브에이전트 만들기 — Claude에게 부탁하거나 파일을 직접 쓴다

서브에이전트는 YAML frontmatter 가 붙은 마크다운 파일이다. 만드는 길은 둘. Claude에게 써 달라고 하거나 파일을 직접 쓰거나. /agents 를 쳐도 지금은 이 두 길을 알려 주는 안내만 나온다. v2.1.197 까지는 같은 명령이 만들기 · 고치기 · 지우기를 하는 대화형 화면을 열었다.

Claude에게 맡긴다면 이런 식(공식 예시를 줄여 옮김).

~/.claude/agents/ 에 개인용 code-improver 서브에이전트를 만들어 줘.
파일을 훑어서 읽기 쉬움 · 성능 · 관례 쪽 개선점을 제안하게 하고
읽기 전용으로, 모델은 Sonnet 으로.

Claude가 만든 파일은 한 번 열어 본다. tools 에 무엇이 들어갔는지, description 이 언제 맡길지를 말하고 있는지. ~/.claude/agents/ 에 둔 파일은 내 모든 프로젝트에서 쓰인다. 한 프로젝트에서만 쓰려면 그 프로젝트의 .claude/agents/ 로 옮길 것.

2단계: 파일 위치 — 팀과 나눌 건 .claude/agents/, 나만 쓸 건 ~/.claude/agents/

위치	쓰이는 곳	같은 이름일 때 순위
회사 관리 설정	조직 전체	1(가장 높음)
실행 옵션 `--agents`(JSON)	지금 세션	2
`.claude/agents/`	지금 프로젝트	3
`~/.claude/agents/`	내 모든 프로젝트	4
플러그인의 `agents/` 폴더	플러그인을 켠 곳	5(가장 낮음)

프로젝트 서브에이전트는 버전 관리에 넣어 팀이 같이 쓰고 고치라는 게 문서의 권고. 폴더는 하위 폴더까지 훑는다. 같은 서브에이전트인지 가르는 기준은 파일 이름 말고 name 필드. --agents 는 실행할 때 JSON 으로 넘기는 정의라 디스크에 남지 않는다.

파일을 더하거나 고치면 Claude Code가 몇 초 안에 알아채고 다음 위임부터 새 정의를 쓴다. 다시 시작해야 하는 경우는 셋.

세션을 시작할 때 없던 agents 폴더를 새로 만들고 첫 파일을 넣었을 때
--add-dir 이나 /add-dir 로 더한 폴더 안의 .claude/agents/ 를 고쳤을 때
--disable-slash-commands 로 시작한 세션일 때(이때는 폴더를 아예 지켜보지 않는다)

3단계: frontmatter — 필수는 name · description 둘

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

공식 문서에 실린 가장 짧은 꼴. frontmatter 아래 본문이 그 서브에이전트의 시스템 프롬프트가 된다.

name(필수): 고유 이름, 256자까지.
description(필수): Claude가 언제 이 서브에이전트에 맡길지 고르는 기준. 알아서 맡기게 하려면 「use proactively」 같은 말을 넣으라고 문서는 적는다. 짧게 쓸 것 — 직접 만든 서브에이전트들의 description 을 합쳐 15,000 토큰을 넘으면 시작할 때 경고가 뜬다(그래도 전부 불러온다).
tools: 쓸 수 있는 도구. Read, Grep, Bash 같은 쉼표 목록이나 YAML 목록. 빼면 서브에이전트가 쓸 수 있는 도구를 전부 물려받는다.
disallowedTools: 뺄 도구. 물려받은 목록이나 tools 목록에서 지운다.
model: sonnet · opus · haiku 같은 별칭, 전체 모델 ID, 또는 inherit. 비워 두면 부를 때 지정한 모델 → 환경 변수 CLAUDE_CODE_SUBAGENT_MODEL → 메인 대화 모델 순으로 정해진다.
그 밖에 permissionMode · maxTurns · skills · mcpServers · hooks 같은 필드가 있다. permissionMode 를 비우면 메인 대화의 권한 모드를 물려받는다.

필수는 둘뿐이지만 tools 는 적어 두는 쪽이 낫다. 빼면 위 설명대로 전부 물려받으니까.

4단계: 부르기 — description 으로 알아서 · 이름이나 @ 로 직접

Claude는 요청 내용과 서브에이전트의 description, 지금 맥락을 보고 알아서 맡긴다. 직접 고르는 길은 셋.

test-runner 서브에이전트로 실패하는 테스트를 고쳐 줘
@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

첫째는 이름을 말로 부르는 것, 둘째는 @ 를 치고 목록에서 고르는 것(손으로 칠 땐 @agent-<이름>), 셋째는 세션 전체를 그 서브에이전트로 여는 것. 특정 서브에이전트를 아예 못 쓰게 하려면 설정의 permissions.deny 에 Agent(<이름>) 을 넣는다.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Claude가 띄우는 서브에이전트는 기본값에서 백그라운드로 돈다. 그동안 나는 다른 일을 하고 권한 확인 창은 그때그때 메인 세션으로.

5단계: 도구 제한 — tools 는 허용 목록, Bash 는 따로 거른다

tools 는 허용 목록, disallowedTools 는 차단 목록. 아무것도 적지 않으면 메인 대화에 있는 내장 도구와 MCP 도구를 물려받는다. 파일을 고치면 안 되는 검토용이라면 tools: Read, Grep, Glob 처럼 Write · Edit 를 뺀 목록. 공식 예시 가운데는 여기에 Bash 를 더한 것도 있고 문서는 그 꼴을 「파일을 고치거나 쓸 수 없다」고 설명한다. Edit · Write 도구가 없다는 뜻. Bash 는 셸 명령을 그대로 돌리니 권한이 허용하는 명령이면 파일이 바뀔 수 있다. 셸이 꼭 필요하다면 공식 예시 db-reader 처럼 PreToolUse 훅으로 명령을 거르는 쪽. 그 예시에서는 SQL 쓰기 명령이 보이면 훅 스크립트가 종료 코드 2로 막는다.

서브에이전트는 기본값에서 메인 대화 아래 세 단계까지 자기 서브에이전트를 띄울 수 있다. 막는 길은 셋. 그 서브에이전트 하나만 막으려면 tools 허용 목록에서 Agent 를 빼거나 disallowedTools 에 Agent 를 넣고 모든 서브에이전트를 한꺼번에 막으려면 환경 변수 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 를 1 로 둔다.

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"
  }
}

이 값은 메인 대화 아래 몇 단계까지 띄울지를 뜻한다. 1 이면 중첩이 꺼지는 셈.

tools 에 적어도 서브에이전트에게서 빠지는 도구가 있다. 사용자에게 되묻는 AskUserQuestion 이 그중 하나. 그러니 맡기는 프롬프트는 그것만 읽고 일을 끝낼 수 있게 쓸 것.

검토는 왜 남이 해야 하나: 쓴 대화를 못 보는 쪽이 읽게 한다

같은 대화에서 「방금 쓴 것 검토해 줘」라고 하면 무엇이 빠질까? 검토하는 쪽도 쓴 이유와 가정을 이미 다 아는 상태. 서브에이전트는 대화 기록 없이, 넘겨받은 프롬프트로 새 컨텍스트에서 출발한다. 예외는 포크. 지금 대화를 통째로 물려받는 서브에이전트라 검토를 맡길 자리는 아니다. 그래서 검토 서브에이전트는 쓴 쪽의 설명 대신 결과물과 그 출처를 놓고 읽게 된다. 여기부터는 우리가 정한 기준.

쓴 에이전트와 다른 에이전트가 검토한다. 원고든 코드든, 만든 에이전트가 아니라 별도 컨텍스트의 검토 에이전트가 본다.
검토 에이전트는 결과물을 고치지 않는다. tools 에 Edit 를 넣지 않고 찾은 것은 보고서나 마지막 메시지로 돌려받는다.
커밋하지 않는다. 커밋은 부른 쪽 세션이 한다.
다시 위임하지 않는다. Agent 를 주지 않아서 검토를 또 다른 서브에이전트에 넘기지 못하고 직접 끝낸다.

공식 문서 꼴로 줄이면 이렇다(이름은 자리표시).

---
name: <AGENT_NAME>
description: Reviews a finished draft or diff against its sources. Use after writing is done, never for writing.
tools: Read, Grep, Glob
model: inherit
---

Review only what the request names. Check each claim against its source.
Return findings in your final message. Do not edit files or delegate.

Bash 가 없으니 이 서브에이전트는 git 명령도 못 돌린다. 테스트나 git diff 가 필요한 검토라면 Bash 를 넣게 되고 그때부터 커밋 금지는 지시문이 지키는 규칙.

실제로 겪은 일

10월 20일, Claude가 쓴 이 블로그 17편 초안을 검토 전용 에이전트가 따로 읽었다. 판정은 「아래를 고치면 통과」, 고칠 것은 여덟 가지. 그중 하나가 우리 설정을 설명한 대목. 초안은 읽기 도구만 승인 없이 열어 둔 그 설정을 권한 허용 규칙으로 했다고 썼는데 기록과 대조해 보니 실제 장치는 훅이었다. 고친 판은 다시 검토를 받아 통과했고 보안 검토도 따로 거쳤다.

내 설정 점검표: 클로드 코드 서브에이전트 사용법

파일이 .claude/agents/(팀 공유) 또는 ~/.claude/agents/(나만)에 있나. 같은 name 이면 프로젝트 것이 이긴다.
name 과 description 을 적었나. description 이 언제 맡길지를 짧게 말하나.
tools 를 적었나. 빼면 메인 대화의 내장 도구 · MCP 도구를 물려받는다.
검토용이라면 Write · Edit 가 빠졌나. Bash 를 넣었다면 훅으로 명령을 거르나.
다시 위임하지 않게 하려면 Agent 를 tools 에서 뺐거나 disallowedTools 에 넣었나. 한꺼번에 막으려면 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 를 1 로.
맡기는 프롬프트만 읽고도 일을 끝낼 수 있나. 서브에이전트는 AskUserQuestion 으로 되묻지 못한다.
검토를 쓴 대화 안에서 하고 있지 않나. 검토는 이름 있는 다른 서브에이전트에.
세션 중에 agents 폴더를 처음 만들었다면 Claude Code를 다시 시작했나.

같이 읽을 글

15편 — claude code skills vs agents · 클로드 코드 스킬 vs 서브에이전트: 지금 대화에서 다시 쓸 절차는 스킬, 결과만 받을 일은 서브에이전트: 스킬에 둘지 서브에이전트에 둘지 고르는 기준.
9편 — Claude Code · Codex 한 저장소에서 충돌 막는 법(git worktree · git commit 경로 지정): 에이전트 둘이 동시에 커밋한 날: 서브에이전트를 여럿 돌릴 때 커밋이 섞이지 않게, 커밋을 부른 세션에 둔 이유.

다음 글은 클로드 코드 에이전트 만들기. Claude Code에서 에이전트를 만들기 전에 무엇을 따져 볼지 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

코드나라 구글 도구 개인정보처리방침

코드짜는아빠 — Tue, 20 Oct 2026 19:23:15 +0900

시행일: 2026년 10월 20일

「코드나라 도구」는 코드나라(블로그 code-nara.tistory.com 과 같은 이름의 YouTube 채널) 운영자가 혼자 쓰려고 만든 도구입니다. 하는 일은 두 가지입니다. 운영자 채널에 영상을 올리고, 운영자 채널과 블로그의 지표를 받아 기록합니다. 다른 사람이 이 도구로 로그인하거나 자기 계정을 연결하는 기능은 없습니다.

이 도구는 YouTube API 서비스를 씁니다. 이 도구를 쓰면 YouTube 서비스 약관(https://www.youtube.com/t/terms)에 동의하는 것이 됩니다. 구글이 정보를 어떻게 다루는지는 구글 개인정보처리방침(https://policies.google.com/privacy)에 있습니다.

1. 구글에 요청하는 권한과 다루는 정보

권한(범위)	하는 일	다루는 정보
`https://www.googleapis.com/auth/youtube.upload`	운영자 채널에 영상 올리기, 올린 영상의 썸네일 정하기	보내는 것: 영상 파일, 제목, 설명, 태그, 공개 상태, 아동용 여부, 합성 미디어 여부, 카테고리, 썸네일 이미지. 받아 쓰는 것: 올라간 영상의 ID, 공개 상태, 업로드 처리 상태
`https://www.googleapis.com/auth/yt-analytics.readonly`	운영자 채널 지표 보기	최근 28일 동안 영상별 조회수, 평균 시청 비율, 구독자 증감, 참여 조회수. 영상 단위 합계이고 시청자 개인 정보는 없습니다
`https://www.googleapis.com/auth/webmasters.readonly`	블로그(code-nara.tistory.com) 검색 지표 보기	최근 28일 동안 날짜 · 검색어 · 페이지별 클릭 수, 노출 수, 클릭률, 평균 순위. 검색한 사람이 누구인지는 들어 있지 않습니다

지표 권한 두 개는 읽기 전용이라, 이 권한으로는 채널이나 블로그를 바꿀 수 없습니다.
업로드 권한으로 채널의 다른 정보를 읽지는 않습니다. 공개 상태를 따로 정하지 않으면 영상은 비공개로 올라갑니다.
권한 세 개와 별개로, 로그인 없이 누구나 볼 수 있는 영상 수치(조회수 · 좋아요 수 · 댓글 수)도 YouTube Data API 로 하루 한 번 기록합니다. 이 조회에는 운영자 계정 권한을 쓰지 않습니다.

2. 사용 목적

받은 정보는 운영자가 자기 영상과 글이 얼마나 보이고 읽혔는지 판단하는 데만 씁니다. 광고에 쓰지 않고, 팔지 않습니다. 3절에 적은 운영자의 작업 도구 말고는 다른 서비스에 넘기지 않습니다.

3. 저장하는 곳과 기간

인증 정보(토큰)는 운영자 컴퓨터에 있고, 운영자 계정만 열 수 있게 파일 권한을 막아 두었습니다. 업로드용과 지표용은 따로 둡니다. 다시 인증하면 새 값으로 바뀌고, 권한을 철회하면 더는 쓰이지 않습니다.
1절의 지표는 하루 한 번 자동으로 받고, 운영자가 필요할 때 직접 더 받기도 합니다. 받은 지표는 운영자 컴퓨터의 기록 파일에 덧붙이고, 같은 날짜의 같은 항목은 두 번 쓰지 않습니다.
영상을 올리면 그 영상 주소를 운영자의 콘텐츠 기록에 적어 둡니다.
보관 기한은 아직 따로 정하지 않았습니다. 이 도구를 쓰는 동안 보관합니다.
운영자는 이 기록을 자기가 정해 쓰는 AI 작업 도구(문서 · 코드 작업을 돕는 AI 서비스)로 읽고 정리합니다. 요약 숫자는 운영자의 비공개 작업 기록(비공개 코드 저장소 서비스)에도 옮겨 적습니다. 이때 정보가 그 서비스를 제공하는 회사의 서버를 거칩니다. 운영자 본인이 자기 지표를 보고 판단하려고 쓰는 것이며, 그 회사가 광고나 AI 모델 학습 같은 자기 목적에 쓰도록 주는 것이 아닙니다.

4. 다른 곳에 주는 정보

구글에서 받은 정보를 팔거나 광고에 쓰지 않고, 다른 사람에게 넘기지 않습니다. 3절의 AI 작업 도구와 비공개 저장소는 운영자 본인이 쓰는 처리 도구라서 정보가 그 회사의 서버를 거치지만, 그 회사의 목적에 쓰라고 주는 것은 아닙니다. 지표 권한이 만료되면 운영자 메신저로 「다시 인증하라」는 한 줄 알림이 가는데, 이 알림에는 구글에서 받은 정보가 들어가지 않습니다.

5. Limited Use 준수

이 도구가 Google API에서 받은 정보를 쓰는 방식은 Limited Use 요구사항을 포함한 Google API Services User Data Policy 를 따릅니다.

(English) 코드나라 도구 (Codenara Tools)'s use of information received from Google APIs will adhere to the Google API Services User Data Policy (https://developers.google.com/terms/api-services-user-data-policy), including the Limited Use requirements.

6. 권한 철회와 삭제

구글 계정의 보안 설정 페이지(https://security.google.com/settings/security/permissions)에서 이 도구의 접근 권한을 언제든 철회할 수 있습니다. 철회하면 그 뒤로는 새 영상을 올리거나 지표를 받지 못합니다.
권한을 철회하면, 이 도구가 그 권한으로 받아 저장해 둔 정보를 7일 안에 지웁니다.
철회하지 않아도 삭제를 요청하시면 7일 안에 지우고 결과를 답장 드립니다.
여기서 지우는 것은 이 도구가 운영자 컴퓨터와 작업 기록에 저장한 정보뿐입니다. YouTube 에 올라간 영상과 YouTube 가 가진 데이터는 그대로 남습니다. 그것을 지우려면 YouTube 나 YouTube 스튜디오에서 직접 지워야 합니다.

7. 문의

문의 · 삭제 요청: codenara.contact@gmail.com

8. 바뀌면

이 방침이 바뀌면 이 페이지에 시행일과 함께 고쳐 적습니다. 정보를 쓰는 방식이 새로 생기면 그 전에 이 페이지부터 고칩니다.

클로드 코드 MCP 연결 · 설정(claude code mcp setup): claude mcp add 한 줄로 붙이고, 읽기 도구만 승인 없이 열어 둔다

코드짜는아빠 — Tue, 20 Oct 2026 18:55:34 +0900

붙이는 건 명령 한 줄이고, 손이 더 가는 건 붙인 다음이다. Claude Code에 MCP 서버를 연결하는 명령은 claude mcp add. 원격 서버는 --transport http 와 주소를, 내 컴퓨터에서 도는 서버는 -- 뒤에 실행 명령을 적는다. 설정이 어디에 저장될지는 --scope 로 고르고, 기본은 지금 프로젝트에서 나만 쓰는 local. 붙인 뒤엔 claude mcp list 로 연결을 확인하고 곧바로 도구 권한을 정한다. 우리 기준은 읽기 도구만 승인 없이 쓰게 하고, 바깥을 바꾸는 쓰기 · 입력 도구는 계속 승인을 거치게 두는 것. 출처는 Claude Code MCP 문서 · 권한 문서 · 설정 문서 · 훅 문서 · MCP 공식 소개, 모두 2026-10-20 조회.

MCP 서버를 붙이면 Claude Code 안에 도구가 생긴다

MCP 공식 소개는 MCP를 「AI 애플리케이션을 외부 시스템에 연결하는 오픈소스 표준」이라고 부르고, AI 애플리케이션용 USB-C 포트에 빗댄다. Claude Code에 서버를 붙이면 그 서버의 도구가 다른 도구와 똑같이 쓰이고, 이름은 mcp__<서버>__<도구> 꼴. 공식 예시로 mcp__filesystem__read_file 은 파일 시스템 서버의 파일 읽기 도구다. 4단계의 권한 규칙이 이 이름으로 걸리니 기억해 둘 것.

1단계: claude mcp add 로 붙인다 (2026-10-20 공식 문서 기준)

# 원격 서버(HTTP)
claude mcp add --transport http <SERVER_NAME> https://example.com/mcp

# 내 컴퓨터에서 도는 서버(stdio) — 패키지 버전까지 적는다
claude mcp add --transport stdio <SERVER_NAME> -- npx -y <PACKAGE>@<VERSION>

원격 서버는 공식 문서가 HTTP 방식을 권한다. SSE 방식은 「deprecated」로 표시돼 있어서, 고를 수 있으면 HTTP 쪽. stdio 에서는 -- 가 경계선. Claude Code 자신의 옵션(--transport · --env · --scope)은 앞에, 서버를 띄우는 명령과 인자는 뒤에 두고, 뒤쪽은 손대지 않고 그대로 서버로 넘어간다. --env 바로 뒤에 서버 이름이 오면 그 이름까지 KEY=value 로 읽혀 거부되니, 사이에 --transport stdio 같은 옵션을 하나 끼울 것.

npx -y 의 -y 는 설치 전에 묻는 확인을 건너뛰는 옵션이다(npm 문서). @<VERSION> 자리에는 범위(^1 같은)나 태그가 아니라 정확한 버전 숫자를 적는다. 버전을 적는 이유는 아래 「붙이고 나서 먼저 막은 것」에.

2단계: --scope 로 저장 범위를 고른다

claude mcp add --transport http <SERVER_NAME> --scope project https://example.com/mcp
claude mcp add --transport http <SERVER_NAME> --scope user https://example.com/mcp

범위	어디서 쓰이나	저장 위치(공식 문서)
`local`(기본)	지금 프로젝트에서 나만	`~/.claude.json` 안, 그 프로젝트 경로 아래
`project`	지금 프로젝트, 버전 관리로 팀과 공유	프로젝트 맨 위 `.mcp.json`
`user`	내 모든 프로젝트에서 나만	`~/.claude.json`

같은 서버가 여러 곳에 있으면 Claude Code는 한 번만 연결한다. 이기는 순서는 local → project → user → 플러그인이 준 서버 → claude.ai 커넥터. 같은 서버인지는 세 범위끼리는 이름으로, 플러그인 · 커넥터는 주소나 실행 명령으로. 이긴 쪽 항목을 통째로 쓰고, 범위끼리 필드를 섞지 않는다. local · user 범위가 저장되는 ~/.claude.json 은 Claude Code가 스스로 쓰는 파일이라 손으로 고칠 필요가 없다고 문서는 적는다. 추가 · 확인 · 삭제는 claude mcp 명령으로.

project 범위의 .mcp.json 은 다르다. 대화형 세션에서는 그 서버를 사용하기 전에 승인을 묻고, 그 선택을 되돌리는 명령은 claude mcp reset-project-choices. 그런데 claude -p 실행에서는 묻지 않고 바로 불러온다. 남이 만든 저장소에서 자동 실행을 돌린다면 .mcp.json 부터 열어 볼 것.

키가 필요한 서버: 명령줄과 공유 파일에 키를 적지 않는다

공식 예시에는 --env 로 키 값을, --header 로 Bearer 토큰을 명령줄에 바로 적는 꼴도 있다. 진짜 값을 그렇게 치면 셸 기록에 남는다. 게다가 local · user 범위 설정이 들어가는 ~/.claude.json 은 로그인 세션까지 담는 파일. 원격 서버가 OAuth 로그인을 지원하면 키 없이 /mcp 에서 인증하는 쪽이 낫다.

키를 꼭 넣어야 한다면 .mcp.json 의 환경 변수 펼치기. ${VAR} 는 그 환경 변수 값, ${VAR:-기본값} 은 값이 없을 때 쓸 기본값. command · args · env · url · headers 다섯 자리에서 펼쳐진다.

{
  "mcpServers": {
    "<SERVER_NAME>": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

이 파일은 커밋해도 키가 따라가지 않는다. 값은 권한 600 파일 하나에, 넣는 건 편집기로.

mkdir -p ~/.config
[ -e ~/.config/mcp-keys.env ] || install -m 600 /dev/null ~/.config/mcp-keys.env
chmod 600 ~/.config/mcp-keys.env
# 편집기로 열어 한 줄만 넣는다:  export API_KEY='<API_KEY>'
( . ~/.config/mcp-keys.env && exec claude )

echo 로 넣지 않는 건 그 줄이 셸 기록에 남아서. export 한 변수는 그 뒤에 실행하는 명령의 환경으로 넘어가고(bash 설명서), Claude Code도 그 명령 중 하나라 ${API_KEY} 가 펼쳐진다. 마지막 줄의 괄호는 서브셸이라, 거기서 불러온 값은 괄호가 끝나면 원래 셸에 남지 않는다(bash 설명서). 키가 들어가는 건 괄호 안에서 띄운 그 Claude Code 쪽뿐. 거꾸로, Claude Code가 그 안에서 돌리는 명령도 같은 값을 물려받는다. 키를 넣은 세션에서는 env · printenv 처럼 환경을 통째로 출력하는 명령을 승인하지 말 것.

3단계: claude mcp list 와 /mcp 로 연결을 확인한다

claude mcp list                                    # 서버마다 연결 상태
claude mcp get <SERVER_NAME>                       # 한 서버의 설정
claude mcp remove <SERVER_NAME> --scope <SCOPE>    # 뺄 때, 범위를 짚어서

claude mcp list 는 서버마다 ✔ Connected · ! Needs authentication · ✘ Failed to connect 같은 상태를 붙여 보여 준다. Claude Code 안에서는 /mcp. 연결된 서버 옆에 도구 개수가 나오고, 원격 OAuth 서버 인증과 서버 끄기도 여기서 한다. 시작이 느린 서버라면 MCP_TIMEOUT 으로 시작 대기 시간을 바꿀 수 있다. 문서 예시 MCP_TIMEOUT=10000 claude 가 10초. 원격 서버를 지우면 Claude Code가 저장해 둔 그 서버의 OAuth 토큰과 클라이언트 등록도 같이 지운다.

4단계: 도구 권한을 정한다 — 읽기 도구만 허용 규칙에

기본 모드(화면 표시는 Manual)는 도구마다 처음 쓸 때 승인을 묻고, MCP 도구에도 승인 창이 뜬다. 귀찮다고 서버 전체를 허용 규칙에 넣으면? 그 서버의 쓰기 도구까지 승인 없이 돈다. 그래서 읽기 도구만 이름으로. 여기서 읽기는 바깥 상태를 바꾸지 않는다는 뜻이지, 아무것도 내보내지 않는다는 뜻은 아니다. 주소로 이동하는 도구는 그 주소에 실린 글자를 상대 서버로 보낸다. 승인 없이 열 도구는 그것까지 감수할 수 있는지로 고를 것.

{
  "permissions": {
    "allow": [
      "mcp__<SERVER_NAME>__<READ_TOOL_1>",
      "mcp__<SERVER_NAME>__<READ_TOOL_2>"
    ],
    "ask": [
      "mcp__<SERVER_NAME>__<WRITE_TOOL>"
    ]
  }
}

사용자 설정 ~/.claude/settings.json 에 두면 내 모든 프로젝트에, 프로젝트의 .claude/settings.json 에 두면 그 폴더에서 일하는 모두에게 걸린다. /permissions 를 열면 규칙마다 어느 파일에서 왔는지 보인다.

mcp__<서버> · mcp__<서버>__*: 그 서버의 도구 전부
mcp__<서버>__<도구>: 도구 하나
mcp__<서버>__get_* 처럼 서버 이름 뒤에 붙인 글롭은 허용 규칙에서도 된다. mcp__* 처럼 서버 이름 없이 쓴 허용 글롭은 경고와 함께 건너뛰고, 아무것도 허용하지 않는다
서버 이름에 . 이나 공백이 있으면 _ 로 바꿔 적는다(my.server → mcp__my_server__*)

걸리기 쉬운 곳은 순서. 규칙은 deny → ask → allow 차례로 보고, 처음 맞는 것이 결과가 된다. 더 구체적인 규칙이라고 먼저 보는 것도 아니고. 그래서 ask 에 mcp__<SERVER_NAME>__* 를 넣으면 위의 읽기 도구 허용까지 덮여 매번 묻는다. 묻게 할 도구는 이름이나 좁은 글롭으로 따로 적을 것.

훅으로 막는다면 매처 규칙이 또 다르다. 훅 매처에 mcp__memory 처럼 서버 이름만 쓰면 아무 도구에도 맞지 않고, 서버 전체는 mcp__memory__.* 처럼 .* 를 붙여야 한다. 훅 설정의 기초는 7편에.

붙이고 나서 먼저 막은 것: 버전 · 실행 방식 · 사용 통계 · 쓰기 도구

여기부터는 우리가 브라우저 진단용 서버를 붙일 때 본 네 가지(아래 상자). 1~3은 붙이는 명령에 넣고, 4는 붙인 다음 권한에서 정한다.

버전을 적어 고정한다. 패키지가 바뀌는 때를 내가 고르려고.
서버가 띄우는 프로그램이 어떻게 뜨는지. 브라우저를 다루는 서버라면 창 없이 뜨는지, 내가 로그인해 둔 프로필이 아니라 따로 떨어진 프로필을 쓰는지. 옵션 이름은 서버마다 달라서 그 서버의 설명서나 --help 로 확인한다.
사용 통계를 보내는지. 보낸다면 끄는 옵션부터 찾는다.
쓰기 도구는 승인 뒤에. 읽기 도구만 승인 없이 쓰게 하고, 클릭 · 입력 · 업로드 · 스크립트 실행 같은 도구는 승인 대상으로 남긴다. 우리는 이 선을 훅에 그었다(아래 상자). 4단계의 허용 · ask 규칙으로 그어도 된다.

공식 문서의 경고도 같은 쪽. 「연결하기 전에 각 서버를 믿을 수 있는지 확인하라. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험에 노출될 수 있다.」 아무 페이지나 읽어 오는 브라우저형 서버가 바로 그 경우라, 우리는 붙인 뒤에도 쓰기 도구를 승인 뒤에 남겨 뒀다.

실제로 겪은 일

10월 3일, 우리 쪽 Claude Code에 브라우저 진단용 MCP 서버를 하나 붙였다. 버전은 고정, 브라우저는 화면 없이 격리된 프로필로, 사용 통계 전송(텔레메트리)은 끔. 그다음 손본 곳이 도구 권한. 훅에서 읽기 전용 진단 도구만 승인 없이 지나가게 했고, 클릭 · 입력 · 업로드 · 스크립트 실행 도구는 계속 승인을 거치게 남겼다.

내 설정 점검표: 클로드 코드 MCP 설정

서버가 어느 범위에 붙었는지 claude mcp get 으로 봤나. 같은 이름이 여러 범위에 있으면 local 이 이긴다.
claude mcp list 에 ✔ Connected 가 뜨나. ! Needs authentication 이면 /mcp 에서 인증.
키 값이 명령줄 · .mcp.json · 저장소에 그대로 들어가 있지 않나. .mcp.json 엔 ${API_KEY} 같은 자리만.
남이 만든 저장소를 claude -p 로 돌리기 전에 .mcp.json 을 열어 봤나.
내 컴퓨터에서 도는 서버의 패키지에 버전을 적었나.
허용 규칙에 서버 전체(mcp__<서버>__*)를 넣지 않았나. 읽기 도구만 이름으로.
ask 에 서버 전체를 넣어서 허용 규칙을 덮고 있지 않나.
바깥 페이지를 읽어 오는 서버라면 쓰기 도구가 승인 뒤에 있나.

같이 읽을 글

7편 — Claude Code 권한 설정(permissions)과 hooks 예시: auto mode에서 계속 막힐 때 손본 settings.json 세 곳: 허용 규칙과 훅의 기초. 4단계 규칙을 넣을 settings.json 자리.
2편 — Claude Code 설치(클로드코드 설치)부터 첫 자동화까지: 리눅스에서 매일 도는 작업 만들기: MCP 서버를 안 부르는 플래그까지 써 가며 claude -p 입력 토큰을 잰 기록.

다음 글은 클로드 코드 서브에이전트 사용법. Claude Code에서 서브에이전트를 만들고 일을 맡기는 방법을 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

클로드 코드 텔레그램 연동 · claude code telegram notification: Notification 훅에 sendMessage 한 번, 부르는 건 승인이 필요할 때만

코드짜는아빠 — Tue, 20 Oct 2026 10:19:35 +0900

필요한 건 셋: 봇 토큰, 알림을 받을 대화의 chat_id, Claude Code 설정 파일의 Notification 훅 한 블록. Claude Code는 입력이나 권한 승인을 기다릴 때 알림을 보내고, 그때 Notification 훅이 돈다. 훅이 부르는 스크립트는 텔레그램 Bot API sendMessage 한 번이면 끝. matcher 에 permission_prompt 를 적으면 도구 사용 승인을 기다릴 때만 보낸다. 남는 건 어느 순간에 부르게 하느냐인데, 우리는 승인이 필요한 순간에만 보내고 일반 승인 요청의 답은 텔레그램 답장이 아니라 작업하던 채팅에서 받는다. 출처는 Claude Code 훅 문서 · 훅 안내 · 채널 문서 · Telegram Bot API · 봇 기능 문서, 모두 2026-10-20 조회.

1단계: BotFather 에서 봇을 만들고 토큰을 받는다

텔레그램에서 BotFather 를 열고 /newbot 을 보낸다. 표시 이름과 bot 으로 끝나는 사용자명을 정하면 토큰이 나온다. 봇 기능 문서의 경고 한 줄: 「토큰은 안전하게 보관하라. 누구든 그 토큰으로 봇을 조종할 수 있다.」 잃어버렸거나 샌 것 같으면 BotFather 의 /token 으로 새로 만든다. 그래서 아래 예시는 토큰을 설정 파일이나 스크립트 본문에 적지 않고, 나만 읽을 수 있는 파일 하나에 따로 둔다.

mkdir -p ~/.config
[ -e ~/.config/notify-telegram.conf ] || install -m 600 /dev/null ~/.config/notify-telegram.conf

파일은 권한부터 600 으로 만들고, 값은 편집기로 넣을 것. echo 로 넣으면 토큰이 셸 기록에 남는다.

# ~/.config/notify-telegram.conf  (권한 600)
BOT_TOKEN='<BOT_TOKEN>'
CHAT_ID='<CHAT_ID>'   # 2단계에서 찾은 숫자로 바꾼다

값은 꺾쇠까지 지우고 작은따옴표 안에 넣는다.

2단계: 봇에게 한 번 말을 걸고 getUpdates 로 chat_id 를 찾는다

chat_id 를 알아내는 한 가지 방법은 봇에게 아무 메시지나 한 번 보낸 뒤 getUpdates 를 부르는 것.

source ~/.config/notify-telegram.conf   # 이 단계에선 BOT_TOKEN 만 진짜 값으로 바꾼 상태
curl -sS -K <(printf 'url = "https://api.telegram.org/bot%s/getUpdates"\n' "$BOT_TOKEN") \
  | jq '.result[].message.chat.id'

나온 숫자가 그 대화의 chat_id. getUpdates 는 봇에 웹훅이 걸려 있으면 동작하지 않고, 업데이트는 24시간을 넘겨 보관되지 않는다. 이 숫자도 토큰처럼 글이나 캡처에 올리지 말 것.

3단계: 훅이 부를 스크립트 — sendMessage 한 번

훅은 표준 입력으로 JSON 을 받는다. Notification 이면 공통 필드에 더해 알림 문구 message, 있을 때만 오는 title, 어떤 종류인지 알려 주는 notification_type 이 들어온다. 이 중 종류와 문구만 꺼내 보내는 예시.

#!/bin/bash
# ~/.claude/hooks/notify-telegram.sh
set -euo pipefail
source "$HOME/.config/notify-telegram.conf"

INPUT=$(cat)
TYPE=$(jq -r '.notification_type // "unknown"' <<< "$INPUT")
MSG=$(jq -r '.message // ""' <<< "$INPUT")

curl -sS -o /dev/null \
  -K <(printf 'url = "https://api.telegram.org/bot%s/sendMessage"\n' "$BOT_TOKEN") \
  --data-urlencode "chat_id=${CHAT_ID}" \
  --data-urlencode "text=[Claude Code] ${TYPE}: ${MSG}"

토큰이 든 주소는 명령줄 인자 대신 curl 설정(-K)으로 넘겼다. 입력에 같이 오는 작업 폴더(cwd)나 대화 기록 경로(transcript_path)는 일부러 보내지 않는다. 알림 문구는 텔레그램 서버를 거쳐 가니까.

4단계: settings.json 의 Notification 훅에 건다 (2026-10-20 공식 문서 기준)

스크립트에 실행 권한(chmod +x, 5단계)을 주고, 사용자 설정 ~/.claude/settings.json 의 hooks 안에 Notification 을 더한다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME\"/.claude/hooks/notify-telegram.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

이미 hooks 가 있다면 통째로 바꾸지 말고 Notification 을 옆 키로 더한다. 공식 안내 그대로. matcher 를 비우면 모든 알림 종류에 돈다. 공식 표에는 열두 가지가 있고, 이 글에 닿는 건 이 셋이다.

`matcher`	언제 도나(공식 문서)
`permission_prompt`	도구 사용이나 샌드박스 명령의 네트워크 요청을 승인해야 하고, 승인 창이 6초쯤 기다렸을 때
`idle_prompt`	Claude가 응답을 마치고 60초쯤 지났는데 입력이 없을 때
`agent_needs_input`	에이전트 뷰가 열려 있는 동안 백그라운드 세션이 입력을 기다리기 시작할 때

timeout 은 초 단위. 명령형 훅의 기본값은 600초라, 알림 하나에 그만큼 기다릴 이유가 없어 10초로 줄였다. 스크립트 경로는 공식 보안 권고대로 절대 경로로 적었고, 셸 형태라 큰따옴표로 감쌌다. 훅은 내 사용자 권한 그대로 도니까, 남이 준 스크립트는 읽어 보고 넣을 것. 대화형 세션에서는 그 폴더의 작업 공간 신뢰 창을 받아들이기 전까지 사용자 설정의 훅도 돌지 않는다. Notification 훅은 알림을 막거나 바꾸지 못하고, 문서도 바깥 서비스로 알림을 넘기는 용도라고 적는다.

5단계: /hooks 로 확인하고 시험 메시지를 보낸다

Claude Code 프롬프트에서 /hooks 를 치면 Notification 아래에 방금 넣은 훅이 보여야 정상. 안 보이면 JSON 끝의 쉼표나 주석부터. 스크립트만 따로 시험하려면 예시 JSON 을 넣어 돌려 본다.

chmod +x ~/.claude/hooks/notify-telegram.sh
echo '{"notification_type":"permission_prompt","message":"Claude needs your permission"}' \
  | ~/.claude/hooks/notify-telegram.sh
echo $?

텔레그램에 메시지가 오고 종료 코드가 0 이면 스크립트 쪽은 된 셈. 끝으로 공식 안내의 시험 순서대로 Shift+Tab 을 눌러 상태 줄에 manual mode on 이 보이게 하고, 권한이 필요한 일을 시킨 뒤 터미널에서 다른 창으로 옮겨 본다. 승인 창이 6초쯤 기다리면 알림이 와야 한다. 자판을 칠 때마다 6초가 뒤로 밀리니, 손을 떼고 기다릴 것.

언제 부르게 했나: 승인이 필요한 순간에만, 답은 채팅으로

여기부터는 우리가 정한 기준. 승인 알림은 사람이 정해야 하는 일에만 보낸다. 밖으로 나가는 실행(게시 · 배포 · 발송 같은 것), 되돌리기 어렵거나 위험이 큰 선택, 범위가 넓어지는 일, 돈 · 고객 · 법 · 보안 결정, 최종 디자인 선택, 정해 둔 기준으로 못 푸는 막힘. 구현 세부, 테스트 고치기, 로컬 검증, 이미 승인된 범위 안에서 되돌릴 수 있는 선택은 알리지 않기로 했다.

알림은 알림일 뿐, 승인이 아니다. 알림이 그 일을 대신 실행하지 않고, 비밀을 담지 않고, 나 말고 다른 곳으로 가지 않는다. Claude Code 훅으로 옮기면 이 기준에 가장 가까운 건 permission_prompt. idle_prompt 는 응답이 끝날 때마다 걸릴 수 있어 이 기준보다 넓다.

답장까지 텔레그램에서 하고 싶다면 공식 기능으로 Channels 가 있다. 실행 중인 세션에 텔레그램 메시지를 넣고 Claude가 같은 대화로 답하는 플러그인 방식이고, 2026-10-20 기준 연구 미리보기. 권한 승인을 채널로 넘기는 경우에 대해 채널 문서는 「채널로 답할 수 있는 사람은 누구나 세션의 도구 사용을 승인하거나 거부할 수 있다」고 적고, 그 권한을 맡길 만한 사람만 허용 목록에 넣으라고 한다. 우리 쪽 일반 승인 요청은 아래 상자의 이유로 답을 채팅에서 받는다.

실제로 겪은 일

우리 승인 요청 알림은 원래 텔레그램 답장으로도 승인을 받게 짜여 있었다. 10월 1일, 8월 1일부터 두 달 치 운영 로그를 다시 보니 승인 요청 알림은 162건 나갔는데 일반 승인 요청에 대한 텔레그램 답장이 기록된 적은 한 번도 없었다. 그동안 실제 승인은 전부 채팅에서 했고, 일이 멈춘 적도 없다. 답장을 읽는 프로그램 둘이 같은 봇에서 따로 업데이트를 받아 가며 서로의 업데이트를 지우고 있었던 것도 그때 드러났다. 그날 나는 「알림만 · 답은 채팅」을 골랐고, 알림 문구에는 「텔레그램 답장은 기록되지 않습니다. 답은 채팅으로 주세요.」가 들어갔다.

내 설정 점검표: 클로드 코드 텔레그램 알림

토큰과 chat_id 가 settings.json · 스크립트 본문 · 저장소에 들어가 있지 않나. 나만 읽는 파일 하나에 따로 뒀나.
토큰이 든 주소가 명령줄 인자로 넘어가지 않나.
matcher 가 정말 알림을 받고 싶은 종류인가. 비워 두면 모든 종류에 돈다.
알림 문구에 작업 폴더 경로 · 대화 기록 경로 · 비밀이 섞이지 않나.
/hooks 에 Notification 훅이 보이나. 시험 JSON 으로 돌렸을 때 텔레그램에 메시지가 오고 종료 코드가 0 인가(curl 은 텔레그램이 오류를 돌려줘도 0 으로 끝난다).
같은 봇에서 getUpdates 로 답장을 읽는 프로그램이 둘 이상 돌고 있지 않나. 더 큰 offset 으로 부르는 순간 그 앞 업데이트는 확인된 것으로 치고 잊힌다.
텔레그램 답장을 승인으로 쓸 생각이라면, 그 답장이 어디에 기록되는지부터 확인했나.

같이 읽을 글

7편 — Claude Code 권한 설정(permissions)과 hooks 예시: auto mode에서 계속 막힐 때 손본 settings.json 세 곳: settings.json 자리와 SessionStart 훅. 이 글의 훅 기초.
2편 — Claude Code 설치(클로드코드 설치)부터 첫 자동화까지: 리눅스에서 매일 도는 작업 만들기: 훅 대신 정해진 시각에 알림을 보내는 서비스를 따로 둔다면, systemd 사용자 서비스가 PATH 를 물려받지 않는 함정부터.

다음 글은 클로드 코드 MCP 연결 · 설정. Claude Code에 MCP 서버를 붙이고 설정하는 방법을 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

claude code skills vs agents · 클로드 코드 스킬 vs 서브에이전트: 지금 대화에서 다시 쓸 절차는 스킬, 결과만 받을 일은 서브에이전트

코드짜는아빠 — Mon, 19 Oct 2026 10:49:09 +0900

「다시 쓸 프롬프트나 작업 흐름을 서브에이전트의 독립 컨텍스트가 아니라 메인 대화 컨텍스트에서 돌리고 싶다면, 대신 스킬을 고려하라.」 Claude Code 서브에이전트 문서의 한 줄을 옮기면 이렇다. 두 기능을 가르는 건 결국 일이 어느 컨텍스트에서 도느냐. 스킬(SKILL.md)은 Claude가 지금 대화 안에서 꺼내 쓰는 지시이고, 서브에이전트(.claude/agents/)는 자기 컨텍스트 창에서 일한 뒤 결과만 돌려주는 전문 조수다. 그래서 대화를 이어 가며 같이 쓸 절차는 스킬에, 출력이 길거나 도구를 묶어야 하거나 혼자 끝낼 수 있는 일은 서브에이전트에 둔다. 기준은 2026년 10월 19일에 읽은 Claude Code 공식 문서(Skills · Subagents).

claude code skills vs agents 한눈에 (2026-10-19 공식 문서 기준)

검색어의 agents 는 .claude/agents/ 에 두는 서브에이전트로 보고 썼다. 두 문서에 흩어진 내용을 표 하나로 모으면 이렇다.

	스킬	서브에이전트
무엇인가	`SKILL.md` 에 적은 지시. Claude가 도구 상자에 넣어 두고 필요할 때 쓰거나, 사람이 `/스킬이름` 으로 직접 부른다	정해진 종류의 일을 맡는 전문 조수. 자기 시스템 프롬프트 · 도구 · 권한을 따로 가진다
파일 위치	프로젝트 `.claude/skills/<이름>/SKILL.md`, 개인 `~/.claude/skills/<이름>/SKILL.md`. 이름이 같으면 회사 관리 > 개인 > 프로젝트	프로젝트 `.claude/agents/`, 개인 `~/.claude/agents/`. 이름이 같으면 회사 관리 > 실행 옵션 `--agents` > 프로젝트 > 개인 > 플러그인
파일 모양	스킬 폴더 하나에 `SKILL.md`. 위쪽 frontmatter 에 `description` 같은 필드, 아래 본문이 지시	Markdown 파일 하나. YAML frontmatter(필수는 `name` · `description`) 아래 본문이 그 서브에이전트의 시스템 프롬프트
컨텍스트	지금 대화 안. `context: fork` 를 주면 서브에이전트에서 돈다	새로 시작하는 독립 컨텍스트. 대화 기록 · 이미 쓴 스킬 · 이미 읽은 파일을 보지 못하고, Claude Code 시스템 프롬프트 대신 자기 본문과 작업 폴더 같은 환경 정보를 받는다. 예외는 포크 — 지금 대화를 통째로 물려받는 서브에이전트다
불러오는 방식	평소엔 `description` 만 컨텍스트에 있고, 쓸 때 본문 전체가 실린다	Claude가 요청 · `description` · 지금 상황을 보고 맡긴다. 이름을 말하거나 `@` 로 골라 직접 맡길 수도 있다
맞는 일	메인 대화 안에서 다시 쓸 프롬프트 · 작업 흐름	메인 대화엔 필요 없는 긴 출력이 나오는 일, 도구 · 권한을 묶어야 하는 일, 혼자 끝내고 요약을 돌려줄 수 있는 일

출처는 Claude Code 스킬 문서, 서브에이전트 문서, 둘 다 2026-10-19 조회.

이름이 겹칠 때의 우선순위는 방향이 반대라 봐 둘 만하다. 스킬은 개인 것이 프로젝트 것을 이기고, 서브에이전트는 거꾸로 프로젝트 것이 먼저.

서브에이전트 안에도 CLAUDE.md 는 실린다. 메인 대화가 읽는 단계 그대로, 내장 Explore · Plan 서브에이전트만 빼고. 빼고 싶다면 frontmatter 에 omitClaudeMd: true(v2.1.271 이상)를 둔다. 그래도 회사 관리 정책 파일과, 서브에이전트가 손대는 하위 폴더의 CLAUDE.md 는 실린다.

언제 무엇을 쓰나: 대화가 필요하면 스킬, 결과만 필요하면 서브에이전트

그럼 어느 쪽에 맡길지는 어떻게 고를까? 서브에이전트 문서가 든 기준은 이렇다.

메인 대화가 맞을 때 — 주고받으며 여러 번 다듬어야 할 때, 계획 · 구현 · 테스트처럼 여러 단계가 맥락을 많이 나눌 때, 한 곳만 빠르게 고칠 때, 기다리는 시간이 중요할 때(포크가 아닌 서브에이전트는 처음부터 시작해 맥락을 모으는 데 시간이 걸릴 수 있다).
서브에이전트가 맞을 때 — 메인 대화에선 다시 안 볼 긴 출력이 나올 때, 도구 제한이나 권한을 따로 걸고 싶을 때, 혼자 끝내고 요약을 돌려줄 수 있을 때.

메인 대화 쪽 일에서 같은 지시를 매번 다시 쓰고 있다면, 그걸 담아 두는 곳이 스킬이다.

문서 기준을 질문 셋으로 줄이면 이 순서.

이 일에 지금 대화 내용이 필요한가. 필요하면 스킬이나 메인 대화. 서브에이전트는 대화 기록을 보지 못하고, Claude가 일을 요약해 적은 위임 메시지에서 출발한다. 대화를 그대로 넘겨야 하는 곁가지 일이라면 문서는 포크를 따로 안내한다.
결과가 길고 다시 안 볼 내용인가. 검색 결과 · 로그 · 파일 내용이 메인 대화를 덮을 것 같으면 서브에이전트. 그 일은 서브에이전트 컨텍스트에서 끝나고 요약만 돌아온다.
도구나 권한을 묶어야 하나. 그렇다면 서브에이전트의 tools · disallowedTools 로. 같은 일을 매번 같은 지시로 하게 하는 게 목적이라면 스킬로 충분하다.

섞어 쓰는 두 방법: 스킬을 서브에이전트로 돌리거나, 서브에이전트에 스킬을 싣거나

두 기능은 서로를 불러 쓸 수도 있다.

스킬에 context: fork 를 준다. Claude Code가 agent 필드에 적은 종류의 서브에이전트를 새로 띄우고, 스킬 본문을 그 프롬프트로 넘긴다. agent 에는 내장 Explore · Plan · general-purpose 나 직접 만든 .claude/agents/ 서브에이전트를 적을 수 있고, 비우면 general-purpose. 대화 기록은 넘어가지 않으니 스킬 지시가 혼자서도 읽혀야 한다. 이름과 달리 지금 대화를 통째로 넘기는 포크가 아니라고 문서에 따로 적혀 있다.
서브에이전트에 skills 를 적는다. 적은 스킬의 본문 전체가 시작할 때 서브에이전트 컨텍스트에 들어간다(목록 앞 32개 이름까지). 미리 싣는 목록일 뿐이라, 적지 않은 프로젝트 · 개인 · 플러그인 스킬도 서브에이전트가 Skill 도구로 찾아 쓸 수 있다. 스킬 쪽에 disable-model-invocation: true 가 있으면 서브에이전트에 미리 실리지 않는다.

문서는 둘을 서로 반대 방향이라고 설명한다. 앞은 스킬 본문이 고른 서브에이전트 안으로 들어가고, 뒤는 서브에이전트가 시스템 프롬프트를 쥔 채 스킬을 싣는 쪽. 어느 쪽이든 대화 기록 없이 시작하는 건 같다.

우리 기준: 규칙은 역할 파일 하나에, 스킬과 서브에이전트는 그 파일을 부르는 입구로

여기부터는 우리가 정한 기준. 역할 규칙 본문은 역할 파일 하나에 두고, 스킬과 서브에이전트 파일은 그 파일을 읽으라는 몇 줄로 끝낸다. 스킬 쪽 실물은 1편에 있고, 서브에이전트 쪽을 같은 모양으로 줄이면 아래와 같다.

---
name: reviewer
description: Reviews a finished draft against agents/reviewer.md. Use after a draft is written.
tools: Read, Grep, Glob
model: inherit
---

Read agents/reviewer.md and review the draft as that role.
Return your findings in the final message. Do not edit files.

공식 문서상 필수 필드는 name · description 둘뿐. tools 와 model 은 우리가 늘 적어 두는 필드다. tools 를 빼 두면 쓸 수 있는 도구를 전부 물려받으니까.

작성자와 다른 눈이 필요한 검토, 그러니까 QA · 반증 · 보안 같은 일은 서브에이전트에 맡긴다. 작성한 대화를 못 본다는 점이 이때는 장점.

서브에이전트가 다시 위임하지 못하게 tools 에 Agent 도 넣지 않는다. 문서 기준으로 서브에이전트는 기본값에서 메인 대화 아래 세 단계까지 자기 서브에이전트를 띄울 수 있고, tools 목록에 Agent 가 아예 없으면 띄우지 못한다. 위 예처럼 쓰기 도구가 없는 서브에이전트라면 결과는 마지막 메시지로.

실제로 겪은 일

10월 3일까지 우리 역할은 두 길로만 불렀다. 슬래시 스킬로 지금 세션이 역할을 입거나, 범용 에이전트에 긴 프롬프트를 붙여 띄우거나. 그날 내가 릴스에서 서브에이전트를 보고 「서브에이전트 진행」이라고 했고, QA · 반증 · 보안 같은 역할 다섯 개가 .claude/agents/ 에 서브에이전트 파일로 들어갔다. 파일마다 규칙은 복사하지 않고 원래 역할 파일을 읽으라는 내용만 있고, 도구 목록에 Agent 가 없다. 같은 날 시험에서는 반증 검토 서브에이전트가 이름으로 부르지 않았는데도 description 만 보고 불렸다.

내 저장소 점검표: 스킬 · 서브에이전트 나눠 쓸 때

매번 다시 붙여 넣는 지시 · 절차가 있나. 메인 대화 안에서 쓸 거라면 스킬로 옮긴다.
서브에이전트에 맡기는 일이 지금 대화 내용 없이도 서나. 서브에이전트는(포크 제외) 대화 기록 · 이미 읽은 파일을 보지 못한다.
서브에이전트 파일에 tools 를 적었나. 빼면 쓸 수 있는 도구를 전부 물려받는다. 다시 위임하지 않게 하려면 목록에 Agent 를 넣지 않는다.
스킬과 서브에이전트 모두 description 맨 앞에 언제 쓰는지가 있나. 스킬 목록에서는 description 과 when_to_use 를 합쳐 1,536자에서 잘린다.
같은 이름이 개인 · 프로젝트 양쪽에 있나. 스킬은 개인 것이, 서브에이전트는 프로젝트 것이 쓰인다.
규칙 본문이 스킬 · 서브에이전트 파일에 복사돼 있지 않나. 한 파일에만 두고 거기를 읽게 한다.
세션 중에 agents 폴더를 처음 만들었다면 Claude Code를 다시 시작했나. 이미 있던 폴더의 파일을 고친 건 몇 초 안에 다음 위임부터 반영된다.
SKILL.md 가 500줄을 넘지 않나. 긴 참고 내용은 다른 파일로 뺀다.

같이 읽을 글

1편 — Claude Code Skills 사용법(클로드 코드 스킬 만들기·적용 방법): 스킬 49개로 역할 44개를 돌려 본 실전: 스킬을 얇게 두고 규칙은 역할 파일에 두는 법, 실제 SKILL.md. 이 글의 스킬 기초.
9편 — Claude Code · Codex 한 저장소에서 충돌 막는 법(git worktree · git commit 경로 지정): 에이전트 둘이 동시에 커밋한 날: 서브에이전트는 파일만 쓰고 커밋은 부른 세션이 하게 둔 이유.

다음 글은 클로드 코드 텔레그램 연동. 작업이 승인을 기다릴 때 텔레그램으로 알림을 받게 한 방법을 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

claude.md agents.md 차이 · claude code agents.md: 공통 규칙은 AGENTS.md 에 두고 CLAUDE.md 는 불러오기 한 줄과 Claude 전용만

코드짜는아빠 — Fri, 16 Oct 2026 09:26:21 +0900

작업 폴더나 그 위에 CLAUDE.md 가 있으면 Claude Code는 기본값에서 AGENTS.md 를 읽지 않는다. 두 파일의 차이는 결국 누가 읽느냐에서 갈린다. CLAUDE.md 는 Claude Code가 읽는 지시 파일, AGENTS.md 는 Codex를 비롯한 여러 코딩 에이전트가 같이 읽는 공개 형식의 지시 파일. 그래서 둘 다 쓴다면 공통 규칙은 AGENTS.md 한 곳에 적고, CLAUDE.md 에는 @AGENTS.md 한 줄과 Claude Code에만 필요한 지시를 둔다. 기준은 2026년 10월 16일에 읽은 Claude Code · Codex 공식 문서와 agents.md 사이트다.

claude.md 와 agents.md 차이 한눈에 (2026-10-16 공식 문서 기준)

세 곳에 적힌 내용을 표 하나로 모았다.

	CLAUDE.md	AGENTS.md
누가 읽나	Claude Code	Codex, Cursor, Jules 등 agents.md 사이트가 꼽은 여러 코딩 에이전트. Claude Code도 v2.1.277 이상에서 조건에 따라 읽음
어디에 두나	저장소 맨 위 `./CLAUDE.md`(또는 `./.claude/CLAUDE.md`), 내 전역 `~/.claude/CLAUDE.md`, 나만 쓸 `CLAUDE.local.md`, 하위 폴더	저장소 맨 위와 하위 폴더(Codex는 실행한 폴더까지). Codex는 전역 `~/.codex/AGENTS.md` 도 읽음
문법	마크다운. `@경로` 로 다른 파일을 불러옴(네 단계까지)	그냥 마크다운. 정해진 필드 없음
불러오는 때	세션을 시작할 때 실행 폴더와 그 위 폴더의 파일을 이어 붙임. 하위 폴더 파일은 그 폴더 파일을 다룰 때	Codex는 시작할 때 한 번(실행마다). 저장소 루트에서 현재 폴더까지 폴더마다 한 파일, 합쳐서 기본 32KiB 까지
지시가 겹치면	파일끼리 덮어쓰지 않고 이어 붙음. 지시가 어긋나면 Claude가 아무 쪽이나 고를 수 있음	편집하는 파일에 가장 가까운 `AGENTS.md` 가 이기고, 채팅에서 직접 한 지시는 그보다 위(agents.md 사이트). Codex는 실행한 폴더에 가까운 파일이 뒤에 붙어 앞 지시를 덮고, 실행한 폴더 아래의 파일은 읽지 않음

출처는 Claude Code 메모리 문서, Codex 「Custom instructions with AGENTS.md」, agents.md, 모두 2026-10-16 조회. Claude Code가 AGENTS.md 를 직접 읽을 때는 그 안의 @경로 불러오기도 펼친다.

Claude Code가 AGENTS.md 를 읽는 경우, 안 읽는 경우 (v2.1.277 이상)

공식 문서의 기본값 표를 옮기면 이렇다.

저장소에 있는 것	Claude Code가 읽는 것(기본값)
`AGENTS.md` 만 있고, 작업 폴더나 그 위에 `CLAUDE.md` · `CLAUDE.local.md` 가 없음	`AGENTS.md`
`AGENTS.md` 와 함께, 작업 폴더나 그 위에 `CLAUDE.md` 또는 `CLAUDE.local.md`	`CLAUDE.md` 쪽만
`AGENTS.md` 를 불러오는 `CLAUDE.md`	`CLAUDE.md`, 불러온 `AGENTS.md` 포함

여기서 「있다」로 치는 건 작업 폴더나 그 위 폴더의 CLAUDE.md · .claude/CLAUDE.md · CLAUDE.local.md 셋. 내 전역 ~/.claude/CLAUDE.md, 회사 관리 정책 CLAUDE.md, .claude/rules/ 파일은 치지 않고 AGENTS.md 와 같이 실린다. 그래서 생기는 함정 하나. AGENTS.md 만 쓰던 저장소에 나만 쓸 메모를 두려고 CLAUDE.local.md 를 만들면, 그때부터 Claude Code가 AGENTS.md 를 읽지 않는다. 그 파일을 두면서 AGENTS.md 도 읽히게 하려면 Project instructions 를 claude-md-and-agents-md 로 바꾸라는 게 문서의 방법.

하위 폴더의 AGENTS.md 는 Claude가 그 폴더의 파일을 Read 도구로 열 때 실린다. 작업 폴더와 그 위에 치는 파일이 없고, 그 폴더에도 CLAUDE.md 계열 파일이 하나도 없을 때만.

AGENTS.md 를 직접 읽는 건 v2.1.277 이상부터다. 그보다 낮은 버전, /plugin 으로 AGENTS.md 를 읽는 내장 플러그인을 끈 경우, v2.1.276 이하에서 올린 직후의 첫 세션 일부는 예외. 이런 세션은 CLAUDE.md 만 읽고, /config 에 Project instructions 항목도 나오지 않는다. v2.1.281 전에는 Amazon Bedrock 세션이나 텔레메트리를 끈 세션 일부도 CLAUDE.md 만 읽었다. Claude Code가 아예 읽지 않는 이름도 있다. AGENTS.local.md, AGENTS.override.md, 그리고 .agents/ 폴더 아래 파일.

읽혔는지는 /memory 목록에 AGENTS.md 경로가 있는지로 본다. 대화형 세션이라면 no CLAUDE.md found; AGENTS.md loaded: 로 시작하는 줄도 찍힌다.

Codex는 AGENTS.md 를 이렇게 읽는다

Codex 쪽은 어떨까? 문서에는 「Codex reads AGENTS.md files before doing any work.」라고 적혀 있다. 지시 묶음은 시작할 때 한 번 만든다(실행마다, TUI 라면 보통 띄운 세션마다). 그러니 고친 내용은 다음 실행부터.

전역 — Codex 홈(기본 ~/.codex, CODEX_HOME 으로 바꿀 수 있음)에 AGENTS.override.md 가 있으면 그것, 없으면 AGENTS.md. 비어 있지 않은 첫 파일 하나만 쓴다.
프로젝트 — 프로젝트 루트(보통 Git 루트)에서 현재 작업 폴더까지 내려가며, 폴더마다 AGENTS.override.md → AGENTS.md → 설정 project_doc_fallback_filenames 에 적은 이름 순으로 보고 한 파일만 넣는다.
합치기 — 루트 쪽부터 빈 줄을 끼워 이어 붙인다. 현재 폴더에 가까운 파일이 뒤에 오므로 앞의 지시를 덮는다. 빈 파일은 건너뛴다.
크기 — 합친 크기가 project_doc_max_bytes(기본 32KiB)에 닿으면 더 붙이지 않는다. 한도를 올리거나 하위 폴더로 나누라고 문서는 권한다.

CLAUDE.md 는 이 목록에 없다. 대체 이름에 넣어 봐야, 같은 폴더에 AGENTS.md 가 있으면 한 폴더 한 파일이라 그쪽이 먼저 잡히는 구조. 실린 지시는 저장소 맨 위에서 아래처럼 요약해 달라고 물어 확인한다.

codex --ask-for-approval never "Summarize the current instructions."

둘 다 쓸 때 나누는 법: 공통은 AGENTS.md, Claude 전용은 CLAUDE.md

한 저장소에 두 파일을 같이 둔다면 이 순서로 나눈다.

공통 규칙은 AGENTS.md 에. 빌드 · 테스트 명령, 코드 관례처럼 어느 에이전트든 지켜야 할 것을 적는다. agents.md 사이트는 README 를 사람용(빠른 시작, 프로젝트 소개, 기여 안내)으로 두고, 에이전트에게 필요한 빌드 단계 · 테스트 · 관례 같은 세부를 AGENTS.md 에 두라고 설명한다.
CLAUDE.md 는 맨 위에 @AGENTS.md, 그 아래 Claude 전용. Claude는 불러온 파일을 먼저 읽고 그다음 나머지를 읽는다. 공식 문서의 예시 그대로 옮기면 이렇다.
```
@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.
```
같은 규칙을 두 파일에 나눠 쓰지 않는다. 지시가 겹칠 때의 처리가 도구마다 다르다. Claude Code는 파일을 이어 붙여 읽고 어긋나면 아무 쪽이나 고를 수 있고, agents.md 사이트 기준으로는 편집하는 파일에 가장 가까운 AGENTS.md 가 이긴다. 한 규칙은 한 파일에만 두는 편이 안전하다.
「AGENTS.md 를 읽어라」 문장으로만 가리키지 않는다. 그렇게 적힌 CLAUDE.md 라면 Claude는 AGENTS.md 를 열기로 했을 때만 본다. 문서는 그 문장을 @AGENTS.md 불러오기로 바꾸거나, CLAUDE.md 를 지워 AGENTS.md 를 직접 읽게 하라고 적었다. 지우는 쪽은 그 파일에 다른 내용이 없을 때 얘기.
Claude 전용 내용이 없다면 CLAUDE.md 없이, 또는 심볼릭 링크로. CLAUDE.md 가 없으면 v2.1.277 이상 Claude Code는 AGENTS.md 를 직접 읽는다. 링크는 ln -s AGENTS.md CLAUDE.md. 이때 Claude의 Edit · Write 도구는 링크를 거쳐 쓰지 않고 대상인 AGENTS.md 를 고치라고 안내한다. Windows 에서 clone 하는 사람이 있으면 링크가 한 줄짜리 CLAUDE.md 로 풀릴 수 있어서, 그때는 불러오기 쪽을 쓰라고 문서에 적혀 있다.
설정으로 둘 다 읽게 하는 길도 있다. /config 에서 Project instructions 를 claude-md-and-agents-md 로 두면 폴더마다 CLAUDE.md 다음에 AGENTS.md 를 읽는다. 이 값을 설정 파일에 적을 때는 ~/.claude/settings.json 같은 내 설정이나 관리 설정에서만 읽히고, 저장소의 프로젝트 · 로컬 설정 파일에 적으면 무시된다. 저장소를 받는 사람 모두에게 같은 결과를 주려면 저장소에 들어가는 불러오기 한 줄 쪽이 맞는 셈. 불러오기를 남겨 둔 채 이 값을 켜도 AGENTS.md 를 두 번 읽지는 않는다.
/import 는 한 번 복사다. /import 는 다른 코딩 에이전트 설정을 가져오면서 AGENTS.md 같은 지시 파일을 맞는 CLAUDE.md 뒤에 한 번 복사해 붙인다(v2.1.213 이상). 복사한 뒤로는 두 파일을 따로 고쳐야 하니, 계속 같이 쓸 규칙이면 불러오기가 낫다.
에이전트가 같이 지킬 규칙은 메모리가 아니라 파일에. Claude Code의 auto memory 는 Claude가 스스로 적는 메모다. Codex 문서가 지시 파일로 드는 건 AGENTS.override.md · AGENTS.md 와 설정에 적은 대체 이름이다.

확인은 다음 세션에서 /context 를 쳐 Memory files 에 CLAUDE.md 가 보이는지로.

실제로 겪은 일

우리 저장소도 두 파일을 같이 쓴다. AGENTS.md 는 Codex CLI · Claude Code를 포함한 모든 에이전트용 전체 운영 규칙이고, CLAUDE.md 는 그 요약에 「둘이 다르면 AGENTS.md 를 따른다」를 적어 둔 세션 진입점이다. 10월 12일, 내가 짚고 나서 확인해 보니 여러 세션에 걸쳐 준 프런트엔드 지시가 Claude 메모리에만 있고 저장소 문서에는 한 줄도 없었다. 그날 「이건 에이전트 공통에 심어두고」라고 지시했고, 내가 건네는 링크 · 자료를 출처와 분석까지 남기는 규칙이 AGENTS.md 에 여섯 단계짜리 새 절로 들어갔다. CLAUDE.md 에 붙은 건 요약 한 줄과 그 절 번호인데, 우리 CLAUDE.md 가 아직 @AGENTS.md 로 불러오지 않고 요약을 따로 적는 쪽이라 위 나누는 법 3번 기준으로는 이것도 고칠 거리다.

내 저장소 점검표: claude.md · agents.md 같이 쓸 때

공통 규칙이 AGENTS.md 한 곳에만 있나. CLAUDE.md 에 같은 규칙이 또 적혀 있지 않나.
CLAUDE.md 가 @AGENTS.md 로 불러오나. 「읽어라」 문장으로만 가리키고 있지 않나.
claude --version 이 v2.1.277 이상인가(Bedrock · 텔레메트리를 끈 세션은 v2.1.281 이상). AGENTS.md 만 쓰는 저장소에 CLAUDE.local.md 를 만들어 두지 않았나.
다음 세션의 /context Memory files 에 CLAUDE.md 가 보이나. AGENTS.md 를 직접 읽게 했다면 /memory 목록에 그 경로가 있나.
Codex 쪽에 AGENTS.override.md 가 남아 같은 폴더의 AGENTS.md 를 가리고 있지 않나. 합친 크기가 32KiB 를 넘지 않나.
심볼릭 링크를 쓴다면, Windows 로 clone 하는 사람은 없나.
모든 에이전트가 지킬 규칙이 한 도구의 메모리에만 남아 있지 않나.

같이 읽을 글

13편 — claude.md 파일 위치 · 클로드 코드 claude.md 작성법: 저장소 맨 위 CLAUDE.md 에, 200줄 안쪽으로 매번 필요한 것만: CLAUDE.md 를 어디에 두고 무엇을 적는지. 이 글의 앞 편.
5편 — Claude Code vs Codex 비교(클로드 코드 vs 코덱스 차이): 둘 다 매일 쓰며 일을 나누는 법: 두 에이전트가 같은 규칙집을 읽으면서 일을 나누는 방식.

다음 글은 claude code skills vs agents. 스킬과 서브에이전트를 언제 나눠 쓰는지 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

claude.md 파일 위치 · 클로드 코드 claude.md 작성법: 저장소 맨 위 CLAUDE.md 에, 200줄 안쪽으로 매번 필요한 것만

코드짜는아빠 — Wed, 14 Oct 2026 17:46:32 +0900

claude.md 는 어디에 둬야 Claude Code가 읽을까? 팀이 같이 쓸 프로젝트 규칙은 저장소 맨 위 CLAUDE.md(또는 .claude/CLAUDE.md)에 둔다. 모든 프로젝트에 쓸 내 취향은 ~/.claude/CLAUDE.md, 이 프로젝트에서 나만 쓸 설정은 CLAUDE.local.md, 한 폴더에만 해당하는 규칙은 그 폴더 안의 CLAUDE.md. 작성법의 요점은 셋, 파일당 200줄 아래로 짧게, 맞았는지 확인할 수 있게 구체적으로, 코드를 보면 알 수 있는 내용은 빼고. 기준은 2026년 10월 14일에 읽은 Claude Code 공식 문서다.

claude.md 파일 위치 네 곳과 읽히는 순서 (2026-10-14 공식 문서 기준)

Claude Code 메모리 문서가 드는 위치를 개인 · 팀 쪽 넷으로 추리면 이렇다. 문서에 적힌 파일 이름은 대문자 CLAUDE.md.

범위	위치	넣을 것(문서 예시)	읽히는 때
프로젝트	`./CLAUDE.md` 또는 `./.claude/CLAUDE.md`	빌드 · 테스트 명령, 코딩 규칙, 구조 결정, 이름 규칙, 자주 쓰는 작업 흐름	시작할 때
사용자	`~/.claude/CLAUDE.md`	모든 프로젝트에 쓰는 코드 스타일 취향, 개인 도구 단축	시작할 때
로컬	`./CLAUDE.local.md`	이 프로젝트에서 나만 쓰는 것(샌드박스 URL, 즐겨 쓰는 테스트 데이터)	시작할 때
하위 폴더	`하위폴더/CLAUDE.md`	그 폴더 아래에서만 필요한 지시	Claude가 그 폴더의 파일을 읽거나 쓰거나 고칠 때

프로젝트 파일은 버전 관리로 팀과 같이 쓰고, CLAUDE.local.md 는 .gitignore 에 넣어 나만 쓴다. 회사가 모든 사용자 기기에 까는 관리 정책 파일도 따로 있다. 리눅스 · WSL 은 /etc/claude-code/CLAUDE.md, macOS 는 /Library/Application Support/ClaudeCode/CLAUDE.md, Windows 는 C:\Program Files\ClaudeCode\CLAUDE.md. 이 파일은 개인 설정으로 뺄 수 없다고 적혀 있다.

읽는 순서는? Claude Code는 실행한 폴더와 그 위의 모든 폴더에서 CLAUDE.md 와 CLAUDE.local.md 를 찾아 시작할 때 읽는다. foo/bar/ 에서 실행하면 foo/CLAUDE.md 와 foo/bar/CLAUDE.md 가 둘 다 실리는 식. 서로 덮어쓰지 않고 이어 붙고, 위 폴더 것이 먼저, 실행한 자리에 가까운 것이 나중에 놓인다. 같은 폴더 안에서는 CLAUDE.local.md 가 CLAUDE.md 뒤에 붙는다. 범위로 보면 조직 → 사용자 → 프로젝트 → 로컬 순.

하위 폴더의 CLAUDE.md 는 시작할 때 실리지 않는다. Claude가 그 폴더 안의 다른 파일을 읽거나 쓰거나 고칠 때 실린다. 새로 만든 걸 시험할 때는 Claude에게 쓰게 하지 말고 셸에서 직접 만든 뒤, 그 폴더의 파일 하나를 읽어 달라고 하라는 게 문서의 방법.

실렸는지는 세션에서 /context 를 치고 Memory files 목록으로 확인한다. 목록에 없는 파일은 Claude도 못 본다. 하위 폴더 파일은 예외. 실릴 때 목록 대신 터미널에 경로가 붙은 Loaded 줄로 찍힌다.

/memory 로 여는 목록은 사용자 · 프로젝트 범위의 CLAUDE.md · CLAUDE.local.md 위치. 사용자 · 프로젝트 CLAUDE.md 는 아직 없는 파일도 목록에 나오고, 고르면 편집기로 열리면서 없던 파일은 먼저 만들어진다. 내가 쓰는 CLAUDE.md 와 달리 Claude가 스스로 적어 두는 auto memory 를 켜고 끄는 것도 여기서.

/compact 로 대화를 줄인 뒤엔? 프로젝트 맨 위 CLAUDE.md 는 디스크에서 다시 읽혀 들어간다. 대화에서만 한 지시는 그때 사라질 수 있으니, 계속 지켜야 할 건 파일에 적어 두라는 게 문서의 설명.

처음 만들 때: `/init` 으로 뼈대를 받고 손으로 채운다

/init 을 돌리면 Claude가 코드베이스를 훑어 빌드 명령, 테스트 방법, 찾아낸 프로젝트 관례로 첫 CLAUDE.md 를 만든다. 파일이 이미 있으면 덮어쓰지 않고 고칠 점을 제안한다. 그다음은 Claude가 스스로 찾지 못할 지시를 사람이 더하는 순서. 환경 변수 CLAUDE_CODE_NEW_INIT=1 을 켜고 돌리면 CLAUDE.md · 스킬 · 훅 중 무엇을 만들지 먼저 묻고, 파일을 쓰기 전에 제안을 보여 준다.

claude.md 작성법: 매 세션 필요한 사실만, 확인할 수 있게

문서가 드는 「CLAUDE.md 에 더할 때」는 네 가지.

Claude가 같은 실수를 두 번째로 할 때
코드 리뷰에서 Claude가 이 코드베이스에 대해 알았어야 할 것이 걸렸을 때
지난 세션에 쳤던 정정이나 설명을 이번 세션에도 또 칠 때
새로 온 팀원에게도 같은 맥락이 필요할 때

넣을 것은 모든 세션에서 알아야 할 사실이다. 빌드 명령, 관례, 프로젝트 구조, 「항상 X 를 한다」 같은 규칙. 여러 단계짜리 절차나 코드 일부에만 필요한 건 스킬이나 경로 규칙(아래)으로 옮기라고 적혀 있다.

문장은 맞았는지 확인할 수 있을 만큼 구체적으로. 문서의 예를 옮기면 이렇다.

흐린 문장	확인되는 문장
「코드를 제대로 정리해」	「들여쓰기는 스페이스 2칸」
「변경 사항을 테스트해」	「커밋 전에 `npm test` 를 돌린다」
「파일을 정리해 둬」	「API 핸들러는 `src/api/handlers/` 에 있다」

비슷한 지시는 마크다운 제목과 글머리표로 묶는다. 빽빽한 문단보다 나뉜 절을 Claude가 더 따르기 쉽다는 설명.

긴 내용은 @경로 로 다른 파일을 불러와 나눌 수 있다. 상대 경로는 작업 폴더가 아니라 불러오는 파일이 있는 자리 기준이고, 불러온 파일이 또 다른 파일을 부르는 건 네 단계까지.

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

주의할 점 하나. 불러온 파일도 시작할 때 같이 실린다. 정리에는 도움이 돼도 컨텍스트 비용은 그대로인 셈이다. 경로를 불러오지 않고 글자로만 적으려면 백틱으로 감싼다(`@README`).

우리 저장소 CLAUDE.md 는 이 파일이 무엇인지부터 적었다. 전체 규칙은 AGENTS.md 에 두고 여기는 요약만 한다는 것, 둘이 다르면 AGENTS.md 를 따른다는 것. 2026년 10월 14일 기준 뼈대의 앞부분.

> **Role:** session entrypoint only. ... It summarizes `AGENTS.md` for convenience at session start. If this file conflicts with `AGENTS.md`, follow `AGENTS.md`.

## 1. Read First
Before doing any task work, read **`AGENTS.md`**. ...
## 2. Non-Negotiable Rules
## 3. Source of Truth
## 4. Before Acting Checklist

참고로 이 파일은 같은 날 기준 212줄이라, 문서가 말하는 200줄 목표를 조금 넘는다.

쓰지 말 것: 코드에 있는 것, 일부에만 필요한 것, 서로 부딪치는 것

빼라는 쪽도 문서에 꽤 구체적으로 나온다.

코드를 보면 알 수 있는 것. 폴더 구조, 의존성 목록, 아키텍처 개요. /doctor 점검은 저장소에 올린 CLAUDE.md 에서 이런 걸 깎자고 제안하고, 함정 · 이유 · 도구 기본값과 다른 관례는 남긴다.
코드 일부에서만 필요한 규칙. .claude/rules/ 아래 규칙 파일에 paths 를 달아 두면 맞는 파일을 다룰 때만 실린다.
서로 부딪치는 지시. 두 지시가 어긋나면 Claude가 아무거나 고를 수 있다. 사용자 규칙과 프로젝트 규칙도 서로를 덮어쓰지 않으니 둘을 맞춰 둬야 한다.
나만 쓰는 설정. 팀이 같이 보는 CLAUDE.md 대신 CLAUDE.local.md 나 ~/.claude/CLAUDE.md 로.
사람만 볼 메모를 맨 글로. 메모는 블록 단위 HTML 주석()으로 적는다. 이 주석은 컨텍스트에 넣기 전에 지워져 자리를 차지하지 않고, 코드 블록 안 주석은 남는다.
꼭 지켜져야 하는 금지. CLAUDE.md 는 강제 설정이 아니라 맥락이다. 시스템 프롬프트 뒤에 사용자 메시지로 들어가고, 엄격히 지켜진다는 보장은 없다고 문서에 적혀 있다. 무조건 막아야 하는 동작은 PreToolUse 훅, 커밋 전마다 돌아야 하는 일도 훅으로.
변경 이력. 이건 문서가 아니라 우리가 정한 기준. 「v1.5 에서 추가」 같은 줄은 Claude에게 시키는 행동이 없다(아래 상자).

경로 규칙은 .claude/rules/ 아래 마크다운 파일 맨 위에 paths 를 다는 식.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation

paths 가 붙은 규칙은 Claude가 맞는 파일을 읽거나 쓰거나 고칠 때만 실린다. paths 가 없는 규칙 파일은 .claude/CLAUDE.md 와 같은 우선순위로 시작할 때 실린다.

크기: 파일당 200줄 아래, 줄이는 길은 둘

문서의 목표치는 CLAUDE.md 파일 하나에 200줄 아래. 길수록 컨텍스트를 더 쓰고 지시를 따르는 정도가 떨어진다고 적었다. 권장 길이를 넘는 파일이 있으면 시작할 때와 /status 에서 경고가 뜬다. 4MiB 를 넘는 파일은 아예 건너뛴다. 줄이는 길은 둘, 경로 규칙으로 필요할 때만 싣거나 매 세션 필요 없는 내용을 덜어 내거나.

AGENTS.md 를 같이 쓴다면: `@AGENTS.md` 로 불러온다

Codex 같은 다른 코딩 에이전트용 AGENTS.md 가 있는 저장소라면 알아 둘 게 하나 있다. 기본값에서 Claude Code는 작업 폴더나 그 위에 CLAUDE.md(또는 CLAUDE.local.md)가 있으면 AGENTS.md 는 읽지 않고 CLAUDE.md 만 읽는다(AGENTS.md 를 직접 읽는 기능은 v2.1.277 이상). 둘 다 읽히게 하는 방법은 CLAUDE.md 에 @AGENTS.md 한 줄을 넣어 불러오는 것(/config 의 Project instructions 를 claude-md-and-agents-md 로 바꾸는 길도 문서에 있다). 위 우리 뼈대처럼 「AGENTS.md 를 읽어라」라고 글로만 적어 두면 Claude가 그 파일을 열기로 할 때만 본다고 문서는 적는다. 두 파일을 어떻게 나눠 쓰는지는 다음 글에서.

점검: `/doctor prompt-audit` (2026-10-14 기준 v2.1.283 이상)

세션에서 /doctor prompt-audit 를 치면 Claude가 지시 파일을 훑어 낡았거나 서로 부딪치는 내용을 찾는다. 예전 모델에 맞춰 쓴 지시, 없는 파일이나 명령을 가리키는 줄, 서로 어긋나는 파일 같은 것. 결과는 고칠 안이 붙은 보고서로 나오고, 고쳐 달라고 하기 전까지 파일은 하나도 바뀌지 않는다. 기본 범위는 CLAUDE.md · CLAUDE.local.md · AGENTS.md, 그리고 .claude/ · ~/.claude/ 아래의 규칙 · 스킬 · 명령 · 서브에이전트 · 출력 스타일. 파일 하나만 보려면 뒤에 경로를 붙인다.

실제로 겪은 일

10월 3일, Claude가 우리 저장소의 지시 파일(CLAUDE.md, AGENTS.md, 역할별 지시 파일)을 위 /doctor 명령이 아니라 /claude-api 스킬의 프롬프트 감사로 훑었다. 보고서가 품질을 가장 크게 좌우한다고 꼽은 세 가지 중 하나가 변경 이력. AGENTS.md 앞부분 약 85줄이 릴리스 노트였고, CLAUDE.md 명령 표 설명에도 「added in v1.5」 같은 버전 표기가 섞여 있었다. 이유는 이 줄들이 작업을 시작할 때마다 다시 읽히지만 시키는 행동은 없고, 같은 내용이 결정 기록에 이미 있다는 것. 내가 이력 이동을 승인해 같은 날 이력은 결정 기록으로 원문 그대로 옮겨졌고 규칙 문장은 그대로 남았는데, 그 뒤 지시가 더 잘 지켜졌는지는 재 보지 않았다.

내 claude.md 점검표

팀과 같이 쓸 규칙은 저장소 맨 위 CLAUDE.md, 내 취향은 ~/.claude/CLAUDE.md, 나만 쓸 프로젝트 설정은 CLAUDE.local.md(.gitignore 에 추가)로 갈라 뒀나.
/context 의 Memory files 에 실려야 할 파일이 다 보이나.
파일 하나가 200줄을 넘지 않나. 시작할 때나 /status 에 길이 경고가 뜨지 않나.
문장마다 맞았는지 확인할 수 있나(「제대로 정리해」 대신 「스페이스 2칸」).
폴더 구조 · 의존성 목록처럼 코드를 보면 아는 내용이 들어 있지 않나.
코드 일부에만 필요한 규칙을 .claude/rules/ 의 paths 규칙으로 뺐나.
「언제 추가됨」 같은 변경 이력이 규칙 사이에 남아 있지 않나.
반드시 막아야 하는 동작을 CLAUDE.md 문장에만 맡기고 있지 않나.
AGENTS.md 도 쓴다면, CLAUDE.md 에서 @AGENTS.md 로 불러오고 있나.

같이 읽을 글

2편 — Claude Code 설치(클로드코드 설치)부터 첫 자동화까지: 리눅스에서 매일 도는 작업 만들기: 대화 없이 claude -p 로 불러도 실행한 폴더의 CLAUDE.md 가 따라온다. 빈 폴더에서 돌리고 설정을 걷어 내 입력 토큰을 27만에서 4천으로 줄인 측정.
7편 — Claude Code 권한 설정(permissions)과 hooks 예시: auto mode에서 계속 막힐 때 손본 settings.json 세 곳: CLAUDE.md 문장이 아니라 설정과 훅으로 거는 규칙.

다음 글은 claude.md 와 agents.md 의 차이. 한 저장소에 두 파일을 같이 둘 때 무엇을 어디에 적는지 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

유튜브 api 키 발급 · YouTube Data API 키: 코드에 넣기 전 확인할 것 세 가지(API 제한 · .env 보관 · 교체 순서)

코드짜는아빠 — Tue, 13 Oct 2026 08:56:29 +0900

유튜브 API 키 발급은 Google Cloud 콘솔에서 버튼 몇 번이면 끝난다. 코드에 넣기 전에 볼 건 세 가지. 키가 YouTube Data API v3 만 부르도록 제한했는지, 키를 코드 밖 .env 에 두고 git 에서 뺐는지, 키를 바꿀 때 새 키로 실제 호출을 확인한 뒤에 옛 키를 지우는지. 기준은 2026년 10월 13일에 읽은 Google Cloud · YouTube Data API 공식 문서다.

유튜브 API 키 발급 순서 (2026-10-13 공식 문서 기준)

YouTube Data API 시작 문서가 적는 준비는 프로젝트, API 사용 설정, 인증 정보 세 가지.

Google Cloud 콘솔에서 프로젝트를 만든다. 이미 있으면 그 프로젝트를 고른다.
사용 설정된 API 목록(Enabled APIs)에 YouTube Data API 가 있는지 본다. 없으면 API 라이브러리에서 사용 설정한다.
사용자 인증 정보 페이지에서 사용자 인증 정보 만들기 → API 키 → 이 키로 부를 API 를 고른 뒤 만들기.

버튼 이름은 Google Cloud API 키 관리 문서 한국어판 표기를 따랐다. API 키로 되는 건 공개 데이터 쪽. 시작 문서는 인증 없는 요청은 공개 데이터만 가져온다고 적고, 사용자 인증이 필요한 메서드를 쓸 거면 OAuth 2.0 인증 문서를 읽으라고 한다. 공개된 채널 · 영상 정보를 읽는 일이면 API 키로 되는 셈이다.

넣기 전에 1: API 키 제한은 쓰는 API 하나로

제한은 키를 만들 때 같이 건다. 2026년 10월 9일에 고쳐진 키 관리 문서 영문판은 콘솔에서 키를 만들려면 API 제한을 하나 이상 걸어야 한다고 적는다(한국어판은 2025년 12월 판이라 이 문장이 아직 없다). 이미 만든 키라면 키 이름 클릭 → API 제한사항 섹션의 키 제한 → 이 키로 부를 API 선택 → 저장. 유튜브 데이터만 읽을 키라면 YouTube Data API v3 하나만 고르면 된다. 같은 문서는 제한 없는 키를 두고 어디서나 쓸 수 있어 안전하지 않다고 적었다. API 키 권장 사항 문서가 드는 이유는 하나, 키가 털렸을 때 피해를 줄이는 것.

애플리케이션 제한도 따로 있다. 키 관리 문서는 운영에 쓰는 앱이라면 이것과 API 제한을 둘 다 걸라고 적는다. HTTP 리퍼러(웹사이트), IP 주소, Android 앱, iOS 앱 네 가지 중에서 키를 쓰는 곳에 맞는 걸 고르는 식. 서버나 cron 작업이 쓰는 키라면 문서상 해당 칸은 IP 주소다.

할당량도 넣기 전에 본다. 시작 문서 기준 기본 할당량은 search.list 100회, videos.insert 100회, 그 밖의 엔드포인트를 합쳐 하루 10,000 단위. 목록을 읽는 요청은 보통 1단위가 든다고 적혀 있다.

넣기 전에 2: 키는 코드 밖 `.env` 에, 저장소에서는 빼고

권장 사항 문서는 소스 코드에 박아 넣거나 저장소에 둔 키는 가로채이거나 도난당할 수 있다고 적는다. 우리는 키를 .env 한 줄에 두고, 그 파일을 .gitignore 첫 줄로 git 에서 뺐다.

# .env
YOUTUBE_DATA_API_KEY=발급받은_키

# .gitignore
.env

빠졌는지는 git 으로 확인할 수 있다.

git check-ignore -v .env

git 공식 문서 기준으로, 무시되는 파일이면 걸린 규칙과 경로가 함께 찍히고 종료 코드는 0. 하나도 무시되지 않으면 1이다.

요청에 키는 어떻게 싣나? 키를 URL 의 key= 로 붙이면 URL 스캔으로 털릴 수 있다는 게 권장 사항 문서의 설명이고, 대신 x-goog-api-key HTTP 헤더나 클라이언트 라이브러리를 쓰라고 한다.

x-goog-api-key: API_KEY

키 사용 문서는 헤더를 못 쓸 때 key 쿼리 파라미터를 써도 되지만, 그러면 키가 URL 에 들어가 같은 위험이 붙는다고 적었다.

넣기 전에 3: 키를 바꿀 땐 새 키 확인 뒤에 옛 키 삭제

키 관리 문서의 키 순환 순서.

사용자 인증 정보 페이지에서 바꿀 키 이름을 누른다.
키 순환.
새 키 이름을 넣고, 제한사항이 맞는지 확인한 뒤 만들기.
새 키 문자열을 복사해 앱이 새 키를 쓰게 바꾼다.
모든 앱을 바꾼 뒤, 새 키 세부정보 페이지의 이전 키 섹션에서 이전 키 삭제.

요점은 5번이 맨 끝이라는 것. 앱이 전부 새 키로 바뀐 걸 보고 나서야 옛 키를 지운다. 너무 일찍 지웠더라도 삭제 뒤 30일 안이면 되살릴 수 있다고 문서에 적혀 있다.

언제 바꾸나? 권장 사항 문서는 주기적으로 새 키를 만들고, 앱을 바꾸고, 옛 키를 지우라고 적는다. 우리 보안 검토가 정리한 시점은 조금 더 구체적이었다. 키가 커밋 · 로그 · 세션 기록 · 스크린샷, 또는 AI 에이전트가 붙은 브라우저 화면에 보였을 수 있을 때, 기기를 잃어버렸을 때, 그게 아니면 1년에 한 번.

실제로 겪은 일

10월 7일, 유튜브 공개 통계를 읽는 스크립트에 쓸 API 키가 새로 만들어져 .env 에 들어갔다. 같은 날 보안 검토에서 걸린 건, 그 키를 만든 클라우드 콘솔 「사용자 인증 정보」 화면을 쓰는 동안 내 Chrome 에 Playwright 확장이 붙어 있었다는 점. 키 원문이 샌 흔적은 없었지만 보수적으로 바꾸기로 했다. 새 키는 내가 콘솔에서 직접 만들었고, .env 를 새 키로 바꾼 뒤 그 키로 부른 호출이 HTTP 200 으로 돌아오는 걸 보고 나서 옛 키를 지웠다. 확장이 붙은 브라우저에서는 클라우드 콘솔과 키 화면을 열지 않고, 키 만들기 · 제한 · 삭제는 사람 손으로 한다는 규칙이 이 일 뒤에 생긴 거다.

내 API 키 설정 점검표

키를 쓰는 API 하나(유튜브라면 YouTube Data API v3)로 제한했나. API 제한사항 → 키 제한.
애플리케이션 제한(HTTP 리퍼러 · IP 주소 · Android 앱 · iOS 앱) 중 내 환경에 맞는 게 있는지 봤나.
키가 코드와 저장소에 없고 .env 에 있나. git check-ignore -v .env 가 규칙을 찍어 주나.
요청에 키를 URL key= 대신 x-goog-api-key 헤더로 싣나.
기본 할당량(search.list 하루 100회, 그 밖의 엔드포인트 합쳐 하루 10,000 단위)을 내 호출량과 맞춰 봤나.
키를 만들거나 키 값을 화면에 띄우는 동안, AI 에이전트의 브라우저 도구가 그 브라우저에 붙어 있지 않나.
키를 바꿀 때 새 키로 실제 호출이 성공한 걸 보고 나서 옛 키를 지우나.
바꾼 기록에는 날짜와 이유만 남기고, 키 값은 앞뒤 몇 자리도 적지 않는다.

같이 읽을 글

10편 — 클로드 코드 보안 설정 · AI 에이전트 보안: 비밀번호 칸 앞에서 멈춘 작업과 그 뒤의 규칙 세 곳: 에이전트가 붙은 브라우저에서 열지 않는 화면(클라우드 콘솔 · 결제 · 계정 설정)을 정한 규칙과, 비밀번호 창 앞에서 멈춘 작업.

다음 글은 claude.md 파일 위치와 작성법. 어디에 두면 Claude Code가 읽는지부터 적는다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

코덱스 사용량 확인 · codex cli 사용량: /status 와 사용량 대시보드로 5시간 · 주간 한도 보는 법

코드짜는아빠 — Tue, 13 Oct 2026 08:25:58 +0900

코덱스(Codex CLI) 사용량 확인은 세션 안에서 /status 한 줄. 남은 한도가 거기 나온다. 계정 전체 사용량과 초기화 시각은 ChatGPT의 Codex 사용량 대시보드에서 본다. 한도는 5시간 창과 주간 창, 두 칸(Plus 기준, 문서상 Pro 는 지금 5시간 한도 없음). 둘은 따로 차기 때문에 둘 다 봐야 한다. 기준은 2026년 10월 13일에 조회한 OpenAI 공식 문서.

Codex CLI 안에서 남은 한도 보기: `/status` (2026-10-13 공식 문서 기준)

OpenAI의 Codex 가격 · 한도 문서에는 이렇게 적혀 있다.

If you want to see your remaining limits during an active Codex CLI session, you can use /status.

Codex CLI 대화 창에 그대로 입력하면 끝.

/status

CLI 명령 문서는 /status 를 「세션 설정과 토큰 사용량 표시」로 설명하고, 지금 쓰는 모델 · 승인 정책 · 쓰기 가능한 경로 · 남은 컨텍스트가 함께 나온다고 적는다. 여기서 「남은 컨텍스트」는 지금 대화에 더 담을 수 있는 양이라, 요금제 한도와는 다른 숫자인 셈이다.

`/usage` 로 토큰 사용 기록 보기 · 초기화권 쓰기

/usage 는 같은 CLI 명령 문서에 「계정 토큰 사용량을 보거나 사용량 한도 초기화를 쓰는」 명령으로 나온다. 그냥 /usage 를 치면 메뉴가 뜨고, 토큰 사용 기록을 볼지 쓸 수 있는 초기화를 쓸지 고르는 식. 기록을 바로 열려면 기간을 붙인다.

/usage daily
/usage weekly
/usage cumulative

세션에 Codex 서비스 계정 인증이 없으면 로그인이 필요하다는 안내가 대신 뜬다. 문서 설명대로라면 /usage 는 쓴 양의 기록, 남은 한도는 /status 와 대시보드.

계정 전체 사용량과 초기화 시각: Codex 사용량 대시보드

주소는 chatgpt.com/codex/settings/usage. 공식 문서는 현재 한도와 초기화 시각을 사용량 대시보드에서 확인하라고 적는다. 로컬 메시지와 클라우드 대화는 요금제 사용량을 같이 쓰고, 주간 한도가 더 붙을 수 있다는 줄도 같은 페이지에 있다. Plus 요금제라면 같은 페이지 표에서 5시간당 메시지 수 추정치도 볼 수 있고.

한도에 닿으면? Plus · Pro 사용자는 크레딧을 추가로 사서 계속 쓸 수 있다고 문서에 적혀 있다. 크레딧이 없으면 대시보드의 초기화 시각까지 기다리거나, /usage 메뉴에서 쓸 수 있는 초기화가 있는지 보는 길이 남는다.

한도 메시지가 떴을 때: 5시간 창인지 주간 창인지부터

우리 기록에 남은 한도 문구.

You've hit your usage limit … try again at Oct 18th, 2026 12:57 PM

볼 곳은 끝의 시각. 5시간 창은 이름 그대로 5시간 단위로 돌아서, 다시 시도할 시각이 며칠 뒤라면 주간 창이 찬 거다. 이때는 5시간 창이 풀리기를 기다려도 소용없다.

실제로 겪은 일

10월 12일 밤, Claude가 Codex에 넘긴 작업 두 건이 위 문구와 종료 코드 1로 끝났다. 모델(-m)을 바꿔 다시 넘겨도 같은 계정이라 같은 오류였다. 다음 날 내가 Claude에게 초기화권 확인을 부탁했고, 읽어 온 값은 Plus 요금제, 5시간 창(300분) 0%, 주간 창(10080분) 100%에 초기화 10월 18일 12:57, 유료 크레딧 0. 대신 「Full reset (Weekly + 5 hr)」 초기화권이 3장 있었고, 만료일이 10월 23일, 10월 30일처럼 장마다 따로 붙어 있었다. 내가 앱에서 1장을 쓰자 다시 읽은 주간 창이 0%로 돌아왔다(5시간 창도 0%).

위 값은 어디서 읽었나: app-server(실험 기능, 권하지 않음)

위 상자의 값은 앞의 세 경로가 아니라, codex app-server 에 한도 조회 요청(account/rateLimits/read)을 보내 읽은 것이다. 이 요청은 2026년 10월 13일에 본 공식 app-server 문서에도 「ChatGPT 사용량 한도 읽기」로 나와 있고, 응답에 쓸 수 있는 초기화 수도 들어 있다. 문서는 app-server 명령을 실험 기능이고 운영 작업에는 지원하지 않는다고 적는다. 언제든 바뀔 수 있으니 권하지는 않는 길. 출력에는 계정 이메일 · ID 같은 정보도 같이 나온다. 쓸 수 있는 초기화가 있는지는 공식 /usage 메뉴에서 보면 된다. 세션 기록 파일(~/.codex/sessions/)에서 한도 스냅샷과 초기화 시각을 꺼내는 방법은 3편에 따로 적었다.

내 Codex 사용량을 확인할 때 볼 것

Codex CLI 세션 안에서 /status — 남은 한도.
계정 전체 사용량과 초기화 시각은 Codex 사용량 대시보드(chatgpt.com/codex/settings/usage).
한도 문구가 뜨면 「try again at」 시각부터. 며칠 뒤라면 5시간 창이 아니라 주간 창이다.
모델만 바꿔서는 안 풀렸다. 우리 경우엔 같은 계정이라 같은 오류.
크레딧이 0이라면: 초기화 시각까지 기다리기, 크레딧 사기(Plus · Pro), /usage 메뉴에서 쓸 수 있는 초기화 확인. 우리 계정의 초기화권은 장마다 만료일이 따로였다.
스크립트로 Codex를 부른다면 종료 코드만 보지 말고 출력의 한도 문구도 본다. 우리 기록에서 한도로 끝난 codex exec 는 9월 23일엔 종료 코드 0, 10월 12일엔 1이었다.

같이 읽을 글

3편 — Claude 요금제 비교(Pro·Max 5x·20x 차이)와 사용량 한도: 세션 기록 파일에서 Codex 한도 스냅샷과 초기화 시각(resets_at)을 꺼내는 명령, 한도 때문에 작업이 멈춘 날들의 표.
4편 — Codex CLI 사용법(코덱스 CLI): codex exec 를 백그라운드로 돌릴 때 걸리는 함정 3가지: Codex를 스크립트로 돌린다면, 종료 코드를 codex 바로 뒤에서 받는 이유와 입력을 기다리며 멈춘 호출.

다음 글은 API 키를 넣기 전에 확인할 것. 10월 7일, 키 하나를 새로 발급해 바꿔 끼우고 옛 키를 지운 기록에서 시작한다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.

코드나라

클로드 코드 에이전트 만들기(claude code custom agents): 같은 지시를 되풀이할 때 만들고 호출 기록이 0이어도 바로 지우지 않는다

1. 만들 이유: 같은 일을 같은 지시로 되풀이할 때 (2026-10-21 공식 문서 기준)

2. description: 이 에이전트 하나만 골라내게 쓴다

3. 남는 에이전트의 비용: 안 불러도 description 은 컨텍스트를 차지한다

4. 둘 곳: 모든 프로젝트에서 쓸 것만 ~/.claude/agents/ 에

5. 도구: tools 에 필요한 것만 적는다

6. 지우기 전에: 호출 기록을 세되 0을 「앞으로도 안 씀」으로 읽지 않는다

만들기 전 점검표: 클로드 코드 에이전트 만들기

같이 읽을 글

클로드 코드 서브에이전트 사용법(claude code subagents): .claude/agents/ 에 파일 하나로 만들고 검토는 쓴 쪽과 다른 서브에이전트에 맡긴다

서브에이전트는 자기 컨텍스트에서 일하고 요약만 돌려준다 (2026-10-21 공식 문서 기준)

1단계: 서브에이전트 만들기 — Claude에게 부탁하거나 파일을 직접 쓴다

2단계: 파일 위치 — 팀과 나눌 건 .claude/agents/, 나만 쓸 건 ~/.claude/agents/

3단계: frontmatter — 필수는 name · description 둘

4단계: 부르기 — description 으로 알아서 · 이름이나 @ 로 직접

5단계: 도구 제한 — tools 는 허용 목록, Bash 는 따로 거른다

검토는 왜 남이 해야 하나: 쓴 대화를 못 보는 쪽이 읽게 한다

내 설정 점검표: 클로드 코드 서브에이전트 사용법

같이 읽을 글

코드나라 구글 도구 개인정보처리방침

1. 구글에 요청하는 권한과 다루는 정보

2. 사용 목적

3. 저장하는 곳과 기간

4. 다른 곳에 주는 정보

5. Limited Use 준수

6. 권한 철회와 삭제

7. 문의

8. 바뀌면

클로드 코드 MCP 연결 · 설정(claude code mcp setup): claude mcp add 한 줄로 붙이고, 읽기 도구만 승인 없이 열어 둔다

MCP 서버를 붙이면 Claude Code 안에 도구가 생긴다

1단계: claude mcp add 로 붙인다 (2026-10-20 공식 문서 기준)

2단계: --scope 로 저장 범위를 고른다

키가 필요한 서버: 명령줄과 공유 파일에 키를 적지 않는다

3단계: claude mcp list 와 /mcp 로 연결을 확인한다

4단계: 도구 권한을 정한다 — 읽기 도구만 허용 규칙에

붙이고 나서 먼저 막은 것: 버전 · 실행 방식 · 사용 통계 · 쓰기 도구

내 설정 점검표: 클로드 코드 MCP 설정

같이 읽을 글

클로드 코드 텔레그램 연동 · claude code telegram notification: Notification 훅에 sendMessage 한 번, 부르는 건 승인이 필요할 때만

1단계: BotFather 에서 봇을 만들고 토큰을 받는다

2단계: 봇에게 한 번 말을 걸고 getUpdates 로 chat_id 를 찾는다

3단계: 훅이 부를 스크립트 — sendMessage 한 번

4단계: settings.json 의 Notification 훅에 건다 (2026-10-20 공식 문서 기준)

5단계: /hooks 로 확인하고 시험 메시지를 보낸다

언제 부르게 했나: 승인이 필요한 순간에만, 답은 채팅으로

내 설정 점검표: 클로드 코드 텔레그램 알림

같이 읽을 글

claude code skills vs agents · 클로드 코드 스킬 vs 서브에이전트: 지금 대화에서 다시 쓸 절차는 스킬, 결과만 받을 일은 서브에이전트

claude code skills vs agents 한눈에 (2026-10-19 공식 문서 기준)

언제 무엇을 쓰나: 대화가 필요하면 스킬, 결과만 필요하면 서브에이전트

섞어 쓰는 두 방법: 스킬을 서브에이전트로 돌리거나, 서브에이전트에 스킬을 싣거나

우리 기준: 규칙은 역할 파일 하나에, 스킬과 서브에이전트는 그 파일을 부르는 입구로

내 저장소 점검표: 스킬 · 서브에이전트 나눠 쓸 때

같이 읽을 글

claude.md agents.md 차이 · claude code agents.md: 공통 규칙은 AGENTS.md 에 두고 CLAUDE.md 는 불러오기 한 줄과 Claude 전용만

claude.md 와 agents.md 차이 한눈에 (2026-10-16 공식 문서 기준)

Claude Code가 AGENTS.md 를 읽는 경우, 안 읽는 경우 (v2.1.277 이상)

Codex는 AGENTS.md 를 이렇게 읽는다

둘 다 쓸 때 나누는 법: 공통은 AGENTS.md, Claude 전용은 CLAUDE.md

내 저장소 점검표: claude.md · agents.md 같이 쓸 때

같이 읽을 글

claude.md 파일 위치 · 클로드 코드 claude.md 작성법: 저장소 맨 위 CLAUDE.md 에, 200줄 안쪽으로 매번 필요한 것만

claude.md 파일 위치 네 곳과 읽히는 순서 (2026-10-14 공식 문서 기준)

처음 만들 때: /init 으로 뼈대를 받고 손으로 채운다

claude.md 작성법: 매 세션 필요한 사실만, 확인할 수 있게

쓰지 말 것: 코드에 있는 것, 일부에만 필요한 것, 서로 부딪치는 것

크기: 파일당 200줄 아래, 줄이는 길은 둘

AGENTS.md 를 같이 쓴다면: @AGENTS.md 로 불러온다

점검: /doctor prompt-audit (2026-10-14 기준 v2.1.283 이상)

내 claude.md 점검표

같이 읽을 글

유튜브 api 키 발급 · YouTube Data API 키: 코드에 넣기 전 확인할 것 세 가지(API 제한 · .env 보관 · 교체 순서)

유튜브 API 키 발급 순서 (2026-10-13 공식 문서 기준)

넣기 전에 1: API 키 제한은 쓰는 API 하나로

넣기 전에 2: 키는 코드 밖 .env 에, 저장소에서는 빼고

넣기 전에 3: 키를 바꿀 땐 새 키 확인 뒤에 옛 키 삭제

내 API 키 설정 점검표

같이 읽을 글

코덱스 사용량 확인 · codex cli 사용량: /status 와 사용량 대시보드로 5시간 · 주간 한도 보는 법

처음 만들 때: `/init` 으로 뼈대를 받고 손으로 채운다

AGENTS.md 를 같이 쓴다면: `@AGENTS.md` 로 불러온다

점검: `/doctor prompt-audit` (2026-10-14 기준 v2.1.283 이상)

넣기 전에 2: 키는 코드 밖 `.env` 에, 저장소에서는 빼고

Codex CLI 안에서 남은 한도 보기: `/status` (2026-10-13 공식 문서 기준)

`/usage` 로 토큰 사용 기록 보기 · 초기화권 쓰기