Big Changes
Complete restructure workflow for major pivots requiring full documentation overhaul.
When to Use Big Changes
Use the Big Changes workflow when:
- Restructuring the entire app architecture
- Major pivot in functionality or purpose
- Existing documentation is significantly outdated
- Need to recreate all AI documentation from scratch
- Changing core technologies (framework, database, etc.)
This is the most comprehensive workflow, typically taking weeks to complete.
Overview
Big Changes requires recreating all documentation before development:
- Architecture Planning: Use Claude Code in plan mode to design the new structure
- Documentation Overhaul: Recreate all
ai_docs/files - Phase Planning: Create new phase documents for implementation
- Phased Development: Execute using Phase Development workflow
Step 1: Plan Architecture with Claude Code
Start Claude Code on the repository and switch it to plan mode, so Claude proposes an approach without editing any files. Describe your restructure goals and ask for a complete architecture document.
Prompt for planning a major restructure
Claude promptI need to restructure my app [app-name]. Here's the current state and what I want to achieve:
**Current State:**
- [Brief description of current app]
- [Current tech stack]
- [Main pain points or reasons for restructure]
**Goals:**
- [What the app should become]
- [New features or capabilities]
- [Technical improvements needed]
**Constraints:**
- [Timeline constraints]
- [Must keep certain features]
- [Technical limitations]
Please create a comprehensive restructure plan including:
1. New architecture overview
2. Data model changes
3. API/route changes
4. UI/UX changes
5. Migration strategy
6. Risk assessment
Format this as a detailed architecture document.
Step 2: Recreate Documentation
After planning, you need to recreate all AI documentation files. Use the following checklist and prompts.
Documentation Checklist
App Root Files
| File | Purpose | Status |
|---|---|---|
README.md | App overview, setup instructions | ☐ |
CLAUDE.md | AI development guidelines for this app | ☐ |
PLAN.md | Development status and phase tracking | ☐ |
ai_docs/ Directory
| File | Purpose | Status |
|---|---|---|
README.md | Documentation index and reading order | ☐ |
00_product_brief.md | Goals, users, success metrics | ☐ |
01_user_experience.md | User flows, screens, interactions | ☐ |
02_architecture.md | Technical decisions, patterns | ☐ |
03_data_contract.md | Database schema, API contracts | ☐ |
04_integrations.md | External services, APIs | ☐ |
05_runbook.md | Deployment, operations, monitoring | ☐ |
06_acceptance_tests.md | Test scenarios, quality criteria | ☐ |
Phase Plans
| File | Purpose | Status |
|---|---|---|
plans/README.md | Phase plan directory overview | ☐ |
plans/phase-1-*.md | First implementation phase | ☐ |
Prompts for Each Document
Create product brief (00_product_brief.md)
Claude promptBased on the architecture plan we created, please write the product brief document for [app-name].
Include:
- Product vision and goals
- Target users and personas
- Core features (must-have vs nice-to-have)
- Success metrics and KPIs
- Out of scope items
Format as markdown for 00_product_brief.md
Create user experience doc (01_user_experience.md)
Claude promptBased on the architecture plan, please write the user experience document for [app-name].
Include:
- User flows (step-by-step journeys)
- Screen descriptions and wireframes
- Navigation structure
- Interaction patterns
- Error states and edge cases
Format as markdown for 01_user_experience.md
Create architecture doc (02_architecture.md)
Claude promptBased on our planning, please write the architecture document for [app-name].
Include:
- System overview diagram (ASCII or description)
- Technology stack decisions with rationale
- Directory structure
- Key patterns and conventions
- Performance considerations
- Security considerations
Format as markdown for 02_architecture.md
Create data contract doc (03_data_contract.md)
Claude promptBased on our planning, please write the data contract document for [app-name].
Include:
- Database schema (tables, relationships)
- API endpoints (routes, methods, payloads)
- Data validation rules
- Migration strategy from old schema
Format as markdown for 03_data_contract.md
Step 3: Create Phase Documents
Break down the implementation into phases. Each phase should be 1-2 weeks of work.
Create phase breakdown
Claude promptBased on the complete documentation we've created, please break down the implementation into phases.
Typical phases:
- Phase 1: Foundation (project setup, core infrastructure)
- Phase 2: Core features (main functionality)
- Phase 3: Secondary features
- Phase 4: Polish and optimization
For each phase, provide:
1. Goal and deliverable
2. List of tasks
3. Dependencies on previous phases
4. Estimated complexity
Then create detailed phase documents following the phase-template format.
Step 4: Validate Documentation
Before starting development, have Claude review all documentation for consistency.
Validate documentation consistency
Claude promptPlease review all the documentation we've created for [app-name] and check for:
1. Consistency across documents (naming, terminology)
2. Missing information or gaps
3. Contradictions between documents
4. Unclear or ambiguous requirements
5. Technical feasibility issues
List any issues found and suggest fixes.
Step 5: Begin Phased Development
Once documentation is complete and validated:
- Save all documents to your app's directory structure
- Take Claude Code out of plan mode so it can edit files again
- Follow the Phase Development workflow for each phase
Start development in Claude Code
Claude promptmy-app-name: I've completed the documentation restructure.
Please read all the documentation in ai_docs/ and CLAUDE.md, then:
1. Confirm you understand the new architecture
2. Create a feature branch for Phase 1
3. Begin implementing according to the phase document
Ask any clarifying questions before starting.
Timeline Expectations
| Activity | Typical Duration |
|---|---|
| Architecture planning | 1-2 days |
| Documentation creation | 2-3 days |
| Documentation review | 1 day |
| Phase 1 development | 1-2 weeks |
| Subsequent phases | 1-2 weeks each |
Total: 4-8+ weeks depending on scope
Tips for Success
Planning Phase
- Don't rush the planning—thorough documentation saves time later
- Include diagrams and visual aids where possible
- Get stakeholder buy-in on the architecture before coding
- Document decisions and their rationale
Documentation Phase
- Use consistent terminology across all documents
- Cross-reference related sections
- Include examples and code snippets
- Mark assumptions clearly
Development Phase
- Follow Phase Development workflow strictly
- Don't skip documentation updates as you learn
- Commit frequently with clear messages
- Test thoroughly before moving to next phase
When to Abort and Simplify
Sometimes Big Changes is overkill. Consider switching to Phase Development if:
- The restructure is more limited than initially thought
- Time constraints don't allow full documentation
- Only specific parts of the app need changes
- The existing documentation is mostly still valid
It's better to deliver working software with partial restructure than get stuck in endless planning.