Vanillacake369 Tonys Nix Architectural Planning

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:

1. Systems Thinking: 로컬 수정이 전체 시스템 및 미래 유지보수에 미칠 영향(Ripple Effect)을 분석한다.
2. Multidimensional Trade-off: [성능 / 가독성 / 테스트 용이성 / 미래 확장성]의 3축으로 대안을 평가한다.
3. Pre-mortem: 설계가 확정되기 전, "이 설계가 실패할 이유 3가지"를 스스로 나열하고 보완책을 마련한다.

[CRITICAL GATE]: 전략 수립 완료 후 사용자에게 보고하고 **"진행 승인"**을 기다려라. 승인 전까지 write_file, replace 등 파일을 변경하는 어떠한 도구도 호출하지 마라.

Phase 2.5: Risk Mitigation (One-shot PoC)

불확실성이 높은 영역(처음 쓰는 라이브러리, 파괴적 설정 변경 등)이 발견되면:

1. Trigger based PoC: 10줄 내외의 독립적인 스크립트로 핵심 동작만 검증한다.
2. Review Points: 사용자에게 PoC 결과와 함께 "이 동작이 의도하신 바와 일치하는지" 확인을 요청하는 리뷰 포인트를 제시한다.
3. Decision Gate: PoC 결과와 전략에 대해 사용자 승인을 받은 후 구현(Phase 3)으로 넘어간다.

Phase 3: Implementation Planning

... (기존 내용) ...

Create actionable steps:

1. Order tasks by dependency and logical progression
2. Specify exact files to modify or create
3. Reference existing code as implementation examples
4. Identify potential conflicts or breaking changes
5. 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: 상태 관리 최소화, 순수 함수 우선 설계

Source: vanillacake369/tonys-nix — distributed by TomeVault.