Claude Code 서브에이전트로 CRM 사용자 설명서 20분 만에 완성하는 방법

Claude Code 서브에이전트를 활용하면 CRM 코드베이스를 분석해서 사용자 설명서와 비주얼 가이드북을 자동으로 생성할 수 있습니다. 수작업으로 2일 이상 걸릴 문서화 작업을 단 20분 만에 끝낸 실전 경험을 공유합니다. 어떻게 가능했을까요?

CRM 문서화의 현실: 코드는 있는데 설명서가 없다

CRM 시스템을 운영하다 보면 늘 부딪히는 문제가 있습니다. 코드는 완성되어 있는데 사용자 설명서가 없는 것입니다. 상담원용, 관리자용, 시스템 운영팀용으로 각각 가이드가 필요한데, 수십 개의 컴포넌트와 페이지를 하나하나 읽어가며 문서를 작성하려면 최소 2일은 잡아야 합니다.

더 큰 문제는 코드가 업데이트될 때마다 문서도 함께 수정해야 한다는 점입니다. 결국 문서는 점점 코드와 동떨어지고, 신규 입사자는 선배에게 물어보는 수밖에 없는 상황이 반복됩니다.

이번에 Claude Code의 서브에이전트(Sub-Agent) 아키텍처를 활용해 이 작업을 통째로 자동화해봤습니다.

AI 코드 자동화: 서브에이전트 2개로 설명서 병렬 작성

Claude Code에게 CRM 코드베이스를 분석해서 사용자 설명서를 만들어 달라고 요청하자, 즉시 두 개의 서브에이전트를 병렬로 실행했습니다.

위 실행 화면을 보면 두 에이전트의 진행 상황이 실시간으로 표시됩니다:

• 상담원 가이드 에이전트: 컴포넌트가 40개 가까이 되어 탐색량이 많고, 도구 호출 30회를 넘기며 SelfApplicationChecklist.tsx 등 실제 파일을 분석 중
• 관리자 가이드 에이전트: 페이지 단위로 더 빠르게 진행하며, PlanManagementPage.tsx 등을 읽는 중

핵심은 두 에이전트가 동시에 독립적으로 코드를 탐색한다는 점입니다. 순차적으로 작업했다면 두 배의 시간이 걸렸을 것입니다. 2분 16초 만에 코드 탐색을 마치고 문서 작성에 들어갔습니다.

결과물 1: 관리자 온보딩 가이드 (920줄)

관리자 시스템 온보딩 및 사용 설명서가 완성되었습니다. UTM 파라미터, GA4, Meta CAPI 같은 마케팅 추적 기능까지 코드에서 읽어내서 문서화한 것이 인상적입니다. 용어 정리(Appendix B), 문의 및 지원 섹션, 관련 문서 링크까지 전문적으로 구성되어 있습니다.

결과물 2: 상담원 실무 가이드 (1,662줄)

상담원 실무 가이드는 무려 1,662줄에 달하는 방대한 문서로 완성되었습니다. 리드 목록 활용법, 상담 패널 사용법, 요금제 비교 등 상담원이 실무에서 바로 활용할 수 있는 내용이 체계적으로 정리되어 있습니다. 마지막에는 "여러분의 성공을 응원합니다!"라는 메시지까지 담겨 있습니다.

코드를 직접 읽고 이해한 뒤 문서를 만들기 때문에, 코드와 문서 사이의 괴리가 없습니다. 이것이 AI 코드 자동화의 가장 큰 강점입니다.

멀티에이전트 개발: Playwright + Haiku + Sonnet 협업으로 비주얼 가이드 제작

텍스트 문서만으로는 부족했습니다. 스크린샷이 포함된 비주얼 가이드북을 추가로 요청했습니다. Claude Code는 즉시 멀티모델 전략을 수립했습니다.

3종의 비주얼 가이드를 계획하고, 2단계(Phase)로 나눠서 진행합니다:

파일	대상	포함 내용
VISUAL_GUIDE_CONSULTANT.html	상담원	리드 목록, 상담 패널, 요금제 비교 등
VISUAL_GUIDE_ADMIN.html	관리자	대시보드, 가입관리, 마케팅 분석, 성과 등
VISUAL_GUIDE_SYSTEM.html	시스템 운영팀	사용자관리, 설정, 분배규칙, 요금제관리

여기서 정말 놀라운 점은 각 모델의 역할이 자동으로 분배된다는 것입니다:

1. Phase 1 - 스크린샷 촬영: Playwright로 실제 CRM 화면을 자동 캡처하고, Haiku(경량 모델)가 스크린샷을 빠르게 분석
2. Phase 2 - 가이드 작성: Sonnet 서브에이전트 3개가 병렬로 각각 상담원/관리자/시스템 가이드 HTML을 작성

메인 에이전트(Opus)는 전체 워크플로우를 조율하고, 작업 성격에 따라 적절한 모델을 자동 배치합니다. Haiku는 빠른 이미지 분석에, Sonnet은 글 작성과 프론트엔드 코드 생성에 각각 투입되었습니다.

CRM 사용자 설명서에 티커(Marker)까지 자동 배치

완성된 비주얼 가이드를 보면, Playwright로 캡처한 실제 CRM 화면 위에 번호 티커가 정확한 위치에 표시되어 있습니다.

스크린샷 위의 빨간색 번호 티커 아래에 각 번호에 대한 설명이 정리되어 있습니다:

