plan

Plan

심층 인터뷰를 통해 해결하려는 문제를 파악하고, 기능의 동작을 Concept 단위로 분해하여 Spec 문서를 작성합니다.

출력 구조

~/Projects/flex/til/spec/{feature-name}/
├── {FEATURE-NAME}.md    # Index — 문제 정의, 전체 동작, concept 링크
└── concepts/
    ├── {name}.md        # 개별 동작 명세
    └── ...

Workflow

Phase 1: 주제 수집

• 사용자로부터 인터뷰 주제를 텍스트, Linear URL, Notion URL, Figma URL 등으로 받습니다
• Linear URL → 이슈 상세 로드
• Notion URL → 문서 로드
• Figma URL → 디자인 문서 로드
• 주제가 명확하지 않으면 AskUserQuestion으로 명확히 합니다
• 기존 ~/Projects/flex/til/spec/ 디렉토리에 관련 스펙이 있는지 확인합니다 (Glob 사용)

Phase 2: 문제 정의 인터뷰

목표: "왜 이 기능이 필요한가", "누구를 위한 것인가", "어떤 문제를 해결하는가"를 명확히 한다.

질문 방향:

• 현재 사용자가 겪고 있는 문제는 무엇인가?
• 이 문제로 인해 어떤 불편함이 발생하는가?
• 이 문제 해결을 통해 어떤 가치를 창출하려 하는가?
• 이 기능의 성공 기준은 무엇인가?

질문 방식:

• AskUserQuestion 툴 사용, 한국어
• 다양한 각도에서 문제를 탐색하는 후속 질문 생성
• 문제 정의가 명확해질 때까지 반복
• 답변에 따라 follow-up 질문 생성

Phase 3: 동작 심층 인터뷰

목표: 기능의 구체적인 동작, UX 플로우, 에지 케이스를 파악한다.

질문 카테고리:

• 사용자 플로우: 시작점, 분기, 완료 조건, 취소/되돌리기
• 에지 케이스: 예외 상황, 경계 조건, 동시성, 빈 상태
• 인터랙션 디테일: 로딩, 에러 표시, 성공 피드백, 애니메이션
• 데이터 제약: 최대/최소값, 필수/선택, 형식 제한
• 권한/조건: 접근 권한, feature flag, 사전 조건

질문 가이드라인:

• 명백하거나 피상적인 질문 금지
• 구현 상세(파일명, 함수명, 라이브러리)가 아닌 동작에 집중
• "만약 ~한 상황이라면?" 형태의 시나리오 기반 질문
• "왜?"를 3번 이상 물어볼 수 있는 깊이의 질문

좋은 질문 예시:

• "사용자가 폼 작성 중 네트워크가 끊겼을 때, 작성 중이던 데이터는 어떻게 되어야 하나요?"
• "1000개 이상의 아이템이 있을 때 리스트는 어떻게 표시되어야 하나요?"
• "모달 안에서 또 다른 확인 다이얼로그가 필요한 경우가 있나요? 있다면 어떤 경우인가요?"
• "저장 실패 시 사용자에게 어떤 피드백을 주어야 하나요? 재시도 옵션이 필요한가요?"

피해야 할 질문:

• "어떤 기술 스택을 사용할 건가요?"
• "컴포넌트 구조를 어떻게 설계하시겠습니까?"
• "API 엔드포인트는 어떻게 구성하나요?"

Phase 4: Concept 식별

인터뷰 답변을 분석하여 기능을 **동작 단위(Concept)**로 분해합니다.

Concept 분해 기준:

• 하나의 Concept = 하나의 온전한 동작 단위
• 개발 단위가 아닌 동작 단위 (예: "테이블 동작", "검색 동작", "에러 처리 동작")
• 각 Concept은 독립적으로 테스트할 수 있어야 함
• 다른 Concept과의 관계가 명확해야 함

식별 절차:

1. 인터뷰 답변에서 동작 키워드 추출
2. 유사한 동작을 클러스터링
3. 각 클러스터에 Concept 이름 부여
4. Concept 간 의존관계 파악

Phase 5: Concept 확인

식별된 Concept 목록을 사용자에게 제시하고 확인받습니다.

