기능 개발 프로세스

핵심 원칙: 에이전트가 스스로 결정을 내리는 횟수가 적을수록 결과는 더 안정적입니다. 각 단계는 docs/features/<slug>/ 디렉토리에 산출물을 생성하고 검증('게이트')을 거칩니다. 표시된 곳에서는 사람의 확인 후에야 다음 단계로 넘어갑니다.

코드 작성 방법은 fsd-frontend를 따르고, 불필요한 코드 확인은 anti-slop-review를, 세션 시작 및 인증은 frontend-auth-session을 참조하세요.

1. 단계

#	단계	산출물	승인자	게이트
0	준비	브랜치	—	워킹 트리가 깨끗함; 의존성 설치 및 마이그레이션 후 `/clear` 실행
1	PRD	`prd.md`	사람	Non-Goals가 작성됨; 검증 가능한 기준; 기술적 해결책 없음
2	사양서	`spec.md` (최대 150줄)	사람	PRD의 모든 기준을 포함하며 그 이상은 없음
3	태스크	`tasks.md`	사람	하나의 태스크는 하나의 커밋; 첫 번째 태스크는 트레이서 불릿
4	리서치	`tasks.md` 내 로그	—	읽기 전용; 재사용할 내용 발견
5	트레이서 불릿	커밋	—	하나의 시나리오가 전체를 통과하여 브라우저에서 확인 가능
6	빌드	태스크당 커밋	—	로직은 테스트 우선; `pnpm check` 통과
7	리뷰	`reviewer` 보고서	사람 (발견 사항 기반)	확인된 발견 사항이 수정됨
8	브라우저	크리티컬 패스 E2E	—	PRD 시나리오가 콘솔 에러 없이 통과

작은 태스크(하나의 커밋, 사용자에게 새로운 동작 없음)는 1~3단계를 건너뛸 수 있지만, Non-Goals는 여전히 태스크 설명에 기록되어야 합니다. 단계를 건너뛸 때는 반드시 명시적으로 언급하고, 조용히 넘어가지 않습니다.

2. PRD

템플릿: docs/features/_template/prd.md

에이전트는 요청을 바탕으로 초안을 작성하고, 진행을 위해 반드시 필요한 경우에만 질문합니다. 나머지는 '미해결 질문'에 가정으로 기록되며, 사용자가 승인 시 확인합니다.
Non-Goals는 필수입니다. 에이전트가 '덤으로' 하고 싶어할 만한 것들을 나열하세요: 새로운 크기에 대한 반응형, 애니메이션, i18n, 캐싱, 관리자 페이지, 인접 코드 리팩토링 등. 이 목록이 없으면 기능이 점점 커집니다.
완료 기준은 검증 가능해야 합니다: 'Given / When / Then' 형식을 사용하고, '편리한' 또는 '빠른'과 같은 모호한 표현은 피합니다.
라이브러리, 파일, 스키마에 대한 논의는 없습니다: '무엇을 그리고 왜'에 집중하고, '어떻게'는 다루지 않습니다.

3. 사양서

템플릿: docs/features/_template/spec.md

최대 150줄. 에이전트가 작성하고 사람이 승인합니다. 길고 자동 생성된 사양서는 없는 것보다 못합니다: 컨텍스트를 소모하고 결정을 흐리게 만듭니다.
작성 전에 영향을 받는 레이어를 짧게 읽기 전용으로 검토합니다: 이미 있는 것, 재사용할 수 있는 것.
포함 내용: 코드 위치(레이어, 슬라이스), 데이터 계약(Zod 스키마, DTO 매핑), API(입력, 출력, 오류 → kind), UI 상태, 경계 케이스, 테스트 레벨이 포함된 승인 시나리오.
사양서는 코드와 함께 살아있습니다. 동작이 변경되면 동일한 커밋에서 spec.md를 수정합니다. 사양서와 다른 코드는 둘 중 하나에 결함이 있음을 의미합니다.

4. 태스크

템플릿: docs/features/_template/tasks.md

하나의 태스크는 하나의 커밋이며, 커밋 후에는 프로젝트가 빌드되고 검사를 통과해야 합니다. 에이전트가 막다른 골목에 도달하면, 모델과 논쟁하는 것보다 이전 커밋으로 롤백하는 것이 더 저렴합니다.
각 태스크는 하나의 세션에 들어맞아야 하며, 각각 '완료 조건'이 있어야 합니다.
첫 번째 태스크는 트레이서 불릿이고, 그 다음은 상태 처리, 경계 케이스, 폴리싱 순서입니다.

5. 리서치 (읽기 전용)

각 태스크 전에, 파일을 수정하지 않고 다음을 수행합니다:

