backtodev_
← cd ..
ClaudeCodeAgent자동화

Claude Code 커스텀 에이전트 만들기 — blog-auto-draft로 배우는 실전 세팅

April 22, 20261 min read

"매번 같은 작업을 Claude에게 설명하기 지치셨나요?"

개발을 하다 보면 Claude Code에게 반복적으로 시키는 일이 생긴다. 나는 작업이 끝날 때마다 "오늘 커밋 분석해서 블로그 초안 써줘"를 입력했다. 처음엔 괜찮았는데, 매번 컨텍스트를 설명하는 게 슬슬 귀찮아졌다.

그래서 커스텀 에이전트를 만들었다. 한 번 세팅해두면 /blog-auto-draft 한 줄로 동일한 작업을 반복할 수 있다. 이 글은 그 과정을 blog-auto-draft 예시로 설명한다.

에이전트가 뭔데?

Claude Code에서 에이전트(Agent) 는 특정 역할과 행동 지침을 미리 정의한 서브 AI다. 일반 대화와 다른 점은 세 가지다.

구분일반 대화커스텀 에이전트
컨텍스트매번 직접 설명파일에 저장해서 재사용
권한전체 도구필요한 도구만 지정 가능
호출 방법자유 텍스트이름으로 호출

쉽게 말해 반복 작업을 위한 전용 도우미를 만드는 것이다.

사전 준비

  • Claude Code CLI 설치 (claude 명령어 사용 가능한 상태)
  • ~/.claude/agents/ 디렉토리 (없으면 생성)
mkdir -p ~/.claude/agents

Step 1 — 에이전트 파일 만들기

에이전트는 마크다운 파일 하나로 정의된다. 위치는 두 곳 중 하나:

~/.claude/agents/에이전트명.md      # 글로벌 (모든 프로젝트에서 사용)
.claude/agents/에이전트명.md        # 로컬 (현재 프로젝트 전용)

파일 구조는 간단하다:

---
name: 에이전트-이름
description: "이 에이전트가 뭘 하는지 한 줄 설명"
color: purple
---
에이전트에게 줄 시스템 프롬프트 (역할, 행동 지침)

--- 사이의 frontmatter가 메타데이터, 그 아래가 에이전트의 역할 지침이다.

Step 2 — blog-auto-draft 파일 뜯어보기

실제로 내가 쓰는 에이전트를 보자. ~/.claude/agents/blog-auto-draft.md:

---
name: blog-auto-draft
description: "오늘 작업한 git 커밋과 변경 파일을 분석해서 블로그 초안을 자동 생성한다.
             호출 시 git log와 diff를 읽고, blog-write 스타일로 마크다운 초안을 작성해 저장한다."
color: purple
---
오늘 작업한 내용을 분석해서 블로그 초안을 작성해줘.

## Step 1: 오늘 작업 내용 파악

다음 명령어로 최근 작업을 확인해:

```bash
git log --oneline -10

오늘 날짜와 커밋 메시지를 대조해서 오늘 커밋만 추려낸다. 커밋이 없으면 가장 최근 커밋 1~3개를 대상으로 삼는다.

Step 2: 변경 파일 목록 확인

...


핵심 포인트 세 가지:

**1. description은 AI가 읽는다**
description은 단순 메모가 아니다. Claude가 이 에이전트를 언제 호출할지 판단하는 기준이 된다. 구체적으로 쓸수록 자동 트리거가 정확해진다.

**2. 프롬프트는 단계별로 나누기**
에이전트 본문은 그냥 자유 텍스트가 아니라 명확한 지침서처럼 쓰는 게 좋다. `Step 1`, `Step 2`처럼 순서를 주면 에이전트가 단계를 건너뛰지 않는다.

**3. 출력 경로를 명시하기**
파일을 저장하는 에이전트라면 저장 경로와 파일명 형식을 프롬프트에 고정해두는 게 좋다. 매번 물어보지 않게 된다.

---

## Step 3 — 실제 호출하기

에이전트를 만들면 두 가지 방법으로 호출할 수 있다.

### 방법 1: 명시적으로 이름 부르기

blog-auto-draft 실행해줘


Claude가 description을 보고 해당 에이전트를 찾아서 실행한다.

### 방법 2: Agent 도구로 직접 호출 (코드에서)

```python
Agent(
  subagent_type="blog-auto-draft",
  prompt="오늘 작업한 내용 분석해서 초안 써줘"
)

Claude Code가 내부적으로 서브 에이전트를 생성할 때 쓰는 방식이다.

Step 4 — 나만의 에이전트 만들어보기

blog-auto-draft를 참고해서 자기 용도에 맞는 에이전트를 만들어보자. 예시:

PR 리뷰 요약 에이전트

---
name: pr-summary
description: "GitHub PR의 변경사항을 분석해서 팀원에게 공유할 요약을 작성한다"
color: blue
---
현재 브랜치의 PR 변경사항을 분석해서 요약해줘.

## Step 1: 변경사항 파악
git diff main...HEAD 로 전체 변경 내용 확인

## Step 2: 요약 작성
- 변경된 기능 목록 (불릿 포인트)
- 주요 의사결정 사항
- 테스트 필요 항목

## Step 3: 출력
콘솔에 마크다운 형식으로 출력

일일 커밋 정리 에이전트

---
name: daily-standup
description: "오늘 git 커밋 내역을 분석해서 스탠드업 미팅용 요약을 만든다"
color: green
---
오늘 작업 내역을 스탠드업 형식으로 정리해줘.

형식:
- 어제 한 일: (커밋 기반)
- 오늘 할 일: (TODO.md 기반)
- 블로커: (없으면 "없음")

자주 쓰는 패턴 요약

패턴설명
color 지정purple, blue, green, red 등 — 에이전트 목록에서 구분용
Step 구조단계별로 나누면 에이전트가 순서 지킴
경로 고정파일 저장 에이전트는 경로를 프롬프트에 명시
description 구체화AI 자동 트리거 정확도에 직결됨

트러블슈팅

에이전트를 불러도 반응이 없다 → ~/.claude/agents/ 경로가 맞는지 확인. 파일명이 .md로 끝나야 한다.

항상 컨텍스트를 새로 설명해야 한다 → 에이전트 프롬프트 본문에 배경 정보를 직접 넣어야 한다. 에이전트는 대화 히스토리를 기억하지 않는다.

원하는 형식으로 저장이 안 된다 → 저장 경로와 파일명 형식을 프롬프트 마지막에 명확히 명시하면 해결된다.

정리

1. ~/.claude/agents/ 에 .md 파일 생성
2. frontmatter에 name, description 작성
3. 본문에 단계별 지침 작성
4. 이름 불러서 호출

한 번 만들어두면 반복 작업이 명령어 하나로 줄어든다. 나는 작업 마무리할 때마다 blog-auto-draft 실행해줘 한 줄로 블로그 초안이 나오게 됐다. 처음 세팅에 10분 투자하면 이후엔 계속 써먹을 수 있다.

다음 글에서는 에이전트에 MCP 도구를 연결하는 방법을 다룰 예정이다.

PM

backtodev

40대 PM, 다시 개발자로 돌아갑니다. 실패하고 배우며 성장하는 기록.

Claude Code 커스텀 에이전트 만들기 — blog-auto-draft로 배우는 실전 세팅 | backtodev