다음과 같이 Concept을 분류했습니다:

1. **table** — 테이블 행 추가/수정/삭제, 정렬, 페이지네이션
2. **search** — 검색 필터, 자동완성, 결과 표시
3. **error-panel** — 유효성 검증 에러, 서버 에러 표시

수정하거나 합치고 싶은 Concept이 있나요?

• 사용자가 합치기/분리/이름 변경을 요청하면 반영
• 빠진 동작이 있는지 확인

Phase 6: 문서 작성

확정된 Concept 목록으로 Spec 문서를 작성합니다.

{FEATURE-NAME}.md — templates/SPEC.md 형식 참조:

• 파일명은 feature name을 대문자 + 하이픈으로 (예: STREAMING-ANIMATION.md)
• 제목의 feature name은 대문자로 작성 (예: # MARKDOWN ANIMATION - Spec)
• 문제 정의 (Phase 2에서 수집)
• 전체 동작 설명
• Concepts 테이블 (각 concept 파일 링크)
• Decision Log (빈 테이블) — plan 단계에서는 엔트리를 채우지 않음. Decision Log는 review 단계(/drill:review)에서 Spec과 구현의 차이가 발견될 때만 작성
• 피그마/노션 참조 링크

concepts/{name}.md — templates/CONCEPT.md 형식 참조:

• 이 동작이 해결하는 문제
• SHOULD: 기본 동작, 사용자 플로우 (ASCII 다이어그램), 에지 케이스
• SHOULD NOT: 금지 동작 + 이유
• 관련 Concept 링크

문서 작성 원칙:

• 동작 명세만 포함: 사용자 플로우, 에지 케이스, SHOULD/SHOULD NOT
• 구현 상세 제외: 파일 경로, 코드 스니펫, 함수명, 컴포넌트명 등
• 구체적 코드명 사용 금지: subscribeToTask → "재구독 호출", MessageList.tsx → "메시지 리스트"
• 사용자 플로우는 ASCII 다이어그램으로 표현
• Concept 간 관계는 관련 Concept 섹션에 상대 경로 링크로 표현

저장 위치: ~/Projects/flex/til/spec/{feature-name}/ (프로젝트 루트 기준)

Phase 7: 최종 확인

스펙 문서 작성 후:

• 사용자에게 스펙 문서 경로 안내
• Concept별 핵심 SHOULD/SHOULD NOT 요약 제공
• 추가 인터뷰 필요 여부 확인
• 다음 단계 안내: /drill:prepare로 티켓 생성

인터뷰 진행 흐름

1. 주제 수집 (Linear/Notion/Figma/텍스트)
   ↓
2. 문제 정의 인터뷰
   ↓
3. 동작 심층 인터뷰
   ├─ 사용자 플로우
   ├─ 에지 케이스
   ├─ 인터랙션 디테일
   └─ 데이터 제약/권한
   ↓
4. Concept 식별 (답변 클러스터링)
   ↓
5. Concept 확인 (사용자 검증)
   ↓
6. 문서 작성 ({FEATURE-NAME}.md + concepts/*.md)
   ↓
7. 최종 확인

인터뷰 완료 판단

다음 조건이 모두 충족되면 인터뷰 종료:

• 모든 Concept에 SHOULD/SHOULD NOT이 정의됨
• 각 Concept의 주요 사용자 플로우가 파악됨
• 에지 케이스가 충분히 수집됨
• 더 이상 중요한 미결 질문이 없음

중요 사항

• 언어: 모든 질문과 커뮤니케이션은 한국어로 진행
• 동작 중심: 구현이 아닌 동작에 집중. "어떻게 만들 것인가"가 아니라 "어떻게 동작해야 하는가"
• 연속성: 답변에 따라 자연스럽게 이어지는 follow-up 질문 생성
• 유연성: 사용자의 답변에 따라 질문 방향을 조정

에러 처리

• 사용자가 답변을 모르는 경우: 대안 제시 및 함께 고민
• 범위가 너무 넓어지는 경우: 우선순위 조정 제안, Concept 분리 검토
• Linear/Notion/Figma 접근 실패: 텍스트 기반으로 진행