바이브코딩 입문

무엇인가

코드를 직접 치는 대신 AI 에이전트에게 말로 시키고, 사람은 방향과 검수를 맡는 개발 방식이다. 손으로 짜던 때와 가장 크게 다른 점은 일의 단위다. 한 줄이 아니라, 지시 한 번과 검증 한 번이 단위가 된다.

잘 쓰는 사람과 못 쓰는 사람의 차이는 프롬프트 문장력보다 AI가 세션마다 읽는 설정에서 난다. 규칙, 도구, 역할을 얼마나 잘 깔아 두었느냐다.

이 문서는 그 설정 전체를 한 장으로 묶은 지도다. 각 부품은 플레이북에 따로 깊게 적어 두었고, 여기서는 무엇이 어디에 있는지와 처음 시작할 때 알아야 할 것만 적는다. 도구는 Claude Code 기준이지만 Codex·Cursor 같은 다른 도구도 이름만 다르고 구조는 같다.

세 부품과 그 바닥

한눈에

에이전트는 누가 일하나, 스킬은 어떻게 하나, MCP는 어디에 손이 닿나
셋을 받치는 바닥이 하네스다. CLAUDE.md(규칙) · 훅(강제) · 권한(허용 범위) · 메모리(교훈)
문서는 부탁이고 훅은 강제다

부품	한 줄	자세히
에이전트	파일을 읽고 명령을 실행하고 결과를 보고 다시 고치는 루프를 알아서 도는 AI	멀티 에이전트플레이북멀티 에이전트역할별로 쪼개 격리된 채로 병렬로 굴린다.
스킬	평소엔 설명 한 줄만 올라가 있다가 관련된 일이 오면 본문을 여는 설명서	규칙 자동 주입플레이북규칙 자동 주입한 번 정한 규칙이 매번 지켜지게 만드는 법., 슬래시 커맨드플레이북슬래시 커맨드 만들기매번 설명하던 것을 명령 하나로 굳힌다.
MCP	에이전트에 외부 시스템을 꽂는 표준 규격	MCP플레이북MCP프롬프트로 못 미치는 자리에 도구를 붙인다.
CLAUDE.md	세션이 열릴 때마다 자동으로 읽히는 프로젝트 규칙 파일	AI 하네스플레이북AI 하네스Claude Code를 무인으로 부리려고 짠 협업 하네스.
훅	정해진 순간에 도구가 알아서 부르는 스크립트. AI 판단이 아니라 코드가 막는다	훅플레이북훅(Hook)부탁으로는 안 지켜지는 것을 실행 직전에 기계로 막는다.
메모리	세션을 넘어 남기는 교훈과 선호	파일 메모리플레이북파일 메모리세션이 끝나도 남는 기억을 파일로 둔다.

이 바닥 전체를 하네스라고 부른다. 말에 채우는 마구처럼, 모델이라는 힘을 원하는 방향으로 쓰게 하는 장치다. 같은 모델도 하네스에 따라 결과가 크게 달라진다. 모델은 그대로 두고 하네스만 바꿔 점수를 40에서 100으로 올린 연구가 있고(arXiv 2610.02200), 하네스 부품을 176가지 조합으로 바꿔 본 연구에서는 이득 대부분이 컨텍스트 넘침을 막는 데서 나왔다(arXiv 2609.20804).

에이전트가 도는 방식

세션 시작

어느 폴더에서 여느냐가 중요하다

CLAUDE.md 자동 로드

작업 폴더에서 위로 올라가며 찾는다

요청

말로 시킨다

읽기 → 계획 → 도구 실행 → 결과 확인

끝날 때까지 반복. 크면 서브에이전트에게 위임

완료 보고

무엇을 어떻게 했는지

CLAUDE.md는 위로만 자동 로드된다. 작업 폴더에서 상위 폴더로 올라가며 찾은 파일을 읽고, 하위 폴더의 것은 그 폴더 파일을 열 때 들어온다. 모노레포 루트에서 세션을 열면 하위 프로젝트 규칙이 처음부터 없다. 그래서 이 저장소는 루트 CLAUDE.md 맨 위에 "대상 프로젝트를 정하고 그 CLAUDE.md를 직접 읽어라"를 시작 절차로 둔다.
서브에이전트는 별도 컨텍스트에서 일하고 요약만 돌려준다. 메인 대화가 파일 덤프로 차지 않고, 여러 개를 동시에 돌릴 수 있다.
서브에이전트는 CLAUDE.md를 물려받지만, 지킨다는 보장은 없다. 반드시 지켜야 할 것은 일을 맡길 때 다시 적어 준다. 내장 Explore·Plan은 물려받지 않는다.

