전체 내역

[멀티 에이전트 설정] 프로젝트 문서 6종, AI가 길을 잃지 않게 하는 구조

바이브 코딩이 길어질수록 AI는 처음 정한 것을 잊습니다. 요구사항, 구조, 규칙, 디자인, 작업, 기억을 문서 여섯 개로 나눠 두는 방법을 파일별로 살펴봤습니다.

AI에게 앱을 만들게 하다 보면 처음에는 잘 따라오다가, 대화가 길어지면서 어긋나기 시작하는 일이 흔합니다. 폴더 구조가 슬그머니 바뀌고, 이미 있는 컴포넌트를 두고 새로 만들고, 어제 끝낸 일을 오늘 다시 묻습니다. 새 대화를 시작하면 사정은 더 나빠집니다. 이 글에서는 이런 문제를 문서 여섯 개로 막는 방법을 다룹니다. 파일별로 무엇을 적는지, 이 블로그의 광명 지도를 예로 풀어 보겠습니다.

1. 어떤 도구인가

특정 AI 도구에 묶인 기능이 아니라, 프로젝트 폴더에 두는 문서 구성입니다. prd.md, architecture.md, rules.md, design.md, tasks.md, memory.md 여섯 개를 만들어 두고, AI에게 작업 전에 읽게 하고 작업 후에 갱신하게 합니다. Claude Code, Cursor, Codex처럼 파일을 읽을 수 있는 도구라면 어디서든 같은 방식으로 쓸 수 있습니다.

발상은 단순합니다. 맥락을 대화가 아니라 파일에 둡니다. 대화는 길어지면 잘려 나가지만 파일은 그대로 남습니다. 사람이 읽어도 프로젝트의 현재 상태를 한눈에 알 수 있어서, 혼자 하는 작업에서도 팀 작업에서도 도움이 됩니다.

2. 언제 쓰면 좋은가

앱 하나를 AI와 며칠에 걸쳐 만들 때 가장 효과가 큽니다. 한 번의 대화로 끝나는 작은 스크립트에는 과합니다. 저는 아래 같은 상황에서 필요하다고 봅니다.

  • 대화를 새로 열 때마다 프로젝트 배경을 다시 설명하고 있을 때
  • AI가 이미 있는 코드를 모르고 비슷한 것을 새로 만들 때
  • 여러 도구를 오가며 작업해서 맥락이 흩어질 때
  • 어디까지 했는지 나중에 본인도 헷갈릴 때

3. 사용법

문서는 모두 docs 폴더에 둡니다. 각 파일이 맡는 질문이 서로 다르다는 점이 구성의 요점입니다. 무엇을 만들까, 어떻게 짜여 있나, 어떤 규칙을 지키나, 어떻게 보이나, 무엇을 해야 하나, 지금 어디까지 왔나입니다.

prd.md, 무엇을 왜 만드는가

제품 요구사항 문서(PRD, Product Requirements Document)입니다. 맨 위에 버전, 날짜, 작성자, 상태, 목표 출시 시점을 표로 두고, 그 아래로 제품 개요, 해결하려는 문제, 목표, 대상 사용자, 핵심 기능(MVP)을 번호를 달아 잇습니다. 핵심 기능에는 로그인이나 대시보드처럼 최소 제품에 들어갈 것만 적습니다.

AI에게 이 문서가 중요한 이유는 범위를 정해 주기 때문입니다. "대학생이 학업을 한곳에서 관리한다"처럼 목표와 대상이 적혀 있으면, AI가 기능을 제안할 때 기준이 생깁니다. 반대로 MVP에 없는 기능을 멋대로 붙이려 할 때 되돌릴 근거도 됩니다.

예를 들어 광명 지도 프로젝트의 prd.md는 이렇게 쓸 수 있습니다. 이 블로그의 지도를 문서화한다고 보고 제가 새로 쓴 예시입니다.

# 우리동네 지도 PRD
 
| 항목 | 내용 |
|---|---|
| 버전 | 0.1 |
| 상태 | 초안 |
| 공개 위치 | LAB 첫 프로젝트 |
 
## 1. 제품 개요
광명시를 입체 일러스트 지도로 보여 주고, 장소를 골라 둘러보는 웹 페이지입니다.
 
## 2. 해결할 문제
평면 지도 앱은 정보는 많지만 동네를 구경하는 재미가 적습니다.
 
## 3. 목표
- 광명시 경계 안의 건물, 도로, 녹지를 한눈에 보여 준다
- 장소를 고르면 위치와 정보를 바로 확인할 수 있다
 
