실전 가이드 · 4분 · 05.29

Claude Code를 '터미널 챗봇'처럼 쓰고 있었다면 — HN 424점 가이드의 5층 워크플로

loopy vibecoder

#draft #Claude-Code #CLAUDE-md #Skills #Subagents #MCP #워크플로 #Arpan-Patel #HN #가이드

핵심 요약 (TL;DR)

Hacker News 5/27 시점 424점·249댓글을 받은 Arpan Patel의 가이드 Beyond the Prompt는 Claude Code를 "터미널 챗봇"이 아닌 "설정 가능한 팀메이트"로 다루는 5층 워크플로를 제안합니다. CLAUDE.md, CLAUDE.local.md, Skills, Subagents, MCPs — 이 다섯 층을 깔면 같은 프롬프트도 결과 천장이 달라집니다. 저자는 "PR 니트픽 코멘트가 몇 주 만에 눈에 띄게 줄었다"고 보고했어요.

"왜 같은 실수를 매번 반복하지?"

Claude Code를 한 달 정도 써본 분이라면 한 번쯤 이런 순간이 있으셨을 거예요. 어제 분명히 고친 스타일 가이드를 오늘 또 어기는 출력, 프로젝트 컨벤션과 안 맞는 import 순서, 똑같이 까먹는 테스트 패턴. 매번 채팅창에 다시 적기엔 손이 아프고, 안 적자니 또 나오죠.

Arpan Patel의 가이드는 이 문제의 본질을 한 문장으로 정리합니다. "Claude Code clicked for me only after I stopped treating it like ChatGPT in a terminal." (Claude Code는 내가 그것을 터미널 챗봇처럼 다루기를 멈춘 순간 작동하기 시작했다.)

챗봇은 매 대화가 무(無)에서 시작합니다. 팀메이트는 컨텍스트와 룰북을 가지고 일합니다. 둘의 차이를 만드는 건 다섯 개의 층이에요.

5층 워크플로 — 한 층씩 깔아두는 인프라

1층. CLAUDE.md — 프로젝트 룰북

프로젝트 루트에 두는 단일 룰 파일입니다. 패키지 매니저, 빌드 명령, 코딩 컨벤션, 디렉터리 구조, "절대 하지 말 것" 같은 강제 규칙을 한 곳에 모아둡니다. 팀 전체가 공유하는 룰이 들어가요.

# 프로젝트 룰

- 패키지 매니저: pnpm (npm·yarn 사용 금지)
- 새 파일을 만들기 전에 기존 파일을 수정할 수 있는지 먼저 검토
- 커밋 메시지는 Conventional Commits 형식

2층. CLAUDE.local.md — 내가 나에게 주는 피드백 누적

핵심은 여기예요. CLAUDE.local.md는 git에 안 올라가는 개인 룰북입니다. PR 리뷰에서 같은 지적을 두 번 받았다? 그걸 그대로 룰로 옮겨 적습니다. 다음번부터 Claude가 그 실수를 안 합니다. Patel 본인은 이 한 층을 도입한 뒤 "PR 니트픽 코멘트가 몇 주 만에 눈에 띄게 줄었다"고 적었어요. 구체적 팀 규모나 수치는 명시되지 않았지만, 같은 실수의 재발 빈도를 인프라로 누른다는 접근이 핵심입니다.

3층. Skills — 재사용 가능한 절차

자주 하는 작업의 절차를 Skill로 떼어내 두면 매번 같은 프롬프트를 새로 짤 필요가 없습니다. "DB 마이그레이션 생성", "API 엔드포인트 추가" 같은 워크플로를 한 번 정리해두면, 이름만 호출해서 굴립니다.

4층. Subagents — 병렬로 갈라지는 작업

큰 작업을 sub-agent에게 위임해서 병렬로 굴립니다. 리포지토리 전체 검색, 여러 파일 동시 분석 같은 작업이 메인 에이전트의 컨텍스트를 오염시키지 않고 따로 끝납니다.

5층. MCPs — 외부 도구와의 연결

Obsidian, GitHub, Linear, Sentry, Playwright, Figma 같은 외부 시스템을 MCP로 붙입니다. Claude가 노트, 이슈, 디자인 파일에 직접 접근하면 "맥락을 사람이 복붙해 넣는" 단계가 통째로 사라집니다.

한국 개발자가 오늘 깔아볼 단계

다섯 층을 한 번에 다 깔 필요는 없습니다. 순서대로 추천해드리면 이렇습니다.

CLAUDE.md 한 줄부터 시작. 패키지 매니저와 빌드 명령만 적어도 충분합니다. 굳이 처음부터 길게 안 써도 돼요.
CLAUDE.local.md를 PR 피드백 저장소로 운영. 코드리뷰에서 같은 지적을 두 번 받은 순간 거기에 한 줄 추가하는 습관.
자주 하는 절차 한두 개를 Skill로 떼어내기.
Subagents·MCPs는 위 세 층이 익숙해진 다음에 도입해도 늦지 않습니다.

핵심 메시지를 다시 한 줄로 옮기면 이렇습니다. 워크플로 인프라가 프롬프트 quality보다 결과의 천장을 결정합니다. 더 좋은 프롬프트를 짜는 데 시간을 쓰는 것보다, 룰북 한 줄을 적어두는 데 쓰는 시간이 장기적으론 훨씬 큰 레버리지예요.

자주 묻는 질문 (FAQ)

Q. CLAUDE.md와 CLAUDE.local.md를 굳이 나눠야 하나요?
공유 룰과 개인 룰을 섞으면 다른 팀원이 본인과 무관한 규칙까지 끌어안게 됩니다. CLAUDE.md는 git에 올리는 팀 룰, CLAUDE.local.md는 .gitignore에 추가하는 개인 룰. 이 분리 자체가 핵심입니다.

Q. 코드베이스가 작은데도 5층을 다 깔 가치가 있나요?
1층(CLAUDE.md)과 2층(CLAUDE.local.md)은 코드베이스 크기와 관계없이 효과가 즉시 나옵니다. 3~5층은 작업 규모가 커지거나 외부 도구 연동이 필요해진 시점에 자연스럽게 도입하시면 됩니다.

Q. Skills와 Subagents는 정확히 뭐가 다른가요?
Skills는 "내가 이 절차를 어떻게 진행하기로 약속한다"는 절차서. Subagents는 "이 작업을 별도 컨텍스트에서 굴려달라"는 실행 단위. 절차의 정의(Skills)와 실행의 분기(Subagents)는 층이 다릅니다.

마지막 한 마디

Patel의 가이드가 5/27 HN 상위권에 오른 건 새로운 기능을 발견했기 때문이 아니라, 이미 있던 기능의 사용법을 인프라로 묶어 보여줬기 때문이에요. 한 달 전 Daniel Carwright의 Cursor 워크플로 가이드가 같은 결로 viral이 됐던 흐름과 정확히 닿아 있습니다. "Claude Code 베스트 프랙티스" 합의가 굳어지는 중이고, 한국 개발자가 이 흐름에 합류하는 가장 빠른 방법은 오늘 저녁 CLAUDE.md 한 줄을 적는 일입니다. 그 한 줄이 내일 PR 코멘트 하나를 줄입니다.