바이브코딩으로 웹사이트 하나쯤은 만들어보셨을 겁니다. 웹 개발 글이나 Copilot 글 따라 하면 하루 만에 됩니다.

그런데 두 번째, 세 번째 프로젝트에서 막힙니다. AI가 지난주 결정을 까먹고, 같은 실수를 반복하고, "그건 말씀 안 하셨는데요"라는 답이 돌아옵니다. 프롬프트를 더 잘 쓰는 문제가 아닙니다. AI가 일하는 환경을 안 만들어준 문제입니다.

2026년 흐름은 분명합니다. spec-driven(명세서 중심)에서 agent-driven(에이전트 중심)으로. 코더에서 AI 조직의 운영자로 역할이 바뀌는 중입니다.

뭐가 바뀌는가: 명세서에서 운영체제로

구분 기존 바이브코딩 에이전트 중심
중심 기술명세서 AI의 기억과 행동
문서 목적 기능 정의 AI 운영 규칙 정의
AI 역할 시키면 만드는 구현자 기억을 가진 협업 조직
개발자 역할 지시자·검토자 환경 설계자·아키텍트

핵심 문장 하나만 기억하세요.

문서는 사람을 위한 읽을거리가 아니라 AI를 위한 운영체제다.

5종 문서에 뭐를 적는가

프로젝트/
├─ PRD.md           문제 정의·사용자 요구 (왜 만드는가)
├─ ARCHITECTURE.md  API·DB·상태·배포 뼈대 (어떻게 생겼는가)
├─ AGENTS.md        조직도·행동 정책 (누가 뭘 하고 뭘 못 하는가)
├─ SKILLS.md        기술 세계관 (무슨 맛으로 만드는가)
└─ MEMORY.md        장기 교훈 (무엇을 반복하지 않을 것인가)

PRD.md: 한 장으로 "왜"

문제, 사용자, 성공 기준을 적습니다. 길게 쓰면 안 읽습니다.

## PRD 예시 뼈대
- 문제: 동아리 회비 정산을 카톡으로 해서 매번 틀린다
- 사용자: 총무 1명 + 회원 30명 (모바일 우선)
- 성공 기준: 정산 1건 3분 이내, 이의제기 월 1건 이하
- 범위 밖: 자동 이체, 영수증 OCR (다음 버전)

ARCHITECTURE.md: 뼈대만

API 흐름, DB 구조, 상태 관리, 배포를 적습니다. Cursor 같은 도구가 전체 구조를 파악하는 데 이 파일이 제일 중요합니다.

AGENTS.md: 미니 조직도

혼자 일해도 역할은 나눕니다. 탐색·구현·검토 3역이면 충분합니다.

## AGENTS.md 예시 뼈대
- Planner: 요구를 작업 단위로 쪼갠다. 코드는 짜지 않는다.
- Builder: Planner의 작업 1개씩 구현한다. 테스트를 함께 짠다.
- Reviewer: diff를 읽고 테스트·스타일·보안을 확인한다.
- 규칙: 작업 디렉터리 밖 수정 금지 / 삭제·배포 전 승인 필수

보안 4층의 권한 목록이 여기 들어가면 금상첨화입니다.

SKILLS.md: 취향 10줄

선호 스택, 금지 패턴, UI 방향을 적습니다. "매번 새로운 개발자처럼 행동하지 않게" 하는 파일입니다.

## SKILLS.md 예시
- 폼 검증은 서버·클라이언트 양쪽에 둔다
- 날짜는 half-open interval로만 다룬다
- any 타입 금지, 모르면 물어본다
- 버튼은 기본·위험 2종 스타일만 쓴다

MEMORY.md: 실수 박물관

기억 3층 글에서 다룬 영속 기억입니다. 같은 실수 2번 하면 1줄 추가하는 규칙으로 시작하세요.

CodeBridge Mini Lab: 주말 2시간 세팅

① 30분: PRD 1장 쓰기 (문제·사용자·성공 기준·범위 밖)
② 30분: ARCHITECTURE 뼈대 (DB 5개 테이블 이내로 시작)
③ 30분: AGENTS.md (3역 + 금지 5개 + 승인 3개)
④ 20분: SKILLS.md 취향 10줄
⑤ 10분: MEMORY.md에 지금까지의 실수 3개

완료 판정:
새 채팅에서 "AGENTS.md 읽고 Planner로 할 일 쪼개줘"가 되면 성공

공공데이터 첫 앱이나 크롬 확장 같은 입문 프로젝트에 이 5종을 얹어보세요. 같은 앱인데 AI가 훨씬 덜 헤맵니다.

결론: 코더에서 운영자로

흐름을 한 줄로 정리합니다.

생각하고 코딩하는 시대에서, 기록하고 AI가 구현하게 하는 시대로.

미래에 값어치 있는 능력은 코드를 빨리 짜는 게 아니라 AI가 잘 일하는 환경을 설계하는 것입니다. 문서 5장이 그 환경의 최소 단위입니다. 이번 주말에 2시간 내서 깔아두세요. 다음 프로젝트부터 AI가 신입이 아니라 경력자처럼 일하기 시작합니다.

함께 읽으면 좋은 글

참고 자료

이 주제를 직접 따라가며 배우고 싶다면

대화로 웹사이트를 만들고 배포까지 이어가는 연습이 필요하다면, 반나절 만에 웹사이트를 개발하는 과정이 이 글의 5종 문서와 바로 이어집니다.