세 가지 문서와 방법론 축적
기능을 30개 만들고, 3개월 후에 "이 기능은 언제 추가됐지? 왜 이렇게 설계했지? 중간에 방식을 몇 번이나 바꿨지?"라고 찾아보려 해도 git log를 아무리 뒤져도 답이 없습니다. 해결책은 AI에게 엄격한 템플릿으로 세 가지 문서를 유지하게 하고, 자동으로 축적되는 방법론 핸드북을 추가하는 것입니다. 이 페이지의 두 데모 모두 직접 조작할 수 있습니다.
핵심 역할 분담: FEATURES는 "이 기능은 어떻게 나왔나?"를, CHANGELOG는 "이번에 무엇이 바뀌었나?"를, RELEASE_NOTES는 "사용자는 무엇을 얻었나?"를, METHODOLOGY는 "우리는 어떻게 생각했나?"를 답합니다. 네 가지 질문에 각각 귀착점이 있어야 결정이 대화를 넘어 살아남을 수 있습니다.
기능의 완전한 생명 주기
기능의 단일 진실 소스입니다. 상태 전환: 🟡 계획 중 → 🔵 개발 중 → 🟢 완료 / ⚪ 취소. 각 기능에 "히스토리" 섹션이 있어 초기 요구사항, 방식 변경과 이유, 최종 구현을 기록합니다. 취소된 기능도 삭제하지 않고 ⚪로 표시하고 이유를 기록합니다.
모든 변경 사항의 기술적 세부 내용
역시간 순서로, 각 항목을 표 형식으로 기록합니다: 이슈/요구사항, 근본 원인/방식, 변경 범위, 영향받는 영역, 상태. 타입 태그: BUG / FEAT / REFACTOR / PERF / DOCS. 작성 전 반드시 시스템 시간을 확인해야 하며, 기억으로 타임스탬프를 채우거나 나중에 몰아서 작성하는 것은 금지됩니다.
사용자가 인지할 수 있는 변화
실제 사용자를 위해 작성되며, CHANGELOG와 완전히 다른 언어 스타일을 사용합니다. 모든 항목은 "나에게 무슨 의미가 있나?"라는 질문에 답해야 합니다. 절대 규칙: 디버그 기능, 기술적 세부 내용, 사용자가 인지하지 못하는 변경 사항은 작성 금지입니다.
제품 결정과 미적 감각
AI가 대화에서 제품 철학, 결정 논리, 트레이드오프 선호도를 능동적으로 파악하여 정제한 후 직접 기록합니다. 새 대화는 자동으로 이를 상속합니다. 네 섹션 구조: 제품 원칙, 설계 결정 기록, UX 선호도, 안티패턴.
프로젝트에서는 매일 다양한 정보가 생성됩니다. 분류 능력이 문서 시스템이 제대로 작동할 수 있는지를 결정합니다. 아래 8가지 실제 정보를 하나씩 살펴보고 각각 어느 문서에 넣어야 하는지 판단하세요.
FEATURES의 모든 기능에는 "히스토리" 섹션이 있습니다. 상태 전환을 통해 자동으로 성장합니다: 모든 상태 변경과 방식 조정은 날짜가 포함된 항목을 추가합니다. 버튼을 클릭해서 기능을 계획에서 출시까지 직접 진행해 보세요.
히스토리의 날짜는 기기의 시스템 시계에서 읽습니다. 규칙: 타임스탬프는 현재 시스템 시간에서 읽어야 합니다—기억으로 채워 넣어서는 안 됩니다. 방식이 변경되지 않았더라도 "초기 요구사항" 항목을 작성해야 합니다.
각 변경 사항은 고정된 필드의 표로 기록됩니다. AI가 칸을 채우기만 하면 되며, 매번 무엇을 써야 할지 생각할 필요가 없습니다.
## YYYY-MM-DD HH:MM
### [타입] 제목 타입: BUG / FEAT / REFACTOR / PERF / DOCS
| 필드 | 내용 |
|---------------|---------------------------------------------------------|
| 이슈/요구사항 | 이 변경을 유발한 것 (사용자 피드백 / 버그 증상 / 새 요구사항) |
| 원인/방식 | 버그: 근본 원인 분석; 기능: 기술 방식 요약 |
| 변경 범위 | 영향받는 파일 또는 모듈 목록 |
| 영향도 | 이 변경으로 영향받을 수 있는 기존 기능 |
| 상태 | ✅ 완료 / ⏳ 진행 중 / ⚠️ 모니터링 필요 |- 디버그 / 내부 도구 기능
- 기술적 구현 세부 내용: 모듈 이름, 파일 경로, 리팩터링
- 사용자가 인지할 수 없는 변경 사항
- 개발자 전문 용어 및 기술 원리 설명
- 사용자가 인지할 수 있는 변화, 각 항목은 "나에게 무슨 의미가 있나?"에 답해야 합니다
- 새 기능: 사용자가 이제 할 수 있는 새로운 것을 한 문장으로
- 수정: 이전에 어떤 문제가 있었고 지금은 해결됐습니다
- 항목당 최대 3문장, 버전 번호는 SemVer 따르기
4섹션 구조
- 제품 원칙: 반복적으로 나타나는 핵심 신념과 제품 철학
- 설계 결정 기록: [날짜] 결정 내용, 이유와 맥락 포함
- UX 선호도: UI/UX에 대한 미적 취향, 경향, 심미적 기준
- 안티패턴: 명시적으로 거부된 방식들, 거부 이유 포함
작성 원칙
- 본질을 정제하고, 유사한 항목은 병합하고, 새 항목에 날짜를 표시하고, 대화 원문을 그대로 복사하지 마세요
- 기술적 구현 세부 내용(CHANGELOG의 역할)이나 일회성 임시 결정은 기록하지 마세요
- 트리거: 사용자가 "왜 이렇게 하는지" 설명할 때; 방식을 거부하면서 이유를 제시할 때; 명확한 UI/UX 선호도를 표현할 때; 회고에서 경험을 정리할 때
- AI가 인식하면 즉시 기록하고, 작성 후 간략히 알림—매번 허가를 구할 필요 없음
왜 저장소에 보관하는가: 설계 결정을 Notion이나 Feishu에 써도 소용없습니다—AI는 외부 문서를 읽을 수 없습니다. 프로젝트 저장소 안의 Markdown 파일만이 AI가 자동으로 컨텍스트를 얻을 수 있는 유일한 방법입니다.
제출물: docs/ 디렉토리 + 방법론 항목 3개. ① 진행 중인 프로젝트에서 docs/ 디렉토리를 만들고 AI에게 템플릿으로 세 가지 문서를 초기화하게 한 후, 기존 기능을 FEATURES.md에 추가하세요; ② 문서 유지 규칙을 Rule 파일에 추가하고, 소소한 변경을 하나 한 후 AI가 CHANGELOG를 자동으로 업데이트하는지 확인하세요; ③ 최근 제품 토론을 돌아보고, 확인한 설계 결정 3가지를 METHODOLOGY.md에 직접 작성하세요.
출처: 오픈소스 저장소 itshen/xs_vibe_rules의 rule-opensource.mdc 9장 "버전 기록 및 문서 유지"와 12장 "제품 방법론 축적".