Architectural Planning Methodology
This skill enables creating comprehensive technical plans for features and changes by discovering and following project architectural patterns.
Leverages: [codebase-analysis] skill for project discovery and pattern recognition.
Planning Philosophy
Integration Over Innovation
- Design solutions that fit naturally into existing architecture
- Respect established boundaries and responsibilities
- Follow discovered organizational patterns
- Use existing libraries and approaches
Clarity and Actionability
- Create plans others can execute without clarification
- Break work into atomic, testable steps
- Identify dependencies and risks explicitly
- Provide clear success criteria
Planning Workflow
중요: 본 스킬을 사용할 때 모든 응답의 최상단에 [PHASE: STRATEGY]를 명시하라.
Phase 1: Architectural Discovery
... (기존 내용) ...
Phase 2: Solution Design & Strategy
Design within discovered constraints:
- Systems Thinking: 로컬 수정이 전체 시스템 및 미래 유지보수에 미칠 영향(Ripple Effect)을 분석한다.
- Multidimensional Trade-off: [성능 / 가독성 / 테스트 용이성 / 미래 확장성]의 3축으로 대안을 평가한다.
- Pre-mortem: 설계가 확정되기 전, "이 설계가 실패할 이유 3가지"를 스스로 나열하고 보완책을 마련한다.
[CRITICAL GATE]: 전략 수립 완료 후 사용자에게 보고하고 **"진행 승인"**을 기다려라. 승인 전까지 write_file, replace 등 파일을 변경하는 어떠한 도구도 호출하지 마라.
Phase 2.5: Risk Mitigation (One-shot PoC)
불확실성이 높은 영역(처음 쓰는 라이브러리, 파괴적 설정 변경 등)이 발견되면:
- Trigger based PoC: 10줄 내외의 독립적인 스크립트로 핵심 동작만 검증한다.
- Review Points: 사용자에게 PoC 결과와 함께 "이 동작이 의도하신 바와 일치하는지" 확인을 요청하는 리뷰 포인트를 제시한다.
- Decision Gate: PoC 결과와 전략에 대해 사용자 승인을 받은 후 구현(Phase 3)으로 넘어간다.
Phase 3: Implementation Planning
... (기존 내용) ...
Create actionable steps:
- Order tasks by dependency and logical progression
- Specify exact files to modify or create
- Reference existing code as implementation examples
- Identify potential conflicts or breaking changes
- Plan validation and testing approach
Plan Structure Guidelines
Essential Elements
Context Section:
- Discovered architecture pattern
- Technology stack
- Similar existing features
- Integration points
Approach Section:
- High-level solution
- Why it fits the architecture
- New vs existing components
- Pattern references
Implementation Section:
- Atomic, ordered steps
- File paths (create/modify)
- Code examples from codebase
- Rationale for each step
Risk Section:
- Dependencies (internal/external)
- Potential issues and mitigations
- Breaking changes and migrations
- Performance impact
Validation Section:
- Testing strategy
- Success criteria
- Manual verification steps
Planning Best Practices
Reference Real Examples
✅ "Following the UserService pattern in services/user.service.ts,
OrderService will inject repositories via constructor and
use the same error handling approach."
❌ "Create OrderService using dependency injection."
Be Specific About Locations
✅ "Create auth/middleware/jwt-validator.ts following the
pattern from auth/middleware/session-validator.ts"
❌ "Add JWT validation middleware"
Quantify When Possible
✅ "Affects 3 API endpoints and 2 background jobs.
Estimated: 2-3 hours implementation + 1 hour testing."
❌ "This will take some time to implement."
Identify Patterns, Not Just Tasks
✅ "Implement using the Command pattern like existing
payment/commands/ProcessPayment.java uses"
❌ "Implement the feature"
Common Architectural Patterns
Layered Architecture
Plan should respect layers:
- API/Presentation → UseCase/Application → Infrastructure → Domain
- Dependencies flow inward
- Each layer uses only the layer below
Microservices
Plan should consider:
- Service boundaries
- Inter-service communication patterns
- Data consistency approaches
- Shared libraries vs duplication
Hexagonal/Clean Architecture
Plan should:
- Keep business logic in core
- Adapt external dependencies at boundaries
- Use dependency inversion
- Preserve testability
Event-Driven
Plan should:
- Identify events to publish/consume
- Follow existing event schemas
- Use project's message infrastructure
- Consider eventual consistency
Anti-Patterns to Avoid
❌ Generic Plans:
- "Add authentication" without specifying how it integrates
✅ Context-Specific Plans:
- "Extend existing OAuth2 middleware in auth/oauth2.go to support refresh tokens, following the pattern from auth/session.go"
❌ Technology Mismatch:
- Recommending GraphQL when project uses REST
✅ Technology Alignment:
- "Add REST endpoint to api/v1/orders.ts following OpenAPI spec pattern from api/v1/users.ts"
❌ Ignoring Existing Solutions:
- Creating new pagination when project has existing implementation
✅ Leverage Existing:
- "Use existing utils/pagination.ts helper, same as services/user-service.ts uses"
Quality Checklist
Before finalizing plan:
- [ ] Have I identified the architectural pattern?
- [ ] Does the solution fit naturally into existing structure?
- [ ] Are all steps grounded in discovered conventions?
- [ ] Have I referenced specific existing code as examples?
- [ ] Are integration points clearly identified?
- [ ] Is each step atomic and testable?
- [ ] Have I considered risks and provided mitigations?
- [ ] Will someone unfamiliar with my thinking understand this plan?
Plan Templates
For detailed templates and architecture-specific examples, see:
- templates.md - Full plan template and common scenarios
Remember: A great plan reads like it was written by someone deeply familiar with the codebase. Use the [codebase-analysis] skill to become that familiar before planning.
Mandatory: Tone & Reference Policy
- 모든 기술적 주장/판단에 출처 명시 (공식 문서 URL, GitHub issue, RFC 등)
- 출처 없는 주장은 "출처 미확인 — 검증 필요"로 표기
- "~일 수 있습니다", "아마도", "대체로" 등 hedging 표현 금지. 확인 상태를 명시.
- 톤: 간결, 사실 중심. 불필요한 수식어 배제.
- 추론이 아닌 실제 확인된 사실만으로 분석/설계 진행.
Mandatory: Code Principles (설계 시 반영)
- TDD: 테스트 전략을 설계 단계에서 함께 수립
- SSoT/DRY: 중복 제거 관점에서 설계
- SRP: 모듈/서비스 책임 분리 명확화
- DDD: 도메인 모델 중심 설계, Bounded Context 명시
- Functional: 상태 관리 최소화, 순수 함수 우선 설계