Feature Development Workflow

Systematic approach: understand codebase → clarify requirements → design → implement.

Core Principles

• Ask clarifying questions: Identify all ambiguities before implementation
• Understand before acting: Read existing code patterns first
• Library-First: Search for existing solutions before custom code
• Simple and elegant: Prioritize readable, maintainable code
• Use TodoWrite: Track all progress

Execution Mode

New feature (기본): Phase 1부터 전체 실행 Modify feature: 기존 기능 수정 시. Phase 2(Exploration)부터 시작. 기존 스펙 문서를 먼저 읽고, 새 문서를 만들지 않고 Changelog를 추가한다.

Modify 모드 진입 조건: 사용자가 기존 기능의 변경/확장을 요청하고, docs/plans/에 해당 기능의 스펙 문서가 이미 존재하는 경우.

Phase Overview

Phase 1: Discovery        → What are we building? (Modify 모드: 스킵 — 기존 스펙 문서 참조)
Phase 2: Exploration      → How does existing code work?
Phase 3: Questions        → What's unclear? (DON'T SKIP!)
Phase 4: Architecture     → How should we build it?
Phase 5: Implementation   → Build it (after approval)
Phase 6: Review           → Is it good?
Phase 7: Documentation    → Update spec doc with Changelog (DON'T SKIP!)

For detailed steps in each phase, see references/phase-details.md.

Key Phase Summaries

Phase 1-2: Discovery & Exploration

Create todo list → Launch parallel code-explorer agents → Build deep understanding

Phase 3: Clarifying Questions ⚠️ CRITICAL

Identify ALL underspecified aspects → Present questions → Wait for answers

Phase 4: Architecture Design

Launch parallel architect agents (Minimal / Clean / Pragmatic) → Present trade-offs → Ask user preference

Phase 4.5: Implementation Gate (Devil's Advocate - 경량)

구현 돌입 전 30초 체크 — 아래 2가지를 사용자에게 간결하게 공유:

• "이 설계에서 가장 먼저 깨질 부분은 어디인가?" (1문장)
• "테스트하기 가장 어려운 부분은?" (1문장)

블로커가 아닌 인지 도구. 1-2문장으로 답하고 바로 Phase 5로 진행. 심각한 문제가 발견되면 Phase 4로 돌아가서 설계 수정.

Phase 5: Implementation

⛔ DO NOT START WITHOUT USER APPROVAL Library-first → Follow codebase conventions → Update todos

Phase 6-7: Review & Documentation

Launch reviewer agents → Address findings →

• New feature: docs/plans/NNNN.YYYY-MM-DD-<feature>-summary.md 생성 (NNNN: 해당 폴더 내 최대 번호 + 1, 없으면 0001)
• Modify feature: 기존 스펙 문서에 Changelog 항목 추가 (새 문서 생성 금지)

Changelog 포맷:

## Changelog

### vN — YYYY-MM-DD
**변경**: 무엇을 변경했는지 (1줄)
**이유**: 왜 변경했는지 (1줄)
**영향 범위**: 변경된 모듈/파일 목록
**관련 커밋**: conventional commit 메시지

Implementation Guidelines

Follow Karpathy Guidelines for all code changes. See references/karpathy-guidelines.md.

Key points:

• Think before coding, state assumptions explicitly
• Implement only what's requested (YAGNI)
• Surgical changes — don't "improve" adjacent code
• Verifiable goals for every change

문서화 (Phase 7 완료 후 자동 실행)

작업 완료 시 auto-documenter를 호출하여 프로젝트 문서를 업데이트한다.

Completion

• New feature: Phase 7 완료: 기능 구현 + 리뷰 통과 + docs/plans/NNNN.YYYY-MM-DD-<feature>-summary.md 생성.
• Modify feature: Phase 7 완료: 기능 수정 + 리뷰 통과 + 기존 스펙 문서에 Changelog 항목 추가.

Anti-Patterns to Avoid

• NIH (Not Invented Here): Rebuilding what already exists
• Premature Optimization: Unnecessary optimization
• Over-Engineering: Excessive abstraction for simple tasks
• Skipping Questions: Making assumptions instead of asking

Troubleshooting

User says "just do it" when asked clarifying questions: Provide your best recommendation with stated assumptions. Document assumptions in the summary so they can be corrected later. Codebase has no clear patterns to follow: Fall back to the project's language/framework conventions. Document the new pattern as a precedent. Phase 5 implementation diverges from Phase 4 design: Stop, compare, and ask user whether to adjust design or revert implementation. Never silently deviate from approved architecture.