Claude Code에는 처음부터 들어 있는 에이전트가 있다. 버전에 따라 목록은 조금 다를 수 있다.

내장 에이전트	하는 일
general-purpose	범용. 여러 단계가 필요한 조사·검색·작업
Explore	읽기 전용 탐색. 여러 파일을 훑고 결론만 돌려준다
Plan	구현 계획. 파일은 고치지 않고 단계와 핵심 파일을 내놓는다
claude-code-guide	Claude Code 사용법 질문에 답한다
statusline-setup	하단 상태줄 설정

에이전트를 직접 만들 때

에이전트는 마크다운 파일 하나다. 프로젝트의 .claude/agents/<이름>.md에 두면 그 프로젝트에서, ~/.claude/agents/에 두면 어디서나 쓴다. /agents로 대화형으로 만들 수도 있다.

---
name: test-runner
description: 구현한 것이 실제로 도는지 검증한다. 빌드·타입·린트를 돌리고,
  무엇이 검증됐고 무엇이 안 됐는지 구분해 보고한다. 구현 후, 배포 전에 쓴다.
model: sonnet
skills:
  - repo-guards
memory: project
---

너는 검증 담당이다. "돌려봤다"와 "검증됐다"는 다르다.
먼저 프로젝트 CLAUDE.md에서 빌드 명령을 확인한다. ...

항목	의미	걸리기 쉬운 자리
`description`	언제 부를지 정하는 유일한 단서	"언제" 쓰는지와 예시 요청을 적는다
`model`	쓸 모델	판단이 필요하면 큰 모델, 절차대로면 작은 모델
`tools`	쓸 수 있는 도구 제한	리뷰어는 읽기 전용으로 두면 안전하다
`skills`	시작할 때 주입할 스킬 본문	없는 이름을 적으면 경고만 남고 조용히 건너뛴다
`memory`	에이전트별 교훈 저장	반복해서 틀리는 것을 그 에이전트 몫으로 쌓는다

정의에는 기술 스택을 박지 않는다. 한때 정의 여덟 개가 전부 "React + Vite"만 알아서, 프로젝트 21개 중 5개에만 맞았다. 스택은 프로젝트마다 다르니 CLAUDE.md에서 읽게 한다.

만드는 기준은 "같은 설명을 세 번째 하게 될 때"다. 한 번 하고 끝날 일이거나 기존 에이전트에 한 줄 더하면 되는 일은 만들지 않는다. 지금 쓰는 일곱 역할의 구성과 병렬로 띄우는 기준은 멀티 에이전트플레이북멀티 에이전트역할별로 쪼개 격리된 채로 병렬로 굴린다.에 있다.

스킬과 MCP 고르기

처음이라면 아래 스킬부터 써 보면 된다.

스킬	도움되는 일
`/init`	저장소를 훑고 CLAUDE.md 초안을 만든다. 처음 시작할 때
`/code-review`	현재 변경분의 버그 리뷰
`/simplify`	중복·과잉 코드 정리. 버그는 보지 않고 품질만
`/security-review`	변경분의 보안 점검
`/run`	앱을 실제로 띄워 변경이 도는지 확인
pdf · docx · xlsx · pptx	문서 파일 읽기·만들기

내 스킬은 .claude/skills/<이름>/SKILL.md 하나면 된다. 쓸모가 컸던 것은 두 종류다. "예쁘게" 대신 여백과 글자 비율을 수치로 적은 판단 기준형, 그리고 저장소에 이미 있는 스크립트와 쓰는 법을 적은 스크립트 목록형이다. 스크립트는 코드가 컨텍스트에 들어가지 않고 출력만 토큰을 쓴다.

MCP는 흔히 이런 유형으로 꽂는다.

유형	예	에이전트가 할 수 있게 되는 일
라이브러리 문서	Context7플레이북context7기억으로 API를 짜지 않고, 문서를 읽고 짠다.	최신 공식 문서를 보고 짠다
브라우저	Playwright플레이북Playwright MCP코드만 읽으면 틀린다. 띄워서 눈으로 본다.	화면을 띄워 클릭·입력하고 콘솔 에러를 본다
코드·이슈	GitHub, GitLab, Jira	이슈를 읽고 PR과 댓글까지 처리한다
데이터베이스	PostgreSQL 등	스키마를 보고 쿼리를 짜서 확인한다
문서 검색	사내 위키, RAG 검색 서버	디스크에 없는 문서를 찾아 근거로 쓴다
디자인	Figma	시안을 읽고 그대로 구현한다

