| name | boolti-feature-planner |
| description | 불티 프로젝트의 기능 개발(새 화면, ViewModel/Repository/UseCase, API 연동, 디자인 적용 등 신규 작업)을 phase 기반 계획에 따라 컨벤션을 지키며 진행한다. 단순 버그 수정·문구 변경·소규모 리팩토링에는 사용하지 않는다. 키워드: 기능 추가, 화면 추가, feature 구현, plan, planning. |
불티 기능 개발 플래너
불티 프로젝트의 기능을 phase 기반 계획에 따라 컨벤션을 지키며 구현한다.
⚠️ 핵심 원칙
모든 구현 작업은 반드시 계획부터 시작한다. 간단한 구현이라도 예외 없음.
- 계획 없이 바로 코드 수정 금지
- 사용자 승인 전까지 구현 시작 금지
- 각 phase 완료 후 Quality Gate 통과 전까지 다음 phase 진행 금지
워크플로우
Step 1: 컨벤션 로드
CLAUDE.md(프로젝트 루트)를 단일 진실 공급원(single source of truth)으로 삼는다. 모듈 구조, 코드 위치 가이드, 패턴, API 규칙은 모두 거기에 있다. 추가로 작업 영역과 유사한 기존 구현 1~2개를 읽어 코드 스타일을 파악한다.
Step 2: 요구사항 분석
- 관련 파일 읽고 기존 구조와 패턴 파악
- 영향받는 모듈, 의존성, 통합 지점 식별
- 복잡도 판단 (Small / Medium / Large)
- API 작업이면 https://dev.api.boolti.in/v3/api-docs/app 스펙을 먼저 확인
Step 3: Phase 분할
3~7개 phase로 분할한다. 각 phase 조건:
- 1~4시간 분량
- 단독 빌드/실행 가능한 결과물 산출
- 명확한 성공 기준
- 개별 롤백 가능
각 phase는 다음을 포함한다.
- Goal (이 phase가 만들어 내는 동작 가능한 결과)
- Tasks (선택적 TDD: 필요한 경우만 RED → GREEN → REFACTOR)
- Quality Gate 체크리스트
- 의존성, 롤백 방법
Step 4: 계획 문서 작성
plan-template.md 형식을 따라 docs/plans/PLAN_<feature-name>.md를 생성한다.
docs/plans/ 디렉토리가 없으면 생성- 파일명은 kebab-case (예:
PLAN_show-detail-screen.md)
Step 5: 사용자 승인 (필수)
AskUserQuestion으로 명시적 승인을 받는다.
- "Phase 분할이 적절한가?"
- "우려되는 부분이 있는가?"
- "이대로 진행해도 좋은가?"
승인 받기 전까지 절대 구현 시작 금지.
Step 6: Phase 별 실행
승인 후 phase 순서대로 실행한다.
- 해당 phase 작업 수행
- 완료한 task의 checkbox 표시
- Quality Gate 실행:
bash .claude/skills/boolti-feature-planner/scripts/quality-gate.sh
- 실패 시 멈추고 수정 후 재실행
- 모두 통과해야 다음 phase로 진행
플래너 전용 규칙
CLAUDE.md에 없는, 이 스킬에서만 강제하는 규칙.
의존 방향 (위반 절대 금지)
- presentation → domain (data 직접 참조 금지)
- data → domain
- domain은 Android/외부 의존 없음 (pure Kotlin)
코드 품질 차단 항목 (Quality Gate에서 자동 검출)
- 와일드카드 import
- 프로젝트 클래스(
com.nexters.boolti.*)를 fully-qualified name으로 직접 사용
Compose 작성/수정 시
verify-compose-conventions 스킬 실행 (사용자 글로벌 스킬, ~/.claude/skills/)
Quality Gate
각 phase 완료 후 다음 스크립트를 실행해 모두 통과해야 한다.
bash .claude/skills/boolti-feature-planner/scripts/quality-gate.sh
스크립트가 실행하는 검증:
| 항목 | 명령 | 차단 여부 |
|---|
| 빌드 | ./gradlew assembleDebug | 차단 |
| 단위 테스트 | ./gradlew btTest | 차단 (테스트 추가/수정한 경우) |
| Ktlint | ./gradlew ktlintCheck | 차단 (도입 후) |
| 와일드카드 import | scripts/check-imports.sh | 차단 |
| Full path 사용 | scripts/check-fullpath.sh | 경고 |
Ktlint 미설치 시 처리
./gradlew ktlintCheck 실행 시 task가 없다는 에러가 발생하면:
- 사용자에게 알린다: "Ktlint가 설정되어 있지 않습니다. 도입할까요? (baseline 적용으로 기존 코드는 무시, 신규 코드만 검사)"
- 승인 시 다음 작업 수행
- 루트
build.gradle.kts에 org.jlleitschuh.gradle.ktlint plugin 추가
- 각 모듈에 plugin 적용
./gradlew ktlintCheck 1회 실행해 violation 확인./gradlew ktlintGenerateBaseline 으로 baseline 생성 (기존 violation을 baseline에 등록)- 다시
ktlintCheck 실행해 통과 확인
- 거부 시 ktlint 단계는 skip하고 진행
다른 도구(Spotless, detekt 등)도 동일한 절차: 사용자 승인 후 설치, baseline 가능하면 사용.
선택적 TDD
Boolti는 strict TDD를 강제하지 않는다. 다음 기준으로 판단한다.
테스트 작성 권장
- Domain UseCase (pure Kotlin, 비즈니스 로직)
- Repository 구현체의 데이터 변환 로직
- 복잡한 ViewModel 상태 전이 (조건 분기 多)
- 회귀 위험이 큰 영역
테스트 작성 면제
- 단순 데이터 클래스 (data class만 정의)
- Compose UI (Preview로 대체)
- 단순 위임 코드 (UseCase가 Repository를 그대로 호출만)
- "당연한" 테스트 (getter가 값 반환하는지 같은)
판단 기준: "이 테스트가 미래에 회귀를 잡아낼 수 있는가?"가 의심되면 작성하지 않는다.
테스트 작성한 phase에서만 Quality Gate의 btTest 통과 필요. 작성 안 했으면 변경 영향이 있을 수 있는 모듈만 테스트 실행해도 됨.
참고 파일
- plan-template.md — 계획 문서 템플릿
scripts/quality-gate.sh — 전체 검증 실행scripts/check-imports.sh — 와일드카드 import 검출scripts/check-fullpath.sh — Fully-qualified class name 사용 검출