영향을 받는 폴더의 AGENTS.md 읽기;
유사한 문제를 해결하는 기존 코드 검색(rg로 이름과 계약 검색);
태스크가 의존하는 계약과 타입 확인.

발견한 내용이 나중에 필요하면 tasks.md 로그에 2~3줄을 추가합니다.

6. 트레이서 불릿

하나의 시나리오를 전체적으로 구현합니다: 라우트 → 페이지 → 기능 또는 엔티티 → request() → 라우트 핸들러 또는 백엔드 → 화면에 결과 표시.

프로덕션 코드여야 하며 프로토타입이 아닙니다: 올바른 레이어, 사양서의 실제 계약을 사용합니다.
의도적으로 생략: 상세한 유효성 검사, 로딩 및 오류 상태 폴리싱, 스타일, 경계 케이스.
백엔드가 준비되지 않은 경우: 사양서의 계약에 따라 데이터를 반환하는 MSW 핸들러 또는 라우트 핸들러를 사용하고, 이를 tasks.md에 기록합니다.
검증: 브라우저에서 시나리오가 실행되고 콘솔에 오류가 없는지 확인합니다.

7. 빌드

로직은 테스트 우선: 순수 함수, 스토어, 응답 매핑, 분기가 있는 훅. 테스트는 예상된 이유로 실패해야 하고, 그 다음에 코드를 작성합니다. 코드 이후에 작성된 테스트는 요구사항이 아닌 코드의 동작을 검증하는 경향이 있습니다.
마크업과 스타일은 사전 테스트 없음: 브라우저(8단계)에서 검증하며, 크리티컬 패스는 E2E로 커버합니다.
태스크 완료 후: pnpm check 실행, 커밋(lint-staged가 변경된 파일 검사).
중단: 동일한 문제를 세 번 수정에 실패하면 중단합니다. 시도한 내용과 가설을 사람에게 설명합니다. 테스트를 코드에 맞추지 말고, 린터 규칙을 비활성화하지 말고, 타입을 약화시키지 마십시오.
태스크 범위를 벗어난 모든 것은 '나중에' 로그에 기록하고, 이 커밋에 포함하지 마십시오.

8. 리뷰

서브 에이전트 reviewer(.claude/agents/reviewer.md)를 깨끗한 컨텍스트로 사용합니다: prd.md와 spec.md의 경로, 그리고 커밋 범위를 전달합니다. diff는 리뷰어가 직접 읽습니다. 코드 작성자는 자신의 실수를 잘 발견하지 못합니다: 자신의 컨텍스트에는 해결책이 옳다고 생각하는 논리가 있기 때문입니다.
확인된 발견 사항은 수정하고, 논쟁의 여지가 있는 것은 사람이 결정합니다.
보안은 사람도 확인합니다: 로그인, 세션, 리디렉션, 쿠키, HTML 내 사용자 입력. 자동화된 검사가 이를 보장하지는 않습니다: 실제로 오픈 리디렉션이 테스트를 통과하거나, 읽을 수 없는 오류 페이지가 린터를 통과하는 경우가 있었습니다.

9. 브라우저

Next.js: agent-browser를 포함하는 next-dev-loop 스킬 사용(설치된 경우); 그렇지 않으면 Playwright 또는 Chrome DevTools MCP를 사용합니다.
PRD 시나리오를 실행하되, 부정적인 경우도 포함합니다: 빈 데이터, 네트워크 오류, 재전송. 콘솔과 요청 상태를 확인합니다.
UI: 라이트/다크 테마, 모바일 너비에서 확인합니다.
크리티컬 패스는 e2e/ 디렉토리에 E2E 테스트로 작성합니다.
완료 조건: PRD의 모든 기준이 검증됨; 최종 메시지에 기준 목록과 각 기준의 검증 방법을 포함합니다.

10. 컨텍스트

작업 상태는 docs/features/<slug>/ 디렉토리에 저장되며, 대화 기록에 남지 않습니다: 새 세션은 prd.md, spec.md, tasks.md를 읽는 것으로 시작합니다.
잡음이 많은 단계(설치, 마이그레이션, 긴 로그) 후에는 /clear를 실행합니다.
병렬 실험은 git worktree를 사용하고, 작업 브랜치에서는 하지 않습니다.

11. 하지 말아야 할 것

무한한 확인 질문: 진행을 막는 것만 질문하고, 나머지는 PRD에 가정으로 기록합니다.
여러 에이전트로 구성된 오케스트레이터: 실행자와 리뷰어만으로 충분합니다.
아무도 승인하지 않고 읽지 않는 사양서와 문서.
조용히 단계를 건너뛰거나 '덤으로 수정'하는 행위.

rbikbov/frontend-starter

frontend-starter란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서