## 4. 대상 사용자
광명 주민, 광명을 처음 찾는 방문자
 
## 5. 핵심 기능 (MVP)
1. 지도 이동, 회전, 확대
2. 장소 검색과 분류 필터
3. 건물 하이라이트와 상세 정보
 
## 6. 이번 범위에 넣지 않는 것
길찾기, 실시간 교통, 로그인

architecture.md, 어떻게 짜여 있는가

시스템 구조 문서입니다. 첫 항목에는 전체 구조를 그림이나 한 줄 흐름으로 적습니다. 예를 들어 브라우저의 사용자가 프론트엔드와 통신하고, 프론트엔드가 백엔드(서버 액션과 API 라우트)와, 백엔드가 데이터베이스와 이어지는 식입니다.

그 아래에는 기술 스택 표가 있었습니다. 계층, 기술, 목적 세 칸으로 프론트엔드, 언어, 스타일링, 백엔드, 데이터베이스, 인증, 저장소, 배포, 버전 관리를 각각 적습니다. 이어서 폴더 구조, 데이터 흐름, 주요 설계 결정이 나옵니다. 폴더 구조를 app, components, features처럼 역할별로 나눠 적어 두면, AI가 새 파일을 어디에 둘지 헤매지 않습니다.

같은 프로젝트의 architecture.md는 이런 모양이 됩니다.

# 시스템 구조
 
## 1. 전체 구조
브라우저가 Next.js 페이지(/lab/gwangmyeong)를 열고, 페이지가 지도 엔진(Three.js)을 불러오고, 엔진이 정적 데이터(public/maps)를 읽습니다.
외부 API는 부르지 않습니다. 데이터는 빌드 전에 스크립트로 만들어 둡니다.
 
## 2. 기술 스택
| 계층 | 기술 | 목적 |
|---|---|---|
| 프레임워크 | Next.js 16 (App Router) | 페이지와 라우팅 |
| UI | React 19, TypeScript | 목록, 검색, 상세 정보 |
| 3D | Three.js | 지도 장면과 카메라 |
| 스타일 | CSS Modules | 지도 화면 전용 스타일 |
| 데이터 | OpenStreetMap, Python 스크립트 | 경계, 도로, 건물, 장소 |
 
## 3. 폴더 구조
src/app/lab/gwangmyeong/   지도 페이지
src/components/lab/        NeighborhoodMap.tsx(UI), map-engine.ts(장면과 카메라),
                           landmark-models.ts(주요 건물 모형), map-geography.ts(좌표 변환)
src/content/lab.ts         장소 목록과 분류
public/maps/gwangmyeong/   boundary, landscape, buildings 데이터
scripts/                   데이터 생성 스크립트
 
## 4. 데이터 흐름
스크립트가 OSM을 받아 JSON을 만들어 둔다. 엔진은 페이지가 열릴 때 그 파일을 읽는다. 장소를 고르면 엔진이 React에 알린다.

rules.md, 어떤 규칙을 지키는가

개발 규칙 문서입니다. AI와 사람 모두가 따르는 지침이라고 문서 첫머리에 못박아 두면 좋습니다. 일반 원칙에는 작업 전에 PRD, 구조, 디자인 문서를 먼저 따를 것, 로직을 중복하지 말고 기존 컴포넌트와 유틸을 재사용할 것, 크고 위험한 수정보다 작고 집중된 수정을 할 것, 관련 없는 파일을 건드리지 말 것을 둡니다.

기술과 코딩 표준 항목은 언어, 프레임워크, 스타일링, 린트, 포맷, 의존성, 파일 이름처럼 칸을 나눠 한 줄씩 규칙을 적습니다. 예를 들어 언어 칸에는 TypeScript를 쓰고 any는 꼭 필요할 때만 쓴다고 적혀 있었습니다. 세 번째 항목인 프로젝트 구조 규칙은 재사용 컴포넌트와 기능별 코드를 어디에 두는지까지 다룹니다. 이 문서가 가장 직접적으로 AI의 행동을 바꿉니다. "관련 없는 파일을 수정하지 않는다" 한 줄만으로도 diff가 눈에 띄게 깔끔해집니다.

rules.md에는 AI가 어길 때마다 고쳐 쓰고 싶은 규칙을 모읍니다.

# 개발 규칙
 
## 1. 일반 원칙
- 작업 전에 prd.md, architecture.md, design.md를 먼저 읽는다
- 작은 변경 여러 번으로 나눈다. 큰 수정을 한 번에 하지 않는다
- 요청과 관련 없는 파일은 고치지 않는다
- 이미 있는 컴포넌트와 함수를 먼저 찾아 재사용한다
 
