Claude Code에 커스텀 에이전트를 만들었더니, '매번 같은 확인'이 사라진 이야기

코딩하기 귀찮아하는 SE(시스템 엔지니어)가 Claude Code의 커스텀 에이전트(Custom Agent)를 사용하기 시작한 이야기입니다. "매번 똑같은 말을 다시 전달하고 있다"라는 사소한 스트레스를 해소했습니다.

서론: 매번 똑같은 설명을 하고 계시지 않나요

コピペ de UI (복사 붙여넣기로 UI) 라는 사이트를 운영하고 있습니다. 업무용 Web 앱에서 자주 사용하는 UI 컴포넌트를 동작하는 데모·샘플 소스·AI 프롬프트 3종 세트로 제공하는 서비스입니다.

사이트 운영을 위해 Claude에게 요청하는 작업이 몇 종류 있는데, 그때마다 "이 프로젝트는 ○○라는 규칙으로~", "참조할 파일은~", "출력 형식은~"이라는 설명을 해야 합니다. 매번 말이죠.

"지난 채팅에서도 똑같은 말을 했었는데"라고 생각하게 되는 상황입니다. Claude는 세션(Session)을 넘나들며 기억을 유지하지 않기 때문에, 매번 처음부터 다시 설명해야 합니다.

솔직히 "원래 그런 거겠지"라고 생각했습니다. 이것이 문제였는데, 문제라는 사실조차 깨닫지 못하고 있었던 것입니다.

해결책: 커스텀 에이전트라는 것이 있었다

Claude Code에는 커스텀 에이전트(Custom Agent)라는 메커니즘이 있습니다.

.claude/agents/

라는 폴더에 Markdown 파일을 두기만 하면 됩니다. "이 에이전트는 무엇을 하는가", "무엇을 참조하는가", "무엇을 써도 되고 무엇을 쓰면 안 되는가"를 일반적인 일본어로 작성합니다. 그뿐입니다. 코드는 한 줄도 쓰지 않습니다.

제가 만든 것은 두 종류입니다.

• ops-knowhow-keeper — 운영 노하우를 기록하는 담당. "오늘의 배움을 기록해줘"라고 하면 실행됩니다. 쓰기 대상은 doc/knowhow/ 뿐입니다.
• zenn-writer — Zenn 기사 소재 발굴 및 집필 담당. "소재를 뽑아줘"라고 하면 실행됩니다. 쓰기 대상은 doc/zenn-article/ 뿐입니다.

매번 "이 프로젝트는 이런 규칙으로"라는 설명이 필요 없게 되었습니다. 에이전트 정의 파일 안에 전부 적어두었기 때문입니다.

무엇이 바뀌었나

"매번 설명하기"가 없어졌다

이전에는 "노하우를 기록해줘"라고 의뢰할 때마다, 무엇을 어디에 쓸지, 인덱스(Index) 파일은 어디인지, 형식은 무엇인지를 매번 전달해야 했습니다. 지금은 "오늘의 배움을 기록해줘"라는 한마디로 작동합니다.

"매번 똑같은 설명을 하고 있구나"라고 깨달았을 때, 그것이 바로 에이전트화(Agentization)의 신호라고 생각합니다.

쓰기 대상을 제한할 수 있다

이 점이 은근히 컸습니다. 에이전트에게 "doc/knowhow/ 이외의 파일은 절대 변경하지 마"라고 적어두면, 다른 파일을 실수로 덮어쓸 리스크가 사라집니다.

수작업으로 "어라, 왠지 상관없는 파일까지 바뀌어 있네"라는 경험을 몇 번 했었기 때문입니다.

참조 대상을 고정할 수 있다

노하우 기록 에이전트라면 "먼저 doc/knowhow/INDEX.md를 읽고 기존 기록을 확인한 뒤에 작성할 것". 기사 집필 에이전트라면 "먼저 zenn-strategy.md에서 페르소나(Persona)를 확인한 뒤에 작성할 것".

매번 "이 파일을 보고 시작해줘"라고 말할 필요가 없습니다.

만드는 방법, 너무 단순해서 깜짝 놀랐다

.claude/agents/ 폴더에 MD 파일을 만들기만 하면 됩니다. 내용 구성은 다음과 같습니다:

---
name: ops-knowhow-keeper
description: ~한 전문 에이전트. "○○해줘"라고 말하면 이 에이전트가 담당함
...

프론트매터(Frontmatter)를 통해 사용할 수 있는 도구와 모델을 지정할 수 있습니다. 기록·정리 계열은 Haiku(빠르고 저렴), 소재 발굴·집필 계열은 Sonnet(깊게 생각해주길 바람)으로 구분하여 사용하고 있습니다.

파일 내용은 일반적인 일본어로 작성하면 됩니다. "쓰기 대상은 여기뿐", "처음에 이 파일을 읽을 것", "출력은 이 형식으로"라고 적으면 그대로 작동합니다.

"자신의 작업을 관찰하는 것"이 핵심이었다

커스텀 에이전트를 만들게 된 계기는 "매번 똑같은 일을 반복하고 있네"라는 관찰이었습니다.

반복하고 있는 작업이 있다 → 그것은 패턴화할 수 있다 → 패턴을 에이전트에 적는다 → 이후에는 호출하기만 하면 된다.

"매번 무엇을 설명하고 있는가"를 메모해 두면 에이전트화할 소재를 찾기 쉽습니다.

AI와의 작업에서 "매번 이걸 말하고 있네"라는 순간이 온다면, 그때가 바로 에이전트를 만들 타이밍이라고 생각합니다.

이 메커니즘 전체(CLAUDE.md · 규칙 MD · 커스텀 에이전트 구성)를 사용하여 혼자서 사이트를 계속 만들어 나가고 있습니다. 괜찮으시다면 구경해 보세요.

Discussion