서브에이전트에게 원고 찾기 맡기기 | AI 교육 · 클로드 15회 · Use a Claude Code Subagent to Search Your Old Sermon Manuscripts
Create a read-only Claude Code subagent that searches your sermon archive by topic or Bible passage and returns only a summary table.
오늘 배울 것: 서브에이전트를 하나 만들어 원고 찾기 같은 곁가지 일을 맡기고, 결과 요약만 돌려받는다.
왜 필요한가
이번 주일 설교 본문이 정해졌다. 지난 3년 치 원고 폴더에서 같은 주제를 다룬 원고를 찾고 싶다. Claude에게 시키면 파일을 수십 개 열어 보며 찾는다. 그 과정이 모두 지금 대화에 쌓이면 대화가 금세 길어지고, 정작 하려던 개요 작업이 흐려진다.
서브에이전트는 이런 일을 맡는 도우미다. 자기만의 대화 창에서 따로 일하고, 끝나면 요약만 돌려준다. 공식 문서도 "다시 볼 일 없는 검색 결과나 파일 내용이 대화를 뒤덮을 때" 쓰라고 권한다. 서브에이전트가 쓰는 양도 내 사용량 한도에 함께 잡힌다는 점은 알아 두자.
Claude Code에는 이미 기본 서브에이전트가 들어 있다. 읽기만 하며 파일을 찾는 Explore가 대표적이고, Claude가 필요할 때 알아서 쓴다. 오늘은 내 일에 맞는 것을 하나 만든다.
따라 하기
- 원고 폴더(연습이라면
claude-연습)에서claude를 켠다. - 서브에이전트를 만들어 달라고 한다.
~/.claude/agents/에 sermon-finder라는 개인용 서브에이전트를 만들어 줘. 설교 원고 폴더에서 주제나 성경 본문으로 원고를 찾아 파일 이름과 핵심 한 줄을 표로 돌려준다. 파일은 읽기만 하고 고치지 않는다.
허락 창이 뜨면 Yes를 고른다.
- 만들어진
~/.claude/agents/sermon-finder.md를 열어 본다. 위쪽---사이가 이런 모양이면 된다.
--- name: sermon-finder description: 설교 원고 폴더에서 주제나 본문으로 원고를 찾아 표로 정리한다. tools: Read, Grep, Glob ---
tools에 읽기 도구만 있는지 본다. 그래야 원고를 고치지 않는다.
- 말로 부른다. 이름을 넣으면 Claude가 대개 그 서브에이전트에게 맡긴다.
sermon-finder 서브에이전트로 '용서'를 다룬 원고를 찾아 줘
- 꼭 그 서브에이전트가 일하게 하려면
@를 치고 목록에서 고른다.
@"sermon-finder (agent)" 시편 23편을 다룬 원고를 찾아 줘
대화창에 sermon-finder(...) 같은 줄이 생기고, 일이 끝나면 표만 돌아온다.
스킬과 무엇이 다른가
8회의 스킬은 지금 대화 안에서 따르는 순서표다. 서브에이전트는 따로 떨어진 대화에서 일하고 결과만 넘긴다. 찾고 모으는 일은 서브에이전트에게, 내가 지켜보며 다듬는 일은 스킬로 하면 편하다.
자주 막히는 곳
- Claude가 서브에이전트를 못 찾는다.
~/.claude/agents/폴더가 Claude Code를 켜기 전에 없었다면, 한 번 나왔다가 다시 켠다. - 이름을 말했는데 직접 찾아 버린다. 5단계처럼
@로 골라 부른다. description을 더 구체적으로 고쳐도 좋다. /agents를 쳤더니 안내 문구만 나온다. 지금 버전에서는 정상이다. Claude에게 부탁하거나~/.claude/agents/의 파일을 직접 고친다.
상담 기록이 든 폴더에서는 서브에이전트에게도 맡기지 않는다. 서브에이전트도 그 폴더의 파일을 읽는다.
오늘의 과제
sermon-finder를 만들고, 주제 하나와 성경 본문 하나로 각각 불러 본다. 돌아온 표의 파일이 실제로 그 내용을 다루는지 두 개만 열어 확인한다.
다음 회 예고
16회에서는 플러그인을 설치한다. 남이 잘 만들어 둔 스킬 꾸러미를 받아, 워드와 PDF 파일을 다루는 법을 익힌다.
ENGLISH VERSION
Use a Claude Code Subagent to Search Your Old Sermon Manuscripts
What you'll learn today: How to create a subagent, hand it a side task like finding old manuscripts, and get back only a summary of the results.
Why you need it
This Sunday's sermon text has been chosen. I want to find manuscripts on the same theme in my folder of the past three years' sermons. If I ask Claude, it will open dozens of files while it searches. If all of that piles up in the current conversation, the conversation quickly grows long, and the outline work I actually wanted to do gets lost in the clutter.
A subagent is a helper for this kind of job. It works on its own in a separate conversation window, and when it's done it hands back only a summary. The official documentation also recommends using one "when search results or file contents you won't need again would flood the conversation." Keep in mind that whatever a subagent uses also counts toward your usage limit.
Claude Code already comes with built-in subagents. The best-known one is Explore, which only reads files to find things, and Claude uses it on its own when needed. Today we'll make one that fits our own work.
Follow along
- Start
claudein your manuscript folder (orclaude-practiceif you're just practicing). - Ask it to create a subagent.
Create a personal subagent called sermon-finder in ~/.claude/agents/. It searches my sermon manuscript folder by topic or Bible passage and returns a table with each file name and a one-line summary of its main point. It only reads files and never changes them.
When the permission prompt appears, choose Yes.
- Open the new
~/.claude/agents/sermon-finder.mdfile. The part at the top between the---lines should look something like this.
--- name: sermon-finder description: Searches the sermon manuscript folder by topic or passage and organizes the results in a table. tools: Read, Grep, Glob ---
Check that tools lists only read tools. That way it won't change your manuscripts.
- Call it by name in plain words. If you mention its name, Claude usually hands the job to that subagent.
Use the sermon-finder subagent to find manuscripts about 'forgiveness'
- If you want to be sure that subagent does the work, type
@and pick it from the list.
@"sermon-finder (agent)" Find manuscripts that deal with Psalm 23
A line like sermon-finder(...) appears in the conversation, and when the work is finished, only the table comes back.
How is this different from a skill?
The skill from Lesson 8 is a step-by-step checklist followed inside your current conversation. A subagent works in a separate conversation and passes back only the results. A handy rule: give searching and gathering to a subagent, and use a skill for work you want to watch and polish yourself.
Where people often get stuck
- Claude can't find the subagent. If the
~/.claude/agents/folder didn't exist before you started Claude Code, exit once and start it again. - You named it, but Claude does the search itself. Pick it with
@as in step 5. Making the description more specific also helps. - Typing
/agentsshows only a guidance message. That's normal in the current version. Ask Claude to do it, or edit the file in~/.claude/agents/directly.
Don't hand folders containing counseling records to a subagent either. A subagent reads the files in that folder too.
Today's assignment
Create sermon-finder and call it twice: once with a topic and once with a Bible passage. Open just two of the files in the table it returns and confirm they actually cover that content.
Coming up next
In Lesson 16 we'll install a plugin. You'll take a bundle of skills someone else has already built well and learn how to work with Word and PDF files.
Translated from the Korean original by the author's team with AI assistance. Scripture quotations are from the World English Bible (public domain).
댓글