— PRD 이후, 바이브 코딩으로 구현까지 직결되는 초정밀 가이드 —
기능 명세서는 PRD가 제시한 무엇을에 대한 큰 그림을 “어떻게, 어느 정도로” 구현할지 구체적으로 풀어 주는 단계입니다. 특히 바이브 코딩처럼 AI에게 직접 코드를 생성하도록 요청할 때, 명세서가 세밀할수록 AI가 추측해야 할 여지가 줄어들어 결과물이 더 정확하고 완성도 있게 나옵니다.
왜 꼭 필요할까? 🔍
• 추측 최소화 → 품질 향상 : “CRUD 만들어줘”만 입력하면 AI는 가장 단순한 예제만 돌려주지만, 입력·검증·오류 처리 조건을 명시하면 바로 서비스 수준 코드를 제시합니다.
• 팀 커뮤니케이션 : 디자인·백엔드·프런트엔드가 같은 문서를 바라보고 개발해 ‘동시다발 수정’ 리스크를 줄입니다.
• 테스트 기준 제공 : QA 단계에서 ‘무엇을 어떻게 검증해야 하는지’가 명세서 항목 그대로 테스트 시나리오가 됩니다.
• 스코프 관리 : 기능 범위를 글로 고정해 두면, 개발 도중 새 요구사항이 튀어나오는 ‘풍선 효과’를 방지할 수 있습니다.
읽는 법
① 굵은 제목은 항목 이름,
②코드 블록은 AI에게 그대로 던져도 되는 요청 예시,
③ ▸ 기호는 실제 동작 흐름을 나타냅니다.
1. 할 일 추가·수정 ― “텍스트 한 줄”이 카드가 되기까지
| 단계 | 세부 설명 | 구현 포인트 |
|---|---|---|
| ① 입력 수집 | 사용자가 텍스트 필드에 제목 입력 후 Enter 또는 + 버튼 탭 | 모바일 키보드는 action="done" 지정 → 입력 후 키보드 자동 닫힘 |
| ② 클라이언트 검증 | 빈 문자열, 공백만 입력 시 즉시 거절 | trim().length === 0이면 shake 애니메이션 + 토스트 “할 일을 입력하세요” |
| ③ AI 중요도 계산 | calculatePriority(taskText) 호출 ▸ 1~5 반환 | 최대 500 ms 이상 지연 시 스켈레톤 로더 표시 & 기본 값 3 임시 적용 |
| ④ 중복 검사 | 동일 제목 + 동일 날짜 존재 여부 확인 | 이미 있으면 “동일 항목이 있습니다” 노티, 포커스 이동 |
| ⑤ 데이터 저장 | MVP: localStorage.tasks = JSON.stringify(array)확장: POST /tasks {title, priority…} | 네트워크 실패 시 pending=true 플래그로 오프라인 큐에 저장 |
| ⑥ UI 렌더링 | 우선순위 색상·아이콘 입힌 카드 DOM 생성 | 새 카드가 리스트 가장 위로 slideDown 인서트 |
| ⑦ 수정 플로우 | 카드 › ‘연필’ 아이콘 → 모달 팝업 | 제목 외 필드(설명·기한) 2-way 바인딩 후 Save 시 PUT/PATCH |
// AI 요청 예시
“addTask(title, optionalFields)와 editTask(id, payload)를
로컬 저장·오프라인 큐·서버 동기화를 모두 고려해 작성해 줘.
빈 입력·중복·네트워크 오류 예외처리까지 포함해줘.”
2. 우선순위 & 완료 처리 ― 상태 전환을 ‘보는’ 재미까지
2.1 우선순위 단계 정의
| 단계 | 색상(예시) | 아이콘 | 설명 |
|---|---|---|---|
| 1 | #95a5a6 (회색) | 💭 | “나중에” |
| 2 | #3498db (파랑) | 📄 | “보통” |
| 3 | #f1c40f (노랑) | ⭐ | “주의” |
| 4 | #e67e22 (주황) | ⚡ | “급함” |
| 5 | #e74c3c (빨강) | ❗ | “최우선” |
- 자동 AI 분류 → 초기 배경색·아이콘 자동 세팅
- 수동 드래그 → 카드 왼쪽 엣지
vertical drag로 우선순위 ±1 변경- 드래그 끝에 진동 40 ms(모바일)로 피드백
2.2 완료 토글
- DOM 변화
- 완료 카드:
opacity: 0.5text-decoration: line-through- 우측 체크박스 애니메이션 (Lottie JSON)
- 완료 카드:
- 키보드 접근성
<button aria-pressed="true/false">로 상태 노출Space또는Enter로 토글 가능
“toggleDone(id)` 함수와 완료/복원 애니메이션 CSS 키프레임 예시,
그리고 WAI-ARIA 속성까지 포함해서 작성해줘.”
3. 필터·정렬 UI ― 클릭 두 번이면 원하는 뷰
| 기능 | UX 세부 규칙 |
|---|---|
| 필터 패널 | 모바일: 하단 시트 → dragUp() • 데스크톱: 오른쪽 서랍 |
| 즉시 적용 | 사용자가 옵션 클릭 ▸ 150 ms 딜레이 후 카드 재배치 |
| 조합 가능 | 중요도 × 상태 × 마감기간 다중 필터 가능 |
| 시각 피드백 | 활성 필터는 버튼에 칩(Chip) 뱃지 + 숫자 표기 |
| 상태 저장 | 마지막 필터 JSON → localStorage.filterPref |
“applyFilter(criteria)와 sortTasks(by) 함수를
응답성이 좋은 방식(requestAnimationFrame)으로 작성해줘.
필터 UI 예시는 모바일·데스크톱 두 버전 모두 설명해줘.”
4. 예외·오류 플로우 ― 사용자에게 “왜?”를 알려주자
| 코드 | 상황 | 사용자 알림 | 개발자 로깅 |
|---|---|---|---|
| E-4001 | 입력 공백 | 빨간 테두리 + 스낵바 “내용을 입력해 주세요” | console.warn(‘EMPTY_INPUT’) |
| E-4002 | 중복 항목 | 토스트 “이미 등록된 할 일” | console.info(‘DUPLICATE_TASK’, title) |
| E-5001 | 서버 5XX | 카드에 ⚠️ 태그 + “동기화 실패, 탭해 재시도” | Sentry 전송 |
| E-9001 | AI 분류 실패 | 회색 배지 “AI 미분류” + 직접 우선순위 선택 유도 | log(‘AI_FALLBACK’) |
- UI 원칙 : 사용자 잘못(X) → 책임 회피 NO, 해결 방법 제시 YES
- 재시도 전략 : 지수백오프 2-4-8-16 sec, 5회 후 사용자 알림
5. 데이터 모델 & 저장 전략
5.1 로컬 스키마 (TypeScript 인터페이스 예시)
interface Task {
id: string; // UUID
title: string;
description?: string;
priority: 1 | 2 | 3 | 4 | 5;
dueDate?: string; // ISO 8601
done: boolean;
updatedAt: number; // epoch ms
pending?: boolean; // 오프라인 큐 표시
}
5.2 API 엔드포인트 (확장 버전)
| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | /tasks?limit=50&cursor= | 페이징 목록 |
| POST | /tasks | 새 항목 생성 |
| PATCH | /tasks/:id | 항목 수정(부분) |
| DELETE | /tasks/:id | 삭제 |
- 동기화 로직:
syncTasks()가- 로컬 pending 목록 → 서버로 flush
- 서버 변경분 diff → 로컬 merge
- 버전 충돌:
updatedAt비교, 클라이언트 수정 시 우선 승
“위 API 스펙으로
syncTasks(localTasks) 함수를 JavaScript로 작성하고,
오프라인 큐·버전 충돌·토큰 만료시 재인증 흐름까지 포함해줘.”
정리: AI에게 상세 명세서를 요청하는 템플릿
“다음 항목을 포함한 ‘할 일 자동 분류’ 웹 앱의 상세 기능 명세서를 작성해 줘.
1) 할 일 추가·수정 입력 플로우(중복·빈값 검증 포함)
2) calculatePriority·우선순위 색상/아이콘 매핑 표
3) 완료 토글 애니메이션 & 접근성 태그
4) 필터·정렬 UI 설계(모바일·데스크톱)
5) 예외 코드(E-xxxx)와 사용자 알림 방식
6) Task 인터페이스 + localStorage·REST sync 전략
각 항목마다 코드·UX 모형·오류 처리 로직을 자세히 설명해줘.”
명세서가 완성되면, 해당 문서를 바로 AI에게 “이 기준대로 코드 생성”이라고 넘겨도 되고, 팀 내부 리뷰 후에 최종 승인본을 사용해도 좋습니다