1. 아이디 입력 - 관리자 계정 아이디를 입력합니다
2. 비밀번호 입력 - 안전한 비밀번호를 입력합니다
3. 로그인 버튼 - 클릭하여 시스템에 접속합니다

코드만 읽고도 UI의 어느 위치에 어떤 기능이 있는지 정확하게 짚어낸 것입니다. 사람이 직접 스크린샷을 찍고 포토샵에서 마커를 달고 설명을 작성하는 과정을 완전히 자동화했습니다.

shadcn UI 라이브러리로 디자인 완성도까지 확보

마지막으로 shadcn UI 라이브러리를 적용해서 비주얼 가이드의 디자인을 개선했습니다.

깔끔한 카드 레이아웃, 파란색 번호 뱃지, 단계별 설명이 보기 좋게 정리된 최종 결과물입니다. 이대로 사내 위키나 온보딩 문서로 바로 배포할 수 있는 수준의 완성도입니다.

Claude Code 서브에이전트 작업 흐름 총정리

전체 작업이 어떻게 진행되었는지 정리하면 다음과 같습니다:

[사용자 요청: CRM 사용자 설명서 만들어줘]
     |
     v
[Claude Code 메인 에이전트 (Opus)] ── 전략 수립 및 조율
     |
     ├── [서브에이전트 1] 상담원 가이드 (코드 탐색 → 1,662줄 문서 작성)
     ├── [서브에이전트 2] 관리자 가이드 (코드 탐색 → 920줄 문서 작성)
     |
     v
[추가 요청: 비주얼 가이드북도 만들어줘]
     |
     ├── Phase 1: Playwright 스크린샷 자동 촬영 + Haiku 이미지 분석
     |
     ├── [Sonnet 서브에이전트 1] 상담원 비주얼 가이드 HTML
     ├── [Sonnet 서브에이전트 2] 관리자 비주얼 가이드 HTML
     ├── [Sonnet 서브에이전트 3] 시스템 비주얼 가이드 HTML
     |
     v
[shadcn UI 디자인 개선]
     |
     v
[완성] 총 소요 시간: 약 20분

수치로 보는 성과

항목	결과
상담원 실무 가이드	1,662줄 마크다운
관리자 온보딩 가이드	920줄 마크다운
비주얼 가이드 HTML	3종 (상담원/관리자/시스템)
총 소요 시간	약 20분
수작업 예상 소요 시간	2일 이상
투입 모델	Haiku(스크린샷 분석), Sonnet(글 작성 + 프론트 코드), Opus(조율)

Claude Code 서브에이전트의 5가지 핵심 강점

1. 병렬 처리로 시간 단축: 상담원/관리자 가이드를 동시 작성하여 작업 시간을 절반으로 줄임
2. 멀티모델 자동 배치: 작업 성격에 맞는 모델을 자동 선택 (Haiku → 빠른 분석, Sonnet → 콘텐츠 생성)
3. 코드 기반 문서 자동 생성: 실제 코드베이스를 직접 읽고 기능을 파악하여 정확한 문서화
4. Playwright 연동 자동화: 실제 화면을 자동 캡처하고 티커를 배치하여 비주얼 가이드 제작
5. 메인 에이전트의 오케스트레이션: 전체 워크플로우를 관리하며, 품질 검수와 교차 참조까지 수행

자주 묻는 질문 (FAQ)

Q: Claude Code 서브에이전트를 사용하려면 어떤 환경이 필요한가요?

A: Claude Code CLI가 설치된 환경이면 됩니다. 서브에이전트는 Claude Code가 자동으로 관리하며, 복잡한 작업을 분석해서 자동으로 병렬 에이전트를 생성합니다. Playwright 기반 스크린샷 기능을 사용하려면 Node.js 환경과 Playwright 설치가 추가로 필요합니다.

Q: Claude Code로 문서 자동화할 때 결과물의 정확도는 어느 정도인가요?

A: 코드를 직접 읽고 분석하기 때문에 기능 설명의 정확도가 매우 높습니다. 다만 비즈니스 맥락이나 사내 용어는 사전에 CLAUDE.md 등에 정의해두면 더 정확한 결과를 얻을 수 있습니다. 최종 검수는 사람이 하는 것을 권장합니다.

Q: Playwright 스크린샷 비주얼 가이드를 만들려면 CRM이 실행 중이어야 하나요?

A: 네, 로컬 또는 스테이징 환경에서 CRM이 실행 중이어야 Playwright가 화면을 캡처할 수 있습니다. Claude Code가 자동으로 URL을 감지하고 각 페이지를 순회하며 스크린샷을 촬영합니다.

결론

Claude Code 서브에이전트는 단순히 "빠르게 해주는 도구"를 넘어서, 사람이 하기 귀찮고 반복적인 문서화 작업을 전문가 수준으로 자동화합니다. 특히 코드베이스를 직접 읽고 이해한 뒤 문서를 생성하기 때문에, 코드와 문서 사이의 괴리가 발생하지 않습니다.

2일 걸릴 작업을 20분에 끝내면서도 비주얼 가이드의 티커 배치까지 정확하게 처리하는 이 경험은, AI 코드 자동화의 가능성이 어디까지인지 다시 한번 보여주었습니다. CRM뿐 아니라 어떤 코드베이스든 Claude Code 서브에이전트에게 문서화를 맡겨보시기 바랍니다.