꽂을 때는 세 가지를 지킨다. 적게 꽂는다. 서버마다 도구 목록이 컨텍스트를 먹고, 도구가 많을수록 고르다 틀린다. 읽기 전용부터 연다. 쓰기 권한은 나중에 준다. 언제 쓸지 CLAUDE.md에 적는다. 모델은 습관처럼 grep부터 쓴다. 문서 검색 MCP를 꽂아 두고도 "이 저장소에는 없습니다"로 끝난 일이 두 번 있었고, 도구 설명을 두 번 고쳐도 안 바뀌다가 CLAUDE.md에 적은 뒤에야 바뀌었다.

폐쇄망에서 하네스가 더 중요한 이유

폐쇄망에서는 모델이 우리 환경을 모르는데 인터넷으로 찾아볼 수도 없다. 하네스가 대신 쥐어 주지 않으면 공개 인터넷 관행대로 짜고, 없는 명령을 지어낸다.

문제	안 막으면	하네스 처방
규격	사내 프레임워크와 공통 모듈을 본 적이 없어 공개 관행대로 짜거나 새로 만든다	CLAUDE.md에 규격 요약과 따라 할 예시 파일 경로. 규격 문서는 스킬로
저장소 명령어	사내 빌드 스크립트 대신 `npm install`, `pip install`로 인터넷에서 받으려 한다	정확한 명령을 CLAUDE.md에. 외부 설치 명령은 권한에서 막는다
훅	"하지 마라"라고 적어도 언젠가 한다. 사람이 매번 지켜볼 수 없다	실행 직전 훅으로 파괴 명령 차단, 커밋 훅으로 규격·비밀키 검사
문서 검색	인터넷 문서 MCP를 못 쓴다	자주 보는 문서는 저장소 안 마크다운으로. 가능하면 사내 문서 검색을 MCP로
모델 성능	사내에 설치할 수 있는 모델은 대체로 최신 클라우드 모델보다 약하다	계획 단계와 완료 기준(테스트)을 꼭 둔다

마지막 줄은 근거가 있다. 위의 176가지 조합 연구에서 계획 단계는 약한 모델에게 정확도를 받쳐 주었고, 강한 모델에게는 비용을 줄여 주는 쪽으로 성격이 바뀌었다.

여러 세션을 동시에

세션을 여러 개 열어 두면 한 창은 구현, 한 창은 조사, 한 창은 문서를 맡길 수 있다. 에이전트가 일하는 동안 기다리지 않고, 작업마다 컨텍스트가 따로라 대화가 섞이지 않는다. 대신 같은 저장소를 여러 세션이 함께 만지므로 규칙이 필요하다.

git add -A를 쓰지 않는다. 다른 세션이 고치던 파일까지 내 커밋에 딸려 들어간다. 내가 고친 파일만 경로를 지정해 올린다.
파괴적 git 차단 훅이 여기서 가장 쓸모 있다. 한 세션의 reset --hard가 다른 세션의 미커밋 작업을 통째로 날린다.
같은 파일은 동시에 고치지 않는다. 꼭 겹치면 git worktree로 작업 폴더를 따로 뗀다.

반복 작업은 대화 없이 돌린다. claude -p "지시"는 한 번 실행하고 끝나므로 스케줄러에 걸 수 있다. 이 저장소는 매일 아침 기술 동향 정리, 오전 검색 품질 평가, 밤 개발일지를 이렇게 돌린다.

배운 것

문서는 부탁이고, 훅은 강제다. 규칙 여섯 개를 적어 두고 하루에 여섯 개를 다 어긴 날이 있었다. 절대 깨면 안 되는 것은 문서가 아니라 훅과 권한에 둔다.
규칙에는 이유와 사고를 같이 적는다. "차트 라이브러리를 확인하지 않고 SVG를 347줄 손코딩한 적이 있다"처럼 이유가 붙은 규칙을 모델이 훨씬 잘 지킨다.
같은 실수가 두 번 나면 대화가 아니라 설정을 고친다. 대화에서 꾸짖은 것은 다음 세션에 남지 않는다. 메모리, CLAUDE.md, 훅 중 하나에 한 줄을 남긴다.
완료 보고를 그대로 믿지 않는다. 검토하라고 준 파일을 다 읽지 않은 실행이 67.9%였고, 그중 80.4%는 다 읽었다고 보고했다는 측정이 있다(arXiv 2609.20812). diff는 사람이 읽는다.