내 전문가 만들기

새 알바생이 왔다고 해볼게요.

무슨 일을 하는 사람인지 적어줘야 해요. 그리고 하나 더 있어요. 어느 방까지 들어갈 수 있는지 정해줘야 하죠. 창고 열쇠는 주고, 금고 열쇠는 안 주고요.

이건 그 사람을 못 믿어서가 아니에요. 실수가 사고로 번지는 걸 막는 거예요.

오늘 만드는 게 정확히 그거예요.

오늘 만들 것

내 사이트를 검수하는 전문가 하나. 문제를 찾아주지만, 고치지는 못해요. 읽기 권한만 줬으니까요.

그리고 그 안전장치가 진짜로 작동하는 걸 눈으로 확인하는 경험.

준비물

• 시즌 3의 2강을 마친 상태 (세 장짜리 my-page, 위임을 한 번 해봤어요)
• 35분

따라 하기

1. 전문가는 파일 하나예요

지난 강의에서는 이름 없는 조사원에게 맡겼어요. 매번 무슨 일을 하는지 설명해야 했죠.

이름을 붙이고 지시서를 써주면, 다음부터는 설명이 필요 없어요. 그걸 서브에이전트라고 부르고, 파일 하나로 만들어요.

.claude/agents/reviewer.md

스킬은 폴더였는데 이건 파일이에요. 헷갈리기 쉬우니 한 번 더요. 스킬은 폴더, 에이전트는 파일.

2. 만들어 달라고 시키기

직접 타이핑하지 마세요. 늘 하던 대로 시키면 돼요.

.claude/agents/reviewer.md 파일을 만들어 줘.

프런트매터는 이렇게:

---
name: reviewer
description: 내 웹페이지를 점검할 때 사용. 링크, 모바일 화면, 페이지 간
  일관성을 확인하고 문제를 보고한다. 고치지는 않는다.
tools: Read, Grep, Glob
---

그 아래 본문에는 이 검수자가 어떤 사람인지 적어 줘:
- 코딩 모르는 사람의 사이트를 본다는 걸 전제할 것
- 문제마다 어느 파일인지, 왜 문제인지, 안 고치면 뭐가 나쁜지 한 줄씩
- 심각한 순서대로 정리할 것
- 문제가 없으면 없다고 말할 것

만든 다음, 네 줄짜리 프런트매터가 각각 무슨 뜻인지 설명해 줘.

/agents라는 명령어도 있는데, 버전에 따라 만들기 화면이 열리기도 하고 안내만 나오기도 해요. 어느 쪽이든 상관없어요. 파일을 만들면 되니까요.

3. 네 줄이 하는 일

• name — 부를 이름이에요. 소문자와 하이픈만 써요.
• description — 스킬 때와 똑같아요. 언제 부를지를 적어요. 이 문장을 보고 에이전트가 알아서 이 전문가를 불러와요.
• tools — 열쇠 꾸러미예요. 여기 적힌 도구만 쓸 수 있어요.
• model — 안 적으면 지금 쓰는 모델을 그대로 써요. 지금은 신경 안 써도 돼요.

tools에 적은 세 가지는 전부 읽기예요. 파일을 열고, 내용을 찾고, 파일 목록을 보는 것. 고치는 도구는 없어요.

tools를 아예 안 적으면 어떻게 될까요. 모든 도구를 물려받아요. 다 할 수 있게 돼요. 그러니 안전하게 만들고 싶다면 반드시 적어야 해요. 비워두는 게 "제한"이 아니라 "전부 허용"이라는 걸 꼭 기억하세요.

4. 검수를 시켜보기

reviewer한테 내 사이트 세 페이지를 점검시켜 줘.

문제 목록이 돌아와요. 링크가 깨졌다든지, 폰에서 글자가 잘린다든지, 페이지마다 메뉴 이름이 다르다든지.

지난 강의에서 매번 설명했던 걸, 오늘은 이름만 불렀어요.

5. 고쳐달라고 시켜보기

이제 오늘의 순간이에요. 검수자에게 직접 시켜보세요.

reviewer가 찾은 문제들, reviewer한테 직접 고치라고 해 줘.

못 고쳐요.