## 2. 기술과 코딩 표준
| 항목 | 규칙 |
|---|---|
| 언어 | TypeScript. any는 꼭 필요할 때만 씁니다 |
| 글꼴 | 사이트 기본(Pretendard)만 씁니다. 다른 글꼴을 새로 넣지 않습니다 |
| 상태 | 매 프레임 바뀌는 값(확대 비율, 각도)은 React 상태 대신 ref로 갱신합니다 |
| 정리 | 3D 리소스(지오메트리, 텍스처)는 화면을 떠날 때 반드시 해제합니다 |
 
## 3. 문구 규칙
UI 문구와 글에 긴 줄표, 화살표, 이모지를 쓰지 않는다

design.md, 어떻게 보여야 하는가

디자인 시스템 문서입니다. 디자인 원칙, 색상 팔레트(기본, 보조, 성공, 경고, 오류, 배경 색과 값), 타이포그래피(기본 글꼴과 크기 단계), UI 컴포넌트(버튼의 기본, 보조, 위험 변형 등) 순으로 적습니다.

AI에게 색과 글꼴을 말로만 설명하면 매번 조금씩 다른 값이 나옵니다. 값을 문서에 적어 두면 "디자인 문서를 따른다"는 한 줄로 일관성을 얻습니다.

design.md는 말로 설명하기 어려운 값을 그대로 적습니다. 아래 색은 이 지도 코드에 실제로 쓰는 값입니다.

# 디자인 시스템
 
## 1. 원칙
- 낮의 일러스트 같은 차분한 색을 쓴다
- 사이트 테마(라이트, 다크)와 별개로 지도는 항상 낮 풍경이다
 
## 2. 색상
| 이름 | 값 | 쓰는 곳 |
|---|---|---|
| 지도 배경 | #f0eadb | 장면 배경 |
| 포인트 초록 | #365f4e | 선택된 이름표, 포커스 링 |
| 하이라이트 | #f08a3c | 선택한 건물 |
| 도로명 글자 | #5f6f52 | 도로명 라벨 |
 
## 3. 타이포그래피
기본 글꼴은 Pretendard. 이름표 11px, 도로명 10px, 상세 제목 20px.
 
## 4. 컴포넌트
- 이름표: 반투명 크림색 배경, 선택 시 초록 배경에 밝은 글자
- 지도 컨트롤: 폭 40px 고정, 버튼과 수치를 모두 가운데 정렬

tasks.md, 무엇을 해야 하는가

작업 목록과 개발 계획 문서입니다. 맨 위에는 전체 작업 수와 완료 수, 진행률 같은 요약을 둡니다. 그 아래로 프로젝트 설정, 인증, 노트 관리처럼 단계(phase)별 표를 잇고, 각 작업에 번호, 작업 이름, 우선순위(높음, 보통), 상태(완료, 진행 중, 시작 전)를 붙입니다.

번호가 있다는 점이 유용합니다. "2.3 회원가입 로직 구현하자"처럼 번호로 말하면 AI와 오해 없이 같은 작업을 가리킬 수 있습니다. 한 번에 한 단계만 시키는 식으로 작업량도 조절됩니다.

tasks.md는 번호와 상태가 핵심입니다. 이 지도 작업을 단계로 나누면 이렇게 쓸 수 있습니다. 3단계의 모바일, 접근성, 성능 점검 상태는 예시를 위해 가정한 값입니다.

# 작업 목록
 
전체 12개, 완료 9개, 진행 중 1개, 시작 전 2개
 
## 1단계 데이터 준비
| # | 작업 | 우선순위 | 상태 |
|---|---|---|---|
| 1.1 | OSM 원본 내려받기 | 높음 | 완료 |
| 1.2 | 시 경계 안으로 자르기 | 높음 | 완료 |
| 1.3 | 도로 이름을 JSON에 추가 | 보통 | 완료 |
 
## 2단계 지도 엔진
| # | 작업 | 우선순위 | 상태 |
|---|---|---|---|
| 2.1 | 지형 판과 카메라 구성 | 높음 | 완료 |
| 2.2 | 이동, 회전, 확대 조작 | 높음 | 완료 |
| 2.3 | 선택 건물 하이라이트 | 높음 | 완료 |
| 2.4 | 거리별 건물 표시(LOD) | 보통 | 완료 |
| 2.5 | 도로명 라벨 | 보통 | 완료 |
 
