클로드코드로 나만의 AI 부하직원 만들기 · 0편

클로드코드로 나만의 AI 부하직원 만들기 · 0편

똑같은 지시 매번 반복하는 거, 슬슬 지겹지 않아?

코드 한 줄 없이 시작하는 서브에이전트 이야기 — 왜 필요한지부터 편하게 풀어볼게.

안녕! 이 시리즈는 클로드코드(Claude Code)로 '내 일을 대신 해주는 AI 조수'를 직접 만들어보는 이야기야. 거창하게 들리지? 근데 막상 만들어보면 파일 하나 만드는 게 전부라서 좀 허무할 정도야.

0편인 오늘은 실습 없어. 그냥 "이걸 왜 만들면 편해지는지"만 가볍게 이해하고 넘어가는 편이야. 이 감만 잡히면 1편부터는 손이 알아서 움직일 거야.

그래서 서브에이전트가 뭔데?

클로드코드 좀 써봤으면 이런 경험 있을 거야. 코드 좀 짜달라고 하면 잘 짜주긴 하는데, 그때마다 "아 참, 우리는 MyBatis 쓰고, 네이밍은 이렇게 하고, SQL 인젝션 조심하고..." 이 잔소리를 매번 붙여야 하잖아.

나: UserService 리뷰해줘.
나: 아 맞다, 우리 MyBatis 쓰니까 ${} 인젝션도 봐주고,
나: 트랜잭션 처리 빠진 것도 체크하고, 널 체크도 보고...

이 반복되는 지시를 미리 적어둔 파일이 바로 서브에이전트야. "너는 우리 프로젝트 전문 코드 리뷰어야. 리뷰할 땐 이것부터 봐." 이렇게 한 번만 적어두면, 다음부터는 "리뷰해줘" 한마디에 그 담당자가 알아서 튀어나와.

쉽게 말하면 클로드코드 본체가 팀장이고, 서브에이전트는 팀장이 필요할 때 부르는 전문 담당자라고 보면 돼. 리뷰 담당, 테스트 담당, 문서 정리 담당… 이렇게 역할별로 담당자를 두는 거지.

이게 왜 좋은데? 핵심 3가지

단순히 "지시를 미리 저장한다" 그 이상의 이점이 있어. 이 세 가지가 서브에이전트를 진짜 쓸모 있게 만들어줘.

1. 기억(컨텍스트)이 따로 돌아가. 담당자는 자기만의 작업 공간에서 일하고, 팀장한테는 결과 요약만 가져와. 그래서 리뷰하느라 코드 수백 줄을 뒤져도 내 메인 대화창은 안 지저분해져. 팀장 책상은 늘 깔끔한 거지.

2. 성격을 정해줄 수 있어. 담당자마다 자기만의 시스템 프롬프트(=성격서)를 가져. 리뷰 담당한텐 SQL 인젝션 지식을, 테스트 담당한텐 테스트 전략을 몰아줄 수 있어. 서로 필요 없는 지식으로 헷갈릴 일이 없지.

3. 권한을 제한할 수 있어. 이게 은근 제일 중요해. "이 담당자는 읽기만 가능하고 파일 수정은 절대 못 함" 같은 안전장치를 걸 수 있어. AI한테 실수로 삭제 권한 줬다가 식겁하는 일을 아예 막아버리는 거야.

✕ 서브에이전트 없이

• 매번 같은 규칙을 손으로 다시 입력
• 긴 작업이 메인 대화를 다 잡아먹음
• AI가 뭘 건드릴지 통제하기 어려움

○ 서브에이전트 있으면

• "리뷰해줘" 한마디면 규칙 자동 적용
• 작업은 담당자가, 대화창은 깔끔하게
• 읽기 전용 같은 권한을 미리 못박아둠

제일 놀라운 사실

여기까지 들으면 뭔가 대단한 프로그래밍이 필요할 것 같지? 전혀 아냐. 서브에이전트의 정체는 이거야.

이 시리즈에서 딱 하나만 기억한다면

마크다운 파일 하나 = 담당자 하나.
.claude/agents/ 폴더에 .md 파일을 넣으면, 그게 곧 에이전트야.

파일 맨 위에 간단한 설정을 적고, 그 아래에 "너는 이런 일 하는 애야"라고 평범한 문장으로 성격을 써주면 끝이야. 코딩이라기보단 글쓰기에 가깝지. 그래서 개발 잘 몰라도 만들 수 있어.

앞으로 이런 순서로 갈게

• 1편 — 첫 담당자 채용하기. 폴더 만들고 파일 하나 따라 쳐서, 5분 만에 동작하는 코드 리뷰어 만들어보자.
• 2편 — 파일 뜯어보기. "왜 내 에이전트는 안 불려나오지?" 설정 3개 + 본문 구조를 파헤쳐볼게.
• 3편 — 부르는 법 두 가지. 알아서 오게 둘지, 콕 집어 부를지.
• 4편 — 권한으로 안전하게. 이 시리즈에서 제일 중요한 편이야.
• 5편 — 팀 꾸리기. 담당자 여럿을 조합해서 실전 워크플로우 만들기.
• 6편(보너스) — 독립 앱으로. 혼자 도는 AI 앱까지 넘어가는 다리.

다음 편 예고 → 1편에선 진짜로 손을 움직여볼 거야. PowerShell 열고 폴더 하나 만드는 것부터, 첫 코드 리뷰어가 /agents 목록에 뜨는 순간까지. 딱 5분이면 돼. 오늘은 "아, 파일 하나면 되는구나"만 챙겨가면 충분해. 그럼 1편에서 봐!