6개월 동안 Claude Code를 극한까지 굴리며(단독 30만 LOC 리라이트) 구축한 스킬 자동 활성화, Dev Docs 워크플로우, PM2+훅 기반 무오류 파이프라인, 전문 에이전트 운용, 프롬프트 요령 등을 실전 중심으로 정리했다.
게으른 동지들을 위한 초간단 팁: 이 장문의 글을 ElevenLabs Reader나 Natural Reader같은 TTS 서비스에 넣고 들으세요 :)
약 6개월 전, Claude Code를 일주일 하드코어로 써 본 후기를 올렸습니다. 그리고 지금은 6개월 하드코어 사용의 결과물을 더 풀어보려 합니다. 조금 과하게 길어졌을지 모르니 안전벨트 매고, 커피 들고, 화장실 왕좌에 앉든, 뭐든 편한 자세로 둠스크롤을 시작하시죠.
먼저 면책 문구부터: 여기 담긴 내용은 지금 제 워크플로우에서 가장 잘 먹히는 셋업을 공유하는 것일 뿐 정답도, 유일한 방법도 아닙니다. 여러분이 AI 에이전트 코딩 워크플로우를 개선하는 데 영감을 주려는 목적일 뿐이에요. 저는 그냥 한 사람이고, 이건 제 개인적인 의견일 뿐입니다.
또, 저는 20x Max 플랜을 쓰고 있어요. 그래서 여러분의 경험과 다를 수 있습니다. 바이브 코딩 팁을 찾으신다면 다른 곳을 보세요. CC에서 최고의 결과를 원한다면 계획하고, 리뷰하고, 반복하고, 다양한 접근을 탐색하는 식으로 함께 일해야 합니다.
6개월 동안 Claude Code를 한계까지 몰아붙이며(혼자 30만 LOC 리라이트), 이렇게 셋업했습니다:
자, 들어갑니다.
지난 7년간 프로덕션 웹앱을 만들어 온 소프트웨어 엔지니어입니다. 저는 AI 물결을 기꺼이 받아들였고, AI가 제 일을 당장 대체할 거라 걱정하지 않습니다. 제 역량을 레버리지하는 도구니까요. 그 결과, 저는 아주 많은 신규 기능을 빠르게 만들고, Claude와 GPT-5 Thinking으로 새로운 AI 시스템을 프로덕션 앱에 녹여내는 제안서도 잔뜩 만들고 있습니다. 예전 같으면 시도조차 못 했을 프로젝트들을요. 이 덕분에 회사에서 일종의 AI 구루가 되었고, 남들보다 1년쯤 앞서 워크플로우에 AI를 녹이며 일자리를 꽤 견고히 지키고 있습니다.
그래서 자신감이 붙은 김에, 사내 내부툴로 쓰는 웹앱 하나의 대규모 리디자인/리팩터를 제안했습니다. 이건 대학생이 만든 거친 프로젝트였고, 제가 인턴일 때 만든 다른 프로젝트를 포크해(7년 전 제작, 4년 전 포크) 굴려오던 물건이었습니다. 솔직히 다소 무모했죠. 이해관계자들을 설득하려고 “꽤 큰 규모(약 10만 LOC)의 프로젝트를 몇 달 안에, 혼자서, 탑다운으로 전면 개편하겠다”라고 해버렸거든요. CC의 도움을 받아도 야근이 필수라는 걸 알고 있었습니다. 그래도 이게 대박을 칠 거란 믿음이 있었고, 여러 수작업을 자동화해 회사 사람들의 시간을 크게 아껴줄 거라 확신했습니다.
6개월이 지난 지금… 네, 그 일정에 동의한 건 아마 실수였을 겁니다. Claude의 한계도, 제 정신력의 한계도 모조리 테스트했죠. 프런트엔드는 완전히 갈아엎었습니다. 최신 스택으로 놀아보고 싶었고, 기존이 너무 올드했거든요. React 16 JS → React 19 TypeScript, React Query v2 → TanStack Query v5, React Router v4 + hashrouter → TanStack Router 파일 기반 라우팅, Material UI v4 → MUI v7, 거기에 베스트 프랙티스 철저 준수. 지금 프로젝트는 약 30만~40만 LOC이고, 제 기대 수명은 5년 줄었습니다. 이제 드디어 테스트에 올릴 준비가 되었고, 결과물에 무척 만족합니다.
예전엔 감당 불가능한 기술부채, 0% 테스트 커버리지, 끔찍한 DX(테스트가 악몽), 온갖 이상한 꼼수로 가득한 프로젝트였습니다. 이제는 꽤 괜찮은 테스트 커버리지, 관리 가능한 기술부채, 테스트 데이터를 생성하는 CLI와 프런트엔드 기능별 테스트용 dev 모드를 갖추었습니다. 이 과정에서 CC의 능력과 한계를 체감했고 무엇을 기대해야 하는지 감이 잡혔습니다.
포럼을 보다 보면 사용량 제한 문제나 시간이 갈수록 품질이 떨어진다는 불만이 반복적으로 보입니다. 그 경험을 깎아내리거나 “너 프롬프트를 잘못 쓰는 거야”라고 할 생각은 없습니다. 모두의 맥락과 용례가 다르고, 유효한 우려는 경청받아야 하니까요.
다만, 제게 효과적이었던 걸 공유하려 합니다. 제 경험상 CC의 출력 품질은 최근 몇 달 사이에 오히려 꽤 좋아졌고, 이는 제가 워크플로우를 끊임없이 다듬은 덕분이라고 봅니다. 제 시스템에서 작은 부분이라도 가져다 적용하시면, 여러분이 만족할 만한 품질을 얻을 확률이 늘어날 겁니다.
물론 현실적으로, Claude가 완전히 빗나가거나 미흡한 코드를 내놓는 때가 있습니다. 이유는 다양하죠. 첫째, AI 모델은 확률적입니다. 같은 입력에도 출력이 널뛰기할 수 있어요. 운 나쁘면, 여러분 책임이 아닌데도 형편없는 답을 받을 때가 있습니다. 둘째, 프롬프트 구성의 문제도 큽니다. 모델은 글자 그대로 받아들이는 경향이 있어 작은 문구 차이로도 결과가 달라집니다. 애매하게 말하거나 오해의 소지가 있으면 결과가 크게 나빠질 수 있어요.
AI는 대단하지만 마법은 아닙니다. 패턴 인식과 인간적 직관이 이기는 문제들이 있어요. Claude가 30분 동안 씨름하는 걸 지켜보다가, 여러분이 2분이면 끝낼 수 있는 문제라면 그냥 직접 해결하세요. 부끄러워할 필요 없습니다. 자전거 가르칠 때, 잠깐은 핸들을 잡아주는 법이죠.
특히 논리 퍼즐이나 상식이 필요한 문제에서 이런 일이 잦습니다. AI는 많은 걸 브루트포스로 밀어붙일 수 있지만, 사람이 더 빨리 “감”으로 해결하는 경우가 있어요. “AI가 다 해야 해”라는 고집 때문에 시간을 낭비하지 마세요. 잠깐 개입해서 바로잡고, 계속 전진하면 됩니다.
저도 형편없는 프롬프트를 많이 썼습니다. 보통 하루 끝무렵, 대충 쓰고 싶어질 때요. 그러면 결과가 확 나빠집니다. 그러니 “요즘 출력이 왜 이러지? Anthropic이 그림자 너프한 거 아냐?”라는 생각이 들면, 잠깐 멈추고 내 프롬프트가 어떤지 되돌아보세요.
자주 재프롬프트하세요. 더블 ESC로 이전 프롬프트를 띄워 브랜치할 수 있습니다. 같은 프롬프트라도 “무엇이 싫었는지”를 알고 다시 던지면 결과가 놀랄 만큼 좋아지곤 합니다. 즉, 출력 품질이 나빠 보이는 데는 여러 이유가 있고, 내가 원하는 출력을 얻기 위해 무엇을 제공할 수 있는지 스스로 돌아보는 게 중요합니다.
어딘가 현자님이 이렇게 말했을 겁니다. “Claude가 너를 위해 뭘 해줄지 묻지 말고, Claude에게 어떤 컨텍스트를 줄 수 있을지 물어라.” ~ 현자님
자, 설교는 여기까지. 본론으로 갑니다.
지난 6개월 동안 CC 관련 워크플로우를 크게 손봤고, 결과가 꽤 좋았습니다(제 기준).
이건 제 워크플로우를 완전히 바꾼 기능이라 별도 섹션으로 빼야 합니다.
Anthropic이 Skills 기능을 내놨을 때 “와, 이거다!” 싶었습니다. 방대한 코드베이스에서 일관성을 유지하려면, Claude가 참조할 수 있는 휴대 가능한 재사용 지침이 딱이었거든요. 그래서 프런트엔드, 백엔드, DB, 워크플로우 등등에 대한 종합적인 스킬을 Claude와 함께 만들었습니다. 수천 줄에 달하는 베스트 프랙티스, 패턴, 예시들요.
그런데… 안 씁니다. 스킬 설명에 쓴 키워드를 그대로 말해도 반응이 없어요. 스킬이 트리거돼야 할 파일을 만져도 조용합니다. 잠재력은 보이는데, 그냥 비싼 장식처럼 있는 겁니다.
그래서 hooks를 떠올렸습니다. Claude가 스킬을 자동으로 안 쓰면, 무조건 먼저 관련 스킬을 확인하게 “만들어” 버리면 어떨까?
Claude Code의 훅 시스템을 파고들어 TypeScript 훅으로 다층 자동 활성화 구조를 만들었습니다. 그리고… 잘 됩니다!
두 가지 핵심 훅을 만들었습니다:
1. UserPromptSubmit Hook(Claude가 여러분의 메시지를 보기 “전”에 동작):
2. Stop Event Hook(Claude가 답변을 끝낸 “후”에 동작):
모든 스킬을 정의하는 중앙 설정 파일을 만들었습니다. 여기에 다음을 담습니다:
예시 스니펫:
{
"backend-dev-guidelines": {
"type": "domain",
"enforcement": "suggest",
"priority": "high",
"promptTriggers": {
"keywords": ["backend", "controller", "service", "API", "endpoint"],
"intentPatterns": [
"(create|add).*?(route|endpoint|controller)",
"(how to|best practice).*?(backend|API)"
]
},
"fileTriggers": {
"pathPatterns": ["backend/src/**/*.ts"],
"contentPatterns": ["router\\.", "export.*Controller"]
}
}
}
이제 백엔드 코드를 작업하면 Claude는 자동으로:
차이가 확연합니다. 더는 뒤죽박죽 코드가 나오지 않고, “또 옛 패턴 썼네?”가 사라졌고, 매번 “가이드라인 확인하라”고 수동으로 상기시킬 필요도 없어졌습니다.
자동 활성화가 돌아간 뒤, Anthropic의 공식 베스트 프랙티스를 더 파보니 제가 잘못하고 있더군요. 메인 SKILL.md는 500줄 이하로 유지하고, 리소스 파일로 점진적 공개를 하라고 권장합니다.
저의 frontend-dev-guidelines는 1,500줄이 넘었습니다. 1,000줄 넘는 스킬도 여럿. 이렇게 거대한 파일은 “필요한 것만 로드”라는 스킬의 취지를 정면으로 거스릅니다.
그래서 구조를 갈아엎었습니다:
이제 Claude는 가벼운 본문만 먼저 로드하고, 정말 필요할 때만 상세 리소스를 끌어옵니다. 토큰 효율이 대부분 쿼리에서 40~60% 향상됐습니다.
현재 스킬 라인업은 다음과 같습니다:
Guidelines & Best Practices:
backend-dev-guidelines - Routes → Controllers → Services → Repositoriesfrontend-dev-guidelines - React 19, MUI v7, TanStack Query/Router 패턴skill-developer - 스킬 제작용 메타 스킬Domain-Specific:
workflow-developer - 복잡한 워크플로우 엔진 패턴notification-developer - 이메일/알림 시스템database-verification - 컬럼명 오류 방지(수정을 실제로 차단하는 가드레일!)project-catalog-developer - DataGrid 레이아웃 시스템이 모든 스킬은 작업 맥락에 따라 자동 활성화됩니다. 마치 모든 패턴을 기억하는 시니어 개발자가 Claude 어깨 너머로 지켜보는 느낌입니다.
스킬 + 훅 이전:
스킬 + 훅 이후:
큰 코드베이스에서 확립된 패턴을 유지해야 한다면 강력 추천합니다. 초기 셋업에 이틀 정도 걸렸지만, 투자 대비 수익이 최소 열 배는 나왔습니다.
6개월 전 글에서 “룰이 최고의 친구”라고 했는데, 지금도 유효합니다. 다만 제 CLAUDE.md가 너무 비대해져 과하게 많은 일을 하려 했고, 1,400줄 넘는 BEST_PRACTICES.md도 Claude가 읽을 때가 있고 무시할 때가 있었죠.
그래서 오후 한때를 Claude와 함께 보내며 전면 통합/재구성했습니다. 바뀐 점은 다음과 같습니다:
기존 BEST_PRACTICES.md에는 다음이 들어 있었습니다:
이 모든 걸 스킬로 옮겼고, 자동 활성화 훅이 실제 사용을 보장합니다. “Claude가 BEST_PRACTICES.md를 봐주길 바라는” 일은 끝났습니다.
이제 CLAUDE.md는 프로젝트 고유 정보에만 집중합니다(약 200줄):
pnpm pm2:start, pnpm build, 등)Root CLAUDE.md (100 lines)
├── Critical universal rules
├── Points to repo-specific claude.md files
└── References skills for detailed guidelines
Each Repo's claude.md (50-100 lines)
├── Quick Start section pointing to:
│ ├── PROJECT_KNOWLEDGE.md - Architecture & integration
│ ├── TROUBLESHOOTING.md - Common issues
│ └── Auto-generated API docs
└── Repo-specific quirks and commands
요점: “코드를 어떻게 쓰는지”는 Skills가, “이 특정 프로젝트가 어떻게 동작하는지”는 CLAUDE.md가 담당합니다. 관심사의 분리, 승리.
스킬 다음으로 CC 결과에 가장 큰 영향을 준 시스템입니다. Claude는 “자신감 넘치는 기억상실증 주니어” 같아서 금방 맥락을 잃습니다. 이 시스템은 그런 약점을 보완합니다.
CLAUDE.md의 Dev Docs 섹션 발췌:
플랜 모드에서 승인된 플랜으로 나올 때:
작업 디렉터리 생성: mkdir -p ~/git/project/dev/active/[task-name]/
문서 생성:
[task-name]-plan.md - 승인된 플랜[task-name]-context.md - 핵심 파일/결정사항[task-name]-tasks.md - 작업 체크리스트/dev/active/에서 기존 작업 확인이 문서들은 모든 기능/대형 작업마다 항상 생성됩니다. 이 시스템을 쓰기 전에는, 어느 순간 Claude가 플롯을 잃고 30분 전 합의했던 구현에서 벗어나 산으로 가는 일이 잦았습니다.
저는 항상 기획부터 시작합니다. 플래닝이 왕입니다. 최소한 플래닝 모드로 계획을 세우지 않고 구현부터 시키면, 안 좋은 시간을 보내실 겁니다. 집에 증축을 하면서 도면도 안 그리고 바로 공사하진 않잖아요.
기능 계획을 시작하면 플래닝 모드로 둡니다. 어차피 나중에 Markdown으로 플랜을 쓰게 할 거지만요. 플래닝 모드가 필수인지는 모르겠지만, 제 체감으론 코드베이스 리서치와 맥락 수집이 더 잘 되어 좋은 플랜이 나옵니다.
저는 strategic-plan-architect 서브에이전트를 만들었고, 이건 플래닝 괴수입니다. 이 에이전트는:
다만 에이전트의 출력을 볼 수 없고, 플랜에 “아니오”라고 하면 그냥 종료되는 게 불편합니다. 그래서 메인 CC 인스턴스에서 같은 프롬프트를 쓰는 커스텀 슬래시 커맨드(/dev-docs)도 만들었습니다.
Claude가 그 아름다운 플랜을 뱉어내면, 저는 꼼꼼히 리뷰합니다. 이 단계가 정말 중요합니다. 이해하려고 시간을 들이면, 사소한 실수나 요청의 핵심을 오해한 부분을 놀랄 만큼 자주 잡아냅니다.
대개 플래닝 모드를 나오면 컨텍스트가 15% 미만으로 남습니다. 괜찮습니다. 필요한 건 전부 Dev Docs에 새로 담을 테니까요. Claude는 보통 바로 돌격하려 드니, 저는 즉시 ESC로 인터럽트하고 /create-dev-docs 슬래시 커맨드를 실행합니다. 이 커맨드는 승인된 플랜을 바탕으로 세 문서를 만들고, 컨텍스트가 남아 있으면 빈틈을 더 조사해 채웁니다.
이렇게 준비를 마치면, 오토 컴팩션이 걸려도 길을 잃지 않고 기능 전체를 구현시킬 수 있습니다. 중간중간 Claude에게 작업 체크리스트와 컨텍스트 파일을 갱신하라고 리마인드하고, 세션 컨텍스트가 줄어들면 /update-dev-docs를 실행합니다. Claude는 관련 컨텍스트와 다음 단계, 완료/신규 작업을 기록하고 저는 대화를 컴팩트합니다. 새 세션에서는 “계속”만 말하면 됩니다.
구현 동안 기능/작업 크기에 따라 한 번에 한두 섹션만 구현하게 합니다. 그 사이사이에 제가 코드를 리뷰할 시간을 갖기 위함이죠. 주기적으로 서브에이전트에게 변경분 리뷰도 맡겨 큰 실수를 초기에 잡습니다. Claude로 자기 코드 리뷰를 하지 않고 계시다면 강력히 권합니다. 심각한 오류, 누락, 불일치, 보안 이슈를 많이 조기에 잡아줬습니다.
최근에 추가했지만 백엔드 디버깅을 크게 바꿔준 요소입니다.
제 프로젝트는 백엔드 마이크로서비스가 7개 동시 구동됩니다. 문제는 서비스가 돌아가는 동안 Claude가 로그를 볼 수 없다는 점이었습니다. “이메일 서비스에 무슨 문제지?”라고 물어도, 제가 로그를 찾아서 복붙하지 않으면 Claude는 볼 수 없었죠.
한동안은 각 서비스가 타임스탬프 로그 파일에 쓰도록 devLog 스크립트를 붙였습니다. 그럭저럭 쓸 만했습니다. Claude가 로그 파일을 읽을 순 있었지만, 실시간이 아니고, 크래시 자동 재시작도 없고, 관리가 번거로웠죠.
그러다 PM2를 알게 되었고 게임 체인저였습니다. 모든 백엔드 서비스를 PM2로 묶어 단 한 줄로 실행하게 구성했습니다: pnpm pm2:start
얻은 것:
pm2 logs로 실시간 모니터링pm2 monit로 메모리/CPU 모니터링pm2 restart email, pm2 stop all 등)PM2 Configuration:
js// ecosystem.config.js module.exports = { apps: [ { name: 'form-service', script: 'npm', args: 'start', cwd: './form', error_file: './form/logs/error.log', out_file: './form/logs/out.log', }, // ... 6 more services ] };
예전(PM2 이전):
Me: "이메일 서비스에서 에러가 나" Me: [로그를 찾아 복사] Me: [채팅에 붙여넣기] Claude: "분석해볼게..."
지금(디버깅 워크플로우):
Me: "이메일 서비스에서 에러가 나" Claude: [실행] pm2 logs email --lines 200 Claude: [로그를 읽고] "원인 확인 - DB 연결 타임아웃..." Claude: [실행] pm2 restart email Claude: "서비스 재시작, 에러 모니터링 중..."
천지개벽급 차이. 이제 Claude가 인간 로그-배달원을 거치지 않고 자율 디버깅을 합니다.
단 하나의 주의점: 핫 리로드는 PM2와 잘 안 맞습니다. 그래서 프런트엔드는 여전히 pnpm dev로 따로 돌립니다. 하지만 자주 핫 리로드가 필요 없는 백엔드에는 PM2가 최고입니다.
이 프로젝트는 multi-root 구조이고 루트에 8개 정도의 레포가 있습니다. 프런트 1개, 백엔드 마이크로서비스/유틸 7개. 기능에 따라 레포 여러 곳을 오가며 수정합니다.
그리고 가장 미치겠던 건, Claude가 수정한 레포에서 빌드를 안 돌려 에러를 못 잡아두는 일이었습니다. 타입스크립트 에러가 수십 개 쌓이는데 제가 못 본 사이 지나가 버리는 거죠. 몇 시간 뒤 Claude가 착실히 빌드를 돌리고는 출력에 이렇게 쓰는 겁니다. “타입스크립트 에러가 몇 개 있지만 관련이 없으니 괜찮습니다!”
아니, 하나도 안 괜찮아, Claude야.
먼저 post-tool-use 훅을 만들어 Edit/Write/MultiEdit 이후마다 다음을 기록하게 했습니다:
처음엔 수정될 때마다 바로 빌드를 돌렸는데, 아주 비효율적이었습니다. Claude는 중간에 깨뜨리고 바로 고치는 편집을 자주 하거든요.
그래서 Stop 훅을 추가해 Claude의 응답이 끝날 때 동작하도록 했습니다. 이 훅은:
이후로 Claude가 에러를 남겨두는 일이 한 번도 없었습니다. 훅이 즉시 잡아내고, Claude가 바로 고친 뒤 다음으로 넘어갑니다.
단순하지만 강력합니다. Claude의 응답이 끝나면 해당 레포의 .prettierrc 설정으로 수정된 모든 파일을 자동 포맷합니다.
더는 파일을 수동으로 열었다 닫을 때 프리티어가 20군데를 고쳐놓는 사태가 없습니다. 지난주에 만든 파일에 트레일링 콤마를 빼먹는다든지 하는 일이 사라져요.
이건 앞서 말한 철학적 “젠틀 리마인더” 훅입니다:
예시 출력:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 ERROR HANDLING SELF-CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ Backend Changes Detected
2 file(s) edited
❓ Did you add Sentry.captureException() in catch blocks?
❓ Are Prisma operations wrapped in error handling?
💡 Backend Best Practice:
- All errors should be captured to Sentry
- Controllers should extend BaseController
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
이제 Claude의 매 응답마다 이렇게 흘러갑니다:
Claude가 응답 종료 ↓ Hook 1: Prettier 포맷터 실행 → 수정 파일 자동 포맷 ↓ Hook 2: 빌드 체커 실행 → TS 에러 즉시 포착 ↓ Hook 3: 에러 리마인더 → 에러 핸들링 셀프체크 ↓ 에러가 있으면 → Claude가 보고 즉시 수정 ↓ 에러가 너무 많으면 → Auto-error-resolver 에이전트 권고 ↓ 결과: 깔끔하고, 포맷됐고, 에러 없는 코드
그리고 UserPromptSubmit 훅이 작업 시작 “전”에 관련 스킬을 로드하게 만듭니다.
남기는 흔적: 0. 아름답습니다.
Anthropic의 공식 스킬 예제에서 배운 아주 멋진 패턴: 유틸리티 스크립트를 스킬에 붙여라.
예를 들어 제 backend-dev-guidelines 스킬에는 인증 라우트 테스트 섹션이 있습니다. 단순 설명 대신 실제 스크립트를 참조하죠:
제공된 test-auth-route.js 스크립트를 사용하세요:
node scripts/test-auth-route.js http://localhost:3002/api/endpoint
이 스크립트가 복잡한 인증 단계를 모두 수행합니다:
Claude가 라우트를 테스트해야 할 때, 어떤 스크립트를 어떻게 써야 하는지 정확히 압니다. 더는 “테스트 스크립트를 만들어볼게요” 하며 매번 바퀴를 재발명하지 않습니다.
이 패턴을 확장할 계획입니다. 더 많은 유틸 스크립트를 관련 스킬에 붙여, Claude가 매번 새로 만들지 않고 곧장 써먹게요.
타자가 지칠 때 음성으로 프롬프트를 입력합니다. 의외로 잘 되고, 제 중얼거림도 Claude가 꽤 잘 이해합니다.
스킬이 “패턴 기억”을 대부분 대신하면서 사용 빈도는 줄었습니다. 그래도 스킬에 적합하지 않은 프로젝트별 결정/아키텍처 선택을 추적하는 데 유용합니다.
앱 사이를 덜 더듬거리는 시간 절약만으로도 BTT 값어치가 충분합니다.
귀찮고 반복적인 일이라면 대개 스크립트가 있습니다:
프로 팁: Claude가 유용한 스크립트 작성을 도와줬다면, 즉시 CLAUDE.md에 문서화하거나 관련 스킬에 첨부하세요. 미래의 내가 과거의 나에게 절합니다.
플래닝 다음으로 문서화가 중요하다고 생각합니다. 각 기능의 Dev Docs 외에도, 시스템 아키텍처, 데이터 흐름 다이어그램, 개발자 문서와 API 등 웬만한 건 다 문서화합니다.
달라진 점: 이제 문서화는 스킬을 “대체”하는 게 아니라 스킬과 함께 작동합니다.
Skills에는: 재사용 가능한 패턴, 베스트 프랙티스, 사용 가이드 Documentation에는: 시스템 아키텍처, 데이터 플로우, API 레퍼런스, 통합 지점
예를 들어:
문서는 여전히 많습니다(마크다운 850+ 파일). 하지만 이제 프로젝트 고유 아키텍처에 레이저 포커스되어 있고, 일반 베스트 프랙티스는 스킬에 맡깁니다.
여러분이 꼭 이렇게까지 하라는 건 아니지만, 문서에 계층을 두길 권합니다. 서비스별 광범위한 아키텍처 오버뷰가 있고, 더 자세한 내용은 하위 문서로 연결하는 방식으로요. Claude가 코드베이스를 탐색하는 능력이 확 좋아집니다.
프롬프트를 쓸 때, 원하는 결과를 구체적으로 적으세요. 다시 말하지만, 욕실 증축을 아무 계획 없이 “알아서 해 주세요”라고 시키진 않잖아요.
“맞아요! 욕실에 샤그 카펫은 별로죠.”
가끔은 구체를 모를 수 있습니다. 괜찮아요. 모르면 질문하세요. 또는 Claude에게 리서치 후 여러 대안을 가져오게 하세요. 전문 서브에이전트를 쓰거나 다른 AI 챗을 병행해도 됩니다. 세상은 당신의 굴. 이 과정이 반드시 보답합니다. Claude가 제시한 플랜을 보고 좋고 나쁨, 수정 지점을 훨씬 잘 판단하게 되거든요. 그렇지 않으면 감만 믿는 바이브 코딩이 되고, 무엇을 포함해야 할 컨텍스트인지조차 모르는 상태로 파일을 헤매게 됩니다.
리딩 질문을 피하세요. 솔직하고 편향 없는 피드백을 원하면요. Claude가 한 작업이 확신이 안 간다면 “좋아요? 나빠요?” 같은 질문 대신 상황을 중립적으로 설명하고 의견/대안을 요청하세요. Claude는 여러분이 듣고 싶어할 말을 하려는 성향이 있어, 유도 질문은 답을 왜곡합니다. 중립적으로 묘사하고 생각을 물으면 더 균형 잡힌 답을 받습니다.
저는 특화 에이전트 소대를 꾸렸습니다:
Quality Control:
code-architecture-reviewer - 베스트 프랙티스 준수 관점의 코드 리뷰build-error-resolver - 타입스크립트 에러 체계적 해결refactor-planner - 포괄적 리팩터 플랜 수립Testing & Debugging:
auth-route-tester - 인증 필요한 백엔드 라우트 테스트auth-route-debugger - 401/403 및 라우트 이슈 디버깅frontend-error-fixer - 프런트엔드 에러 진단/수정Planning & Strategy:
strategic-plan-architect - 상세 구현 플랜 작성plan-reviewer - 구현 전 플랜 리뷰documentation-architect - 문서 생성/업데이트Specialized:
frontend-ux-designer - 스타일/UX 이슈 개선web-research-specialist - 웹 리서치 전반 지원reactour-walkthrough-designer - UI 투어 제작핵심은 역할을 매우 구체적으로 정의하고, 무엇을 반환해야 하는지 명확히 지시하는 것입니다. 이 교훈은 “뭘 했는지도 말 안 하고 ‘고쳤어요!’만 외치고 사라지는” 에이전트를 만들며 뼈저리게 배웠습니다.
훅 시스템은 모든 것을 묶는 본드입니다. 훅이 없으면:
훅이 있으면:
커스텀 슬래시 커맨드가 꽤 많지만, 가장 많이 쓰는 건 이렇습니다:
Planning & Docs:
/dev-docs - 종합 전략 플랜 생성/dev-docs-update - 컴팩션 전 Dev Docs 갱신/create-dev-docs - 승인된 플랜을 Dev Doc 파일로 변환Quality & Review:
/code-review - 아키텍처 관점 코드 리뷰/build-and-fix - 빌드 실행 후 모든 에러 수정Testing:
/route-research-for-testing - 영향 라우트 탐색 및 테스트 기동/test-route - 특정 인증 라우트 테스트슬래시 커맨드는 입력 시 전체 프롬프트로 확장되므로, 방대한 컨텍스트/지시를 간단한 커맨드 하나에 담을 수 있습니다. 매번 같은 지시를 타이핑하는 것보다 훨씬 낫죠.
6개월 하드코어 사용을 통해 배운 핵심은 다음과 같습니다:
필수 요소:
있으면 좋은 것:
지금은 이 정도가 생각납니다. 다시 말하지만, 저는 그냥 한 사람일 뿐이고, 여러분의 팁/트릭/비판을 환영합니다. 워크플로우는 언제든 더 나아질 수 있으니까요. IRL에서 이걸 공유할 사람이 거의 없어서(우리 팀은 작고, AI 탑승 속도가 느립니다) 이렇게라도 공유하고 싶었습니다.
여기까지 읽으셨다면 감사합니다. 구현 세부나 더 궁금한 점이 있다면 얼마든지 물어보세요. 특히 훅과 스킬 시스템은 시행착오가 꽤 있었지만, 일단 돌아가니 이전으로는 못 돌아가겠습니다.
TL;DR: TypeScript 훅으로 Claude Code 스킬 자동 활성화 시스템을 만들고, 컨텍스트 유실을 막는 Dev Docs 워크플로우와 PM2 + 자동 에러 점검을 도입했다. 결과: 6개월 만에 혼자 30만 LOC를 일관된 품질로 리라이트.