"문서가 곧 프롬프트가 된다. AI 에이전트한테 설명할 필요 없이 문서를 가리키면 된다."
"일단 만들어보자"는 마음으로 바로 코딩에 들어가는 방식. 만들다 보면 방향이 바뀌고, 컴포넌트를 만들었다가 갈아엎고, AI한테 매번 길게 설명해야 한다. 결과물은 나오지만 일관성이 없고, 다음 기능을 붙일 때마다 처음부터 다시 설명하는 비용이 생긴다.
문서를 먼저 만들고 레포 docs/ 폴더에 넣었다. 이제 Antigravity에 프롬프트를 넣을 때 "docs/dev-order-v1.4.md Step 1 진행해줘"처럼 짧게 써도 된다. 에이전트가 문서를 직접 읽고 맥락을 이해한 상태로 작업한다. 문서가 곧 프롬프트가 된다.
바이브 코딩을 시작하기 전에 7종의 기획 문서를 먼저 만들었다. 비전 문서, PRD, 유저플로우, 개발 순서, 디자인 토큰, 와이어프레임, 컴포넌트 인벤토리. 코딩보다 이게 먼저인 이유가 있다.
바이브 코딩을 시작하기로 했을 때 제일 먼저 한 게 코딩이 아니었다.
Antigravity를 설치하고, 레포를 만들고, Next.js를 깔기 전에 7종의 문서를 먼저 썼다. 비전 문서, PRD, 유저플로우, 개발 순서, 디자인 토큰, 와이어프레임 3종, 컴포넌트 인벤토리. 여기에 Claude와 수십 번 대화하며 각 문서를 다듬는 데 며칠이 걸렸다.
왜 이렇게 했을까.
AI 에이전트는 맥락을 기억하지 못한다 Antigravity 같은 에이전트형 도구는 대화가 끝나면 앞에서 나눈 내용을 잃는다. 새 채팅을 열 때마다 "우리 프로젝트는 Next.js 16 기반이고, Supabase를 쓰고, 지금 Step 2까지 왔어"를 다시 설명해야 한다면 에이전트를 쓰는 이점이 반감된다.
문서를 레포 docs/ 폴더에 넣으면 이 문제가 해결된다. 에이전트가 파일을 직접 읽기 때문에 프롬프트가 짧아진다. // 문서 없을 때 프롬프트 "Next.js 16 + Tailwind v4 + Supabase 구조인데, 지금 관리자 인증 만들려고 해.
Supabase Auth 써서 /admin 로그인 페이지 만들어줘. 미들웨어도 넣어서 비로그인 시 /admin 접근 차단해줘."
// 문서 있을 때 프롬프트 "docs/dev-order-v1.4.md Step 2 진행해줘."
와이어프레임은 복잡한 화면만 Figma를 쓰지 않았다. 대신 텍스트로 레이아웃을 적었다. ASCII로 섹션 배치를 그리고, 각 섹션에 들어갈 컴포넌트와 데이터 출처를 명세했다.
홈, 프로젝트 허브, /now — 이 세 개만 그렸다. 나머지 페이지는 디자인 토큰과 컴포넌트 인벤토리로 충분하다고 판단했다. 텍스트 와이어프레임이 Figma 시안보다 에이전트 친화적인 이유가 있다. 에이전트는 이미지를 보는 게 아니라 텍스트를 읽기 때문이다.
컴포넌트 인벤토리가 일관성을 만든다 와이어프레임 3개를 그리고 나니 필요한 컴포넌트 목록이 자연스럽게 드러났다. Button, Card, StatusBadge, Tag, SideProjectCard, WorkProjectCard, NowFeedItem 등 20여 개.
이걸 미리 정의해두면 에이전트가 페이지를 만들 때마다 다른 구조의 버튼을 만들거나, 카드 스타일이 제각각이 되는 걸 막을 수 있다.
결과 첫 프롬프트를 넣었을 때 Antigravity는 코드를 바로 짜지 않고 계획을 먼저 보여줬다. 그 계획에서 git 브랜치 명령어 오류를 발견했다. 문서가 있었기 때문에 계획 검토가 빠르게 끝났다. 실수는 코드가 쓰이기 전에 잡혔다.
문서 준비에 며칠 걸렸지만, 그 이후 작업 속도가 눈에 띄게 빨라졌다. 설명하는 시간이 사라졌기 때문이다.
AI 에이전트는 대화 한 번이 끝나면 맥락을 잃는다. 매번 "우리 프로젝트는 이런 거고, 스택은 이렇고, 지금까지 이걸 했어"를 다시 설명해야 한다면 에이전트를 쓰는 이점이 반감된다. 문서를 레포에 넣으면 에이전트가 직접 읽기 때문에 이 비용이 사라진다. 또한 문서가 있으면 기획자 혼자서도 일관성을 유지할 수 있다. 컴포넌트 인벤토리 덕분에 버튼이나 카드를 새로 만들 때마다 디자인 결정을 반복하지 않아도 된다.
이 구조는 프로젝트 종류에 상관없이 그대로 쓸 수 있다. 순서는 이렇다:
비전 문서 — 왜 만드는지 PRD — 무엇을 만드는지, DB 스키마 포함 유저플로우 — 어떻게 움직이는지 개발 순서 — 어떤 순서로 만드는지 디자인 토큰 — 어떤 모습으로 만드는지 와이어프레임 — 복잡한 화면만 (홈/핵심 페이지) 컴포넌트 인벤토리 — 재사용 컴포넌트 목록
7개 중에서 줄인다면 비전+PRD+개발순서 3개가 최소 단위다. 이 3개만 있어도 에이전트한테 맥락을 넘기는 데 충분하다.
관련 프로젝트
프로젝트 개요 기획자(PM)로서 AI를 활용한 업무 자동화(AX) 사례를 문서화하는 개인 포트폴리오 사이트입니다. 국내 기업의 AX 기획자/AI PM 직군으로의 커리어 전환을 목표로, 사이트 자체가 채용 지원용 스토리텔링 자료로 실사용되고 있습니다. 핵심 패턴: 업무 병목 발견 → AI로 워크플로우 재설계 → Before/After·근거·재현 가능성 문서화 전체 서사는 '실행하지 않은 아이디어 나열'이 아니라, 하나의 검증된 자동화 패턴과 도메인별 확장 블루프린트를 갖춘 재사용 가능한 엔진을 보유하는 방향으로 수렴하고 있습니다. 기술 스택 Next.js 16, Tailwind CSS v4, TypeScript Supabase (개발/운영 환경 분리), Vercel, Resend Claude API 기반 기술 자문 및 프롬프트 설계 보안 아키텍처 관리자 CRUD는 세션 기반 인증과 RLS(Row Level Security)로 보호 공개 읽기 전용 경로는 별도의 익명 클라이언트로 분리 서비스 롤 키는 애플리케이션 코드에서 완전히 배제 권한 검증은 마이그레이션 파일 및 대시보드 검토를 통해서만 진행 작업 방식 (에이전틱 IDE 협업 워크플로우) AI 에이전트 기반 IDE가 파일/버전관리 작업을 담당하고, LLM은 기술 자문 및 프롬프트 작성 역할을 수행하는 협업 구조를 운영합니다. AI 자문 → 에이전트용 프롬프트 작성 → 실행자가 붙여넣기 → 계획 확인 → 자문 검토 → 실행 승인 → 로그 검토 → 직접 클릭 테스트 → 명시적 지시 시에만 커밋 통제 규칙 실행 전 계획 검토 필수 요약 보고가 아닌 직접 클릭 테스트로 검증 개발 환경 우선 적용 후 명시적 승인 하에 운영 환경 반영 커밋은 명시적 지시가 있을 때만 수행 DB 자격증명 직접 연결 및 범위 외 삭제 금지 브랜치 전략: 개발 브랜치에서 작업 후 운영 브랜치는 배포 전용으로 직접 커밋 금지, 병합 전 변경 범위 검증 현재 진행 상황 고객사 미팅 브리핑 자동화 사례: 1단계 완료, 개발/운영 환경 배포 및 실데이터 테스트 완료 범위 변경 감지 자동화 사례: 상태 확인 진행 중 리스크 조기 경보 자동화 사례: 운영 환경 배포 완료 보안 사고 관련 포스트: 'AI 리스크 거버넌스 사례'로 재구성 예정 AI 활용 관련 콘텐츠 시리즈 초안 작성 완료, 게시 미확정 핵심 학습 원칙 보고가 아닌 검증: 버그·보안 이슈는 항상 직접 로그/브라우저 검토를 통해서만 발견되며, 에이전트의 자체 결과 요약을 그대로 신뢰하지 않음 보안 사고의 콘텐츠화: 실제 발생한 권한 관련 이슈 사례를 케이스 스터디로 재구성하여 콘텐츠화 커밋 의미 분리: 기능 단위/변경 유형별로 항상 분리 커밋 자동화하지 않는 것도 스토리: 저사용 빈도 기능을 의도적으로 고도화하지 않은 결정 자체를 AX 스토리텔링 소재로 활용