로딩 중...
로딩 중...
Claude Code 서브에이전트를 활용하면 CRM 코드베이스를 분석해서 사용자 설명서와 비주얼 가이드북을 자동으로 생성할 수 있습니다. 수작업으로 2일 이상 걸릴 문서화 작업을 단 20분 만에 끝낸 실전 경험을 공유합니다. 어떻게 가능했을까요?
CRM 시스템을 운영하다 보면 늘 부딪히는 문제가 있습니다. 코드는 완성되어 있는데 사용자 설명서가 없는 것입니다. 상담원용, 관리자용, 시스템 운영팀용으로 각각 가이드가 필요한데, 수십 개의 컴포넌트와 페이지를 하나하나 읽어가며 문서를 작성하려면 최소 2일은 잡아야 합니다.
더 큰 문제는 코드가 업데이트될 때마다 문서도 함께 수정해야 한다는 점입니다. 결국 문서는 점점 코드와 동떨어지고, 신규 입사자는 선배에게 물어보는 수밖에 없는 상황이 반복됩니다.
이번에 Claude Code의 서브에이전트(Sub-Agent) 아키텍처를 활용해 이 작업을 통째로 자동화해봤습니다.
Claude Code에게 CRM 코드베이스를 분석해서 사용자 설명서를 만들어 달라고 요청하자, 즉시 두 개의 서브에이전트를 병렬로 실행했습니다.
위 실행 화면을 보면 두 에이전트의 진행 상황이 실시간으로 표시됩니다:
SelfApplicationChecklist.tsx 등 실제 파일을 분석 중PlanManagementPage.tsx 등을 읽는 중핵심은 두 에이전트가 동시에 독립적으로 코드를 탐색한다는 점입니다. 순차적으로 작업했다면 두 배의 시간이 걸렸을 것입니다. 2분 16초 만에 코드 탐색을 마치고 문서 작성에 들어갔습니다.
관리자 시스템 온보딩 및 사용 설명서가 완성되었습니다. UTM 파라미터, GA4, Meta CAPI 같은 마케팅 추적 기능까지 코드에서 읽어내서 문서화한 것이 인상적입니다. 용어 정리(Appendix B), 문의 및 지원 섹션, 관련 문서 링크까지 전문적으로 구성되어 있습니다.
상담원 실무 가이드는 무려 1,662줄에 달하는 방대한 문서로 완성되었습니다. 리드 목록 활용법, 상담 패널 사용법, 요금제 비교 등 상담원이 실무에서 바로 활용할 수 있는 내용이 체계적으로 정리되어 있습니다. 마지막에는 "여러분의 성공을 응원합니다!"라는 메시지까지 담겨 있습니다.
코드를 직접 읽고 이해한 뒤 문서를 만들기 때문에, 코드와 문서 사이의 괴리가 없습니다. 이것이 AI 코드 자동화의 가장 큰 강점입니다.
텍스트 문서만으로는 부족했습니다. 스크린샷이 포함된 비주얼 가이드북을 추가로 요청했습니다. Claude Code는 즉시 멀티모델 전략을 수립했습니다.
3종의 비주얼 가이드를 계획하고, 2단계(Phase)로 나눠서 진행합니다:
| 파일 | 대상 | 포함 내용 |
|---|---|---|
| VISUAL_GUIDE_CONSULTANT.html | 상담원 | 리드 목록, 상담 패널, 요금제 비교 등 |
| VISUAL_GUIDE_ADMIN.html | 관리자 | 대시보드, 가입관리, 마케팅 분석, 성과 등 |
| VISUAL_GUIDE_SYSTEM.html | 시스템 운영팀 | 사용자관리, 설정, 분배규칙, 요금제관리 |
여기서 정말 놀라운 점은 각 모델의 역할이 자동으로 분배된다는 것입니다:
메인 에이전트(Opus)는 전체 워크플로우를 조율하고, 작업 성격에 따라 적절한 모델을 자동 배치합니다. Haiku는 빠른 이미지 분석에, Sonnet은 글 작성과 프론트엔드 코드 생성에 각각 투입되었습니다.
완성된 비주얼 가이드를 보면, Playwright로 캡처한 실제 CRM 화면 위에 번호 티커가 정확한 위치에 표시되어 있습니다.
스크린샷 위의 빨간색 번호 티커 아래에 각 번호에 대한 설명이 정리되어 있습니다:
코드만 읽고도 UI의 어느 위치에 어떤 기능이 있는지 정확하게 짚어낸 것입니다. 사람이 직접 스크린샷을 찍고 포토샵에서 마커를 달고 설명을 작성하는 과정을 완전히 자동화했습니다.
마지막으로 shadcn UI 라이브러리를 적용해서 비주얼 가이드의 디자인을 개선했습니다.
깔끔한 카드 레이아웃, 파란색 번호 뱃지, 단계별 설명이 보기 좋게 정리된 최종 결과물입니다. 이대로 사내 위키나 온보딩 문서로 바로 배포할 수 있는 수준의 완성도입니다.
전체 작업이 어떻게 진행되었는지 정리하면 다음과 같습니다:
[사용자 요청: 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(조율) |
A: Claude Code CLI가 설치된 환경이면 됩니다. 서브에이전트는 Claude Code가 자동으로 관리하며, 복잡한 작업을 분석해서 자동으로 병렬 에이전트를 생성합니다. Playwright 기반 스크린샷 기능을 사용하려면 Node.js 환경과 Playwright 설치가 추가로 필요합니다.
A: 코드를 직접 읽고 분석하기 때문에 기능 설명의 정확도가 매우 높습니다. 다만 비즈니스 맥락이나 사내 용어는 사전에 CLAUDE.md 등에 정의해두면 더 정확한 결과를 얻을 수 있습니다. 최종 검수는 사람이 하는 것을 권장합니다.
A: 네, 로컬 또는 스테이징 환경에서 CRM이 실행 중이어야 Playwright가 화면을 캡처할 수 있습니다. Claude Code가 자동으로 URL을 감지하고 각 페이지를 순회하며 스크린샷을 촬영합니다.
Claude Code 서브에이전트는 단순히 "빠르게 해주는 도구"를 넘어서, 사람이 하기 귀찮고 반복적인 문서화 작업을 전문가 수준으로 자동화합니다. 특히 코드베이스를 직접 읽고 이해한 뒤 문서를 생성하기 때문에, 코드와 문서 사이의 괴리가 발생하지 않습니다.
2일 걸릴 작업을 20분에 끝내면서도 비주얼 가이드의 티커 배치까지 정확하게 처리하는 이 경험은, AI 코드 자동화의 가능성이 어디까지인지 다시 한번 보여주었습니다. CRM뿐 아니라 어떤 코드베이스든 Claude Code 서브에이전트에게 문서화를 맡겨보시기 바랍니다.