## 3단계 화면과 점검
| # | 작업 | 우선순위 | 상태 |
|---|---|---|---|
| 3.1 | 장소 목록, 검색, 상세 정보 | 높음 | 완료 |
| 3.2 | 모바일 화면 점검 | 높음 | 진행 중 |
| 3.3 | 접근성 점검 | 보통 | 시작 전 |
| 3.4 | 성능 측정 | 낮음 | 시작 전 |

memory.md, 지금 어디까지 왔는가

프로젝트 기억 문서입니다. 맨 위에 마지막 갱신 시각, 현재 단계, 진행률을 두고, 이어서 현재 상태 체크리스트, 완료한 작업과 날짜, 진행 중인 작업 표를 적습니다. 개발 세션이 바뀌거나 새 기여자가 와도 흐름이 이어지게 하는 문서입니다.

tasks.md가 앞으로 할 일의 계획이라면 memory.md는 지금까지의 상태와 중요한 메모입니다. 새 대화를 열었을 때 AI가 가장 먼저 읽을 문서가 이것입니다. 어제 끝낸 일을 다시 묻는 문제가 여기서 풀립니다.

마지막으로 memory.md는 새 대화를 열었을 때 AI가 가장 먼저 읽는 문서입니다.

# 프로젝트 기억
 
마지막 갱신: 2026-10-12
현재 단계: 3단계 화면과 점검
 
## 현재 상태
- [x] 지도 엔진 완성 (이동, 회전, 하이라이트, LOD, 도로명)
- [x] 장소 목록, 검색, 상세 정보 완성
- [ ] 모바일 화면 점검 진행 중
 
## 결정 사항
- 지도 SDK 대신 Three.js 장면으로 구성한다
- 글꼴은 사이트 기본(Pretendard)만 쓴다
- 이름표 위에서 시작한 드래그는 캔버스로 넘겨 지도 조작이 끊기지 않게 한다
 
## 알아 둘 것
- 데이터 기준일은 2026-10-08이다
- 로컬에서 데이터가 안 보이면 Docker와 로컬 Supabase가 켜져 있는지 먼저 본다

도구에 연결하는 방법

여섯 파일을 만들어 두는 것만으로는 AI가 알아서 읽지 않습니다. 도구의 지침 파일(Claude Code라면 CLAUDE.md)에 읽는 순서와 갱신 규칙을 한 번 적어 두어야 합니다. 아래처럼 적어 두면 됩니다.

  • 작업을 시작할 때 memory.md, tasks.md, rules.md를 먼저 읽는다
  • 구조나 화면을 건드릴 때는 architecture.md, design.md를 확인한다
  • 작업을 마치면 tasks.md의 상태와 memory.md의 현재 상태를 고친다

4. 적용 예시

이 블로그 저장소에는 이미 비슷한 장치가 두 가지 있습니다. CLAUDE.md에 글쓰기 지침과 금지 표현을 적어 두었고, Claude Code의 자동 기억 기능으로 글 작성 방식과 콘텐츠 파이프라인 같은 사실을 남겨 둡니다. 역할로 보면 앞의 것은 rules.md, 뒤의 것은 memory.md에 가깝습니다.

아래는 가정한 시나리오입니다. LAB의 광명 지도처럼 며칠에 걸쳐 기능을 덧붙이는 프로젝트를 처음부터 이 구조로 시작한다고 해 보겠습니다. prd.md에는 "광명시를 입체 일러스트 지도로 보여 주고 장소를 둘러본다"를 쓰고, architecture.md에는 Next.js 페이지와 Three.js 지도 엔진, 정적 데이터 파일의 관계를 그립니다. rules.md에는 글꼴은 사이트 기본을 따르고 기존 컴포넌트를 재사용한다는 규칙을, design.md에는 지도에 쓰는 색 값을 적습니다. 그러면 회전 조작이나 도로명 표시 같은 요청이 올 때마다 tasks.md에 번호가 붙고, 끝난 일은 memory.md로 옮겨집니다. 대화를 비우고 새로 시작해도 이 두 파일만 읽으면 이어서 작업할 수 있습니다.

5. 써 본 소감

여섯 개를 한꺼번에 만들려고 하면 시작도 전에 지칩니다. 제 생각에는 rules.md와 memory.md 두 개만 먼저 두어도 체감이 큽니다. 한 번 적어 둔 규칙은 매번 다시 말하지 않아도 되고, 상태 기록은 새 대화의 출발점이 되어 줍니다. 문서가 오래되면 오히려 AI를 잘못 이끌기 때문에, 작업이 끝날 때마다 갱신하는 습관이 구조 자체보다 중요하다고 생각합니다.

Comments (0)