요즘 "바이브 코딩"이라는 말을 많이 쓰죠. 대충 만들고 싶은 걸 말하면 AI가 코드를 짜주는 방식처럼 들립니다. 저도 처음엔 "이 기능 만들어줘", "이 버그 고쳐줘", "이 UI 예쁘게 바꿔줘" 이런 식으로 썼습니다. 그런데 프로젝트 코드가 커지기 시작하면 이 방식은 금방 한계가 오더라고요.
AI는 빠르게 코드를 쓰는데, 맥락을 잃으면 더 빠르게 이상한 코드를 씁니다. 이미 있는 구조를 무시하고 새 추상화를 만들거나, 문서엔 완료라고 적어두고 실제 검증은 안 하거나, 테스트가 깨져 있는데 겉보기만 그럴듯하게 마무리하거나요.
그래서 요즘은 AI가 일할 수 있는 개발 환경부터 만듭니다.
문서 구조
-> 작업 라우팅
-> 스킬 하네스
-> 작은 구현 단위
-> 검증 루프
-> 리뷰와 푸시
저한테 바이브 코딩은 이 흐름 전체를 운영하는 일에 가까운 것 같아요.
1. 레포가 스스로 설명하게 만든다
AI한테 긴 설명을 매번 붙여넣는 건 오래 못 갑니다. 그래서 큰 레포엔 에이전트가 처음 읽어야 하는 문서를 정해둡니다.
docs/README.md
docs/contributing/roadmap.md
docs/contributing/feature-registry.md
docs/architecture/
docs/agents/
docs/testing/
이 문서들은 "프로젝트 소개"라기보다 라우터에 가까운 것 같아요. 지금 건드리는 기능이 web인지 api인지 worker인지 db인지 먼저 나누고, 그다음 어떤 규칙을 따라야 하는지 알려주는 거죠.
큰 웹서비스 레포라면 이런 식으로 경계를 둡니다.
apps/web - Next.js UI
apps/api - API server
apps/worker - background worker
packages/db - database schema
packages/llm - LLM provider abstraction
packages/shared - shared contracts
이걸 문서로 고정해두면 AI가 "그럴듯한 새 구조"를 만들 가능성이 줄어듭니다. 프론트에서 DB를 바로 import하지 말라거나, user-facing copy는 i18n 파일에 넣으라거나, worker의 긴 작업은 Temporal로 돌리라는 규칙을 매번 말 안 해도 되고요.
바이브 코딩을 잘하려면 프롬프트가 아니라 레포의 기본 문맥이 먼저 좋아야 하는 것 같아요.
2. 공개 문서와 개인 운영 문서를 나눈다
저는 문서를 두 층으로 나눕니다.
공개 저장소에 들어가는 건 제품이랑 기여자가 봐도 되는 안정적인 내용.
반대로 현재 개발 상태, 실패한 시도, 다음 세션 프롬프트, 감사 메모, 리뷰 대응 기록 같은 건 개인 운영 문서에 둡니다.
.private-docs/
docs/superpowers/
공개 문서는 깔끔해야 하는데, AI 에이전트가 일을 잘하려면 지저분한 작업 맥락도 필요한 것 같아요. 어떤 브랜치에서 어디까지 했는지, 어떤 테스트가 실제로 통과했는지, 어떤 계획은 버렸는지 같은 것들이고요.
그걸 전부 README에 넣으면 공개 문서가 망가지고, 아예 안 남기면 다음 세션에서 같은 실수를 반복합니다.
그래서 "제품 문서"랑 "운영 문서"를 분리하고, AI한테도 공개 문서에 넣을 말이랑 maintainer context에만 남길 말을 구분하게 하죠.
3. 스킬 하네스로 작업 방식을 고정한다
요즘 제일 많이 쓰는 게 스킬 하네스입니다.
스킬은 한마디로 "특정 상황에서 AI가 따라야 하는 작은 운영 매뉴얼"입니다. 매번 장문의 지시를 쓰는 대신 작업 종류별로 규칙을 파일로 만들어두고요.
저는 이런 스킬을 둡니다.
project-rules
post-feature
parallel-sessions
next-plan
commit-rules
project-rules는 코드베이스 규칙을 잡아줍니다. post-feature는 기능을 끝냈다고 말하기 전에 문서, 테스트, diff, 상태 기록을 확인하게 만들고요. parallel-sessions는 여러 에이전트를 병렬로 돌릴 때 worktree랑 파일 소유권을 어떻게 나눌지 정리하고요.
여기에 Superpowers 플러그인 스킬도 같이 씁니다.
writing-plans
test-driven-development
systematic-debugging
verification-before-completion
requesting-code-review
receiving-code-review
using-git-worktrees
"AI야 잘해줘"라고 맡기기보다 "이 상황에선 이 절차를 따라"라고 정해두는 편이 결과가 더 안정적이더라고요.
AI 코딩에서 품질은 모델 성능만으로 안 나옵니다. 같은 모델이라도 어떤 루틴 안에 넣느냐에 따라 결과가 완전히 달라지기 때문이죠.
4. 작업은 작은 slice로 자른다
AI한테 "이 프로젝트 완성해줘"라고 한꺼번에 맡기지 않고 이렇게 자릅니다.
목표: 에이전트가 노트 업데이트를 제안하게 만들기
1. DB에 agent_actions ledger 추가
2. API에 preview/apply endpoint 추가
3. web에 검토 UI 추가
4. worker에서 action payload 생성
5. 테스트와 smoke 확인
그리고 각 slice마다 소유 파일을 정하고요.
packages/db/src/schema/agent-actions.ts
apps/api/src/routes/agent-actions.ts
apps/web/src/features/agent-actions/
apps/worker/src/worker/agents/
이렇게 해야 병렬 작업이 됩니다. 한 세션은 DB/API, 다른 세션은 web UI, 또 다른 세션은 worker agent를 맡는 식이고요. 해보니까 속도를 가르는 건 코드 생성 시간보다 작업을 충돌 없이 나누는 방식이더라고요.
5. 구현보다 검증 루프가 더 중요하다
AI 코딩에서 제일 위험한 말은 "완료했습니다"입니다.
그래서 완료 전에 반드시 검증 루프를 넣죠.
변경 파일 확인
-> 타입 체크 또는 테스트
-> 빌드
-> 필요한 경우 브라우저 smoke
-> git diff 리뷰
-> 문서 상태 갱신
-> commit / push
모든 작업에 풀 테스트를 돌릴 필요는 없습니다. 대신 바뀐 범위에 맞는 제일 좁은 검증을 고릅니다.
copy만 바꿨으면 i18n parity랑 web build를 봅니다. API permission을 건드렸으면 route test랑 security test를 보고요. worker ingest를 건드렸으면 activity 단위 테스트랑 payload contract를 보고요.
핵심은 "검증했다"는 말을 결과 없이 믿지 않는 겁니다.
AI한테도 이렇게 시키죠.
성공했다고 말하기 전에 실제 명령을 실행하고,
실패하면 실패한 명령과 원인을 기록하고,
통과한 범위와 아직 검증하지 못한 범위를 분리해서 말해라.
이 루프가 없으면 바이브 코딩은 그냥 빠른 기술 부채 생성기가 됩니다.
6. 프롬프트는 짧아지고, 환경은 길어진다
레포 안의 문맥이 쌓이면서 제 프롬프트는 오히려 짧아지더라고요. 예전엔 설명을 길게 썼기 때문이죠.
이 프로젝트는 이런 구조고, 이런 규칙이 있고, 이 기능은 이렇게 해야 하고...
요즘은 이렇게 말해도 됩니다.
현재 구현 상태 읽고 다음 slice 진행해줘.
아니면
이 PR 리뷰 보고 필요한 것만 반영하고 푸시해줘.
이렇게 짧게 말할 수 있는 건 레포 안에 AI가 읽을 문서, 스킬, 계획, 검증 규칙이 쌓여 있어서입니다. 제가 겪은 바이브 코딩은 순간적인 채팅 기술보다 운영체제에 가까웠던 것 같아요.
사용자는 목표를 짧게 던지고, 에이전트는 레포 안의 문맥을 읽고, 스킬에 맞춰 실행하고, 검증 결과를 남기는 거죠.
7. 제가 생각하는 다음 단계
이 흐름을 더 일반화하면 저는 solo-devflow-os 같은 형태가 될 수 있다고 생각합니다.
1인 개발자가 AI 에이전트를 쓰려고 매번 같은 세팅을 반복하지 않도록, 문서 구조랑 스킬 하네스, worktree 운영, 검증 루프, PR 루틴을 하나의 템플릿으로 묶는 거죠.
대충 이런 구성이고요.
AGENTS.md
docs/README.md
docs/contributing/roadmap.md
docs/contributing/feature-registry.md
docs/testing/
docs/superpowers/plans/
.private-docs/
skills/
scripts/verify/
이 방식은 특정 모델이나 IDE에 안 묶입니다. Codex든 Claude Code든 Cursor든, AI가 읽고 검증할 수 있는 작업장을 먼저 갖추는 게 핵심입니다.
정리
제가 요즘 쓰는 방식은 이렇죠.
1. 레포가 스스로 설명하게 만든다
2. 공개 문서와 개인 운영 문서를 나눈다
3. 작업별 스킬 하네스를 둔다
4. 기능을 작은 slice로 자른다
5. 완료 전 검증 루프를 강제한다
6. 결과를 문서와 git history에 남긴다
이렇게 해도 AI가 다 알아서 해주진 않습니다. 대신 1인 개발자가 주니어 개발자 여러 명을 데리고 일하듯 운영할 수 있습니다. 각 세션이 완벽할 필요는 없지만, 같은 방식으로 읽고 만들고 검증한 다음 다음 작업으로 넘길 수는 있어야 하고요.
앞으로 개발 생산성 차이는 AI가 일할 수 있는 시스템을 얼마나 잘 설계하냐에서 갈릴 것 같아요.