권한이 없다고 말하거나, 고칠 수 없어서 제안만 한다고 답해요. 읽기 도구밖에 없으니까요.

무섭지 않죠. 오히려 안심이 돼요. 검수자가 마음대로 내 파일을 건드릴 수 없다는 게 파일 한 줄로 보장되니까요.

시즌 2의 3강에서 배운 권한 모드를 기억하나요. 매번 물어보기, 편집 자동 수락, 계획만. 그건 대화 전체에 거는 안전장치였어요. 오늘 건 에이전트마다 거는 안전장치예요.

6. 그럼 누가 고치나

검수자는 찾고, 고치는 건 본 에이전트가 해요.

reviewer가 찾은 문제 중에서 첫 번째 것만 네가 고쳐 줘.
고친 다음 브라우저로 열어서 네 눈으로 확인하고 알려 줘.

역할이 나뉘었어요. 찾는 사람과 고치는 사람이 다르죠. 이게 검수가 검수답게 작동하는 이유예요. 자기가 쓴 글을 자기가 교정하면 오타를 놓치잖아요.

7. 이름을 직접 부르기

두 가지 방법이 있어요.

알아서 오게 하기 — description에 적은 상황이 오면 에이전트가 스스로 불러요. "점검해 줘"라고만 해도요.

콕 집어 부르기 — 채팅창에 @를 치면 목록이 떠요. 거기서 reviewer를 고르면 반드시 그 전문가가 와요.

둘 다 해보세요. 알아서 오는 게 편하지만, 확실히 그를 부르고 싶을 땐 두 번째가 좋아요.

8. 전문가는 한 명이면 충분해요

여기서 멈추세요.

지금 당장 "테스터", "디자이너", "카피라이터"를 줄줄이 만들고 싶어질 거예요. 참으세요. 한 명도 제대로 안 써봤는데 다섯 명을 만들면, 관리할 파일만 늘어요.

일주일 써보고, 진짜로 반복되는 역할이 하나 더 보이면 그때 만드세요. 다음 강의가 이 이야기예요.

막혔을 때

tools에 적은 이름이 안 먹혀요. 대소문자를 확인하세요. Read, Grep, Glob처럼 첫 글자가 대문자예요. read라고 쓰면 인식이 안 될 수 있어요. 에이전트에게 "지금 이 서브에이전트가 쓸 수 있는 도구를 알려 줘"라고 물어 확인하세요.

고치라고 했는데 그냥 고쳐버렸어요. tools 줄이 빠졌거나 오타가 났을 가능성이 커요. 파일을 다시 열어 확인하세요. 빈 tools는 제한이 아니라 전부 허용이에요.

@를 쳐도 목록이 안 떠요. Claude Code를 껐다 켜보세요. 파일을 새로 만들면 인식까지 잠깐 걸려요. 그래도 안 되면 파일 위치를 확인하세요. my-page/.claude/agents/reviewer.md여야 해요.

검수 결과가 너무 뻔해요. 본문 지시가 부족한 거예요. "내 사이트는 자기소개 페이지야. 방문자는 폰으로 볼 가능성이 높아"처럼 맥락을 적어주면 결과가 달라져요.

전문가가 자꾸 불려 나와서 귀찮아요. description이 너무 넓어요. "점검"처럼 흔한 단어 말고 "내 웹페이지를 검수할 때"처럼 좁히세요.

마무리 체크

나가기 전에 하나씩 확인해요:

• .claude/agents/reviewer.md가 있어요 (폴더가 아니라 파일)
• description에 언제 부를지가 적혀 있어요
• tools가 읽기 도구로만 좁혀져 있어요
• 검수를 시켜 문제 목록을 받았어요
• 고치라고 시켰는데 못 고쳤어요 ← 오늘의 순간
• 찾는 사람과 고치는 사람을 나눠봤어요
• @로 직접 불러봤어요

다섯 번째가 오늘의 결론이에요. 권한은 신뢰의 문제가 아니라 사고를 막는 장치예요. 파일 한 줄로 걸 수 있고요.

이제 스킬 하나와 전문가 하나가 생겼어요. 마지막 강의에서는 반대 방향을 봅니다. 언제 맡기면 안 되는가. 위임에도 값이 붙거든요.