backtodev_
ClaudeCodeAgent자동화

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

2026년 4월 22일3 분 읽기

"매번 같은 작업을 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, 다시 개발자로 돌아갑니다. 실패하고 배우며 성장하는 기록.