카테고리 없음

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

코드짜는아빠 2026. 10. 23. 18:00

에이전트 파일을 쓰기 전에 같은 지시로 같은 일을 몇 번이나 맡겼는지부터 세어 보자. 클로드 코드 에이전트(공식 문서 이름은 클로드 코드 서브에이전트)는 마크다운 파일 하나로 만들어진다. 따질 건 그 전에 넷. 같은 일을 같은 지시로 되풀이하고 있나, 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은 「앞으로도 안 씀」이 아니었다.

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

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

같이 읽을 글

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

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

'카테고리 없음'의 다른글

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

티스토리툴바