바이브 코딩을 그냥 감으로 하지 않는다

요즘은 "바이브 코딩"이라는 말을 많이 씁니다.

대충 만들고 싶은 걸 말하면 AI가 코드를 짜주는 방식처럼 들립니다. 저도 처음에는 그렇게 썼습니다. "이 기능 만들어줘", "이 버그 고쳐줘", "이 UI 예쁘게 바꿔줘" 같은 식입니다.

그런데 OpenCairn처럼 코드가 커지기 시작하면 이 방식은 금방 한계가 옵니다.

AI는 빠르게 코드를 쓰지만, 맥락을 잃으면 더 빠르게 이상한 코드를 씁니다. 이미 있는 구조를 무시하고 새 추상화를 만들거나, 문서에는 완료라고 적어두고 실제 검증은 안 하거나, 테스트가 깨져 있는데 겉보기만 그럴듯하게 마무리할 수 있습니다.

그래서 요즘 제가 쓰는 방식은 조금 다릅니다.

프롬프트를 잘 쓰는 것보다, AI가 일할 수 있는 개발 환경을 먼저 만듭니다.

문서 구조
-> 작업 라우팅
-> 스킬 하네스
-> 작은 구현 단위
-> 검증 루프
-> 리뷰와 푸시

이 흐름 전체를 저는 바이브 코딩의 실제 본체라고 생각합니다.

1. 먼저 레포가 스스로 설명하게 만든다

AI에게 긴 설명을 매번 붙여 넣는 것은 오래 못 갑니다.

그래서 OpenCairn에는 에이전트가 처음 읽어야 하는 문서를 정해 둡니다.

docs/README.md
docs/contributing/roadmap.md
docs/contributing/feature-registry.md
docs/architecture/
docs/agents/
docs/testing/

이 문서들은 "프로젝트 소개"라기보다 라우터에 가깝습니다. 지금 건드리는 기능이 web인지, api인지, worker인지, db인지 먼저 나누고, 그다음에 어떤 규칙을 따라야 하는지 알려줍니다.

예를 들어 OpenCairn은 이런 경계가 있습니다.

apps/web        - Next.js UI
apps/api        - Hono API
apps/worker     - Python Temporal worker
apps/hocuspocus - Yjs collaboration server
packages/db     - Drizzle 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가 따라야 하는 작은 운영 매뉴얼"입니다. 매번 장문의 지시를 쓰는 대신, 작업 종류별로 규칙을 파일로 만들어 둡니다.

OpenCairn에는 이런 식의 스킬이 있습니다.

opencairn-rules
opencairn-post-feature
opencairn-parallel-sessions
opencairn-next-plan
opencairn-commit

예를 들어 opencairn-rules는 코드베이스 규칙을 잡아줍니다. opencairn-post-feature는 기능을 끝냈다고 말하기 전에 문서, 테스트, diff, 상태 기록을 확인하게 만듭니다. opencairn-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에게 "OpenCairn 완성해줘"라고 하면 안 됩니다.

대신 이런 식으로 자릅니다.

목표: 에이전트가 노트 업데이트를 제안하게 만들기

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를 맡을 수 있습니다.

바이브 코딩의 속도는 "AI가 빠르게 코드를 치는 속도"가 아니라 "작업을 충돌 없이 나누는 능력"에서 나옵니다.

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가 일할 수 있는 시스템을 더 잘 설계하느냐입니다.