adce-framework

# ADCE Best Practices - Maximizing Framework Effectiveness Proven practices for getting the most out of Appetite-Driven Context Engineering. ## Starting Strong ### First 30 Days **Goal**: Build confidence and establish patterns **Week 1**: Install and Basic Usage - Install ADCE framework: `npx adce-framework install` - Try one simple feature: "Use shaper to create a pitch for: [basic improvement]" - Focus on understanding the workflow, not complex features **Week 2**: Complete First Cycle - Execute full shaper → architect → builder/deployer workflow - Track progress with hill charts instead of task lists - Practice circuit breaker decisions when complexity grows **Week 3**: Refine and Customize - Customize agents for your domain and tech stack - Create project-specific templates and context - Document your team's patterns and gotchas **Week 4**: Scale and Share - Try parallel PRPs and larger appetites - Share learnings with team members - Start building team context library ### Team Adoption Strategy **Start Small**: One team member, simple features, 1-3 day appetites **Prove Value**: Track velocity and quality improvements with concrete metrics (measure AI acceleration factor) **Scale Gradually**: Add team members and complexity as patterns stabilize **Share Learnings**: Document what works and what doesn't for your AI-accelerated context ## Appetite Management Mastery ### AI-Accelerated Appetite Calibration by Project Type **New Features (AI-Accelerated)**: - Simple CRUD: 1-3 days - Complex workflows: 3-5 days to 1-2 weeks - Integration features: 3-5 days to 1 week - Analytics/reporting: 1-2 weeks **Bug Fixes (AI-Accelerated)**: - Simple fixes: 1-2 days - Complex debugging: 3-5 days - Performance issues: 3-5 days to 1 week - Security vulnerabilities: 1-3 days (urgent) **Technical Debt (AI-Accelerated)**: - Code refactoring: 3-5 days to 1-2 weeks - Database migrations: 1-2 weeks - Dependency updates: 1-3 days - Architecture improvements: 2-3 weeks **AI Acceleration Factors to Consider**: - **Context Quality**: Better context = faster implementation (2-5x speedup) - **First-Pass Success**: Comprehensive PRPs enable 80-95% success rates - **Pattern Reuse**: Existing patterns accelerate similar features (3-10x speedup) - **Iteration Reduction**: Good context reduces back-and-forth clarification cycles ### Circuit Breaker Excellence **Early Warning Signs**: - Scope discussions taking longer than implementation - "While we're here" additions appearing frequently - Hill chart progress stalling in problem-solving phase - Technical unknowns multiplying rather than resolving **Effective Scope Cutting**: 1. **First to Cut**: Visual polish and micro-interactions 2. **Next to Cut**: Advanced features for power users 3. **Last Resort**: Simplify core workflow (preserve user value) 4. **Never Cut**: Data safety, security basics, core user outcome **Scope Cutting Communication**: ``` "We're cutting [specific feature] to deliver [core user value] within our 3-week appetite. We can revisit [cut feature] in a future cycle if user feedback shows it's needed." ``` ## Context Engineering Excellence ### PRP Quality Framework **Comprehensive Context Checklist**: - [ ] Clear goal with measurable success criteria - [ ] Appetite constraint with specific time boundary - [ ] All necessary documentation links with relevance explained - [ ] Existing code patterns to follow with file references - [ ] Known gotchas with specific workarounds or warnings - [ ] Validation framework with concrete testing criteria - [ ] Circuit breaker options with scope reduction alternatives **Context Gathering Techniques**: - **Code Archaeology**: Document existing patterns before building new ones - **Gotcha Collection**: Maintain team knowledge base of implementation traps - **Pattern Library**: Build reusable context blocks for common scenarios - **Validation Templates**: Standardize testing approaches for different feature types ### First-Pass Success Optimization **High-Success Context Patterns**: - Include actual code examples from your codebase, not generic examples - Reference specific file paths and line numbers for existing patterns - Provide both positive examples (do this) and negative examples (avoid this) - Include performance requirements and constraints upfront - Specify error handling patterns and edge case expectations **Context Testing**: - Try PRPs with team members unfamiliar with the codebase - Measure first-pass implementation success rates - Refine context based on where clarification is needed - Build team library of proven high-success PRPs ## Agent Optimization ### Agent Customization Strategy **Domain-Specific Enhancements**: ```markdown # Example: E-commerce shaper agent addition ## E-commerce Context - Consider checkout flow impact for any user-facing changes - Include mobile-first design requirements (70% mobile traffic) - Reference existing analytics tracking patterns in utils/analytics.js - Factor in payment processing constraints and PCI compliance ``` **Team Pattern Integration**: ```markdown # Example: Team coding standards addition ## Code Quality Standards - Follow existing TypeScript patterns in src/components/ - Use React Query for data fetching (see examples in src/hooks/) - Implement error boundaries for new UI components - Include unit tests following patterns in src/__tests__/ ``` ### Agent Effectiveness Measurement **Success Metrics**: - **First-Pass Success**: Percentage of PRPs that work without clarification - **Scope Adherence**: How often projects finish within appetite - **Code Quality**: Technical debt accumulation vs. resolution - **User Value**: Feature adoption and satisfaction scores **Improvement Feedback Loop**: 1. Track which PRPs need clarification most often 2. Identify common context gaps and add to agent prompts 3. Refine appetite calibration based on historical accuracy 4. Update circuit breaker criteria based on team experience ## Workflow Optimization ### Parallel Execution Patterns **Independent PRPs**: Run simultaneously when no blocking dependencies ``` Sprint Structure: Week 1: architect creates 3 PRPs (API, UI, Deploy) Week 2-3: builder (UI) + deployer (API + Infrastructure) in parallel Week 4: architect oversees integration and validation ``` **Sequential Handoffs**: When PRPs have dependencies ``` Dependent Flow: Week 1: Database schema changes (deployer) Week 2: API updates using new schema (architect) Week 3: UI consuming updated API (builder) Week 4: Integration and user testing ``` ### Hill Chart Mastery **Problem-Solving Phase (0-33%)**: - Focus on understanding and research - Don't start implementation until approach is clear - OK to spend extra time here to avoid thrashing later **Solution Building Phase (34-66%)**: - Clear execution with known approach - If you slide backwards, stop and reassess approach - Most productive phase when problem is well understood **Finishing Phase (67-100%)**: - Integration, testing, and polish - Cut scope aggressively if timeline pressure emerges - Ship working solution over perfect implementation ## Team Patterns ### Cross-Team Coordination **Shared Context Libraries**: - Central repository of successful PRPs and patterns - Team-specific gotchas and solutions - Common validation frameworks and testing approaches - Architecture decision records with context **Community of Practice**: - Weekly "Show and Tell" of successful cycles - Shared appetite calibration experiences - Cross-team agent customization sharing - Methodology improvement discussions ### Scaling Beyond Single Team **Multi-Team Integration**: - Standardize PRP formats and context expectations - Share agent customizations across teams - Coordinate appetite setting for cross-team features - Create integration testing patterns for team boundaries **Organizational Adoption**: - Start with voluntary early adopters, not mandates - Measure and communicate velocity and quality improvements - Provide training and support for teams adopting ADCE - Create center of excellence for methodology refinement ## Common Pitfalls & Solutions ### Appetite Discipline **Pitfall**: "Quick additions" that double scope **Solution**: Explicit scope definition with "not doing" list **Pitfall**: Perfect implementation consuming entire appetite **Solution**: "Good enough" mindset with clear quality gates **Pitfall**: Extending appetite instead of cutting scope **Solution**: Circuit breaker automation with scope reduction options ### Context Engineering **Pitfall**: Generic context that works for any codebase **Solution**: Specific file references and existing pattern examples **Pitfall**: Missing critical implementation gotchas **Solution**: Team knowledge base of discovered gotchas and solutions **Pitfall**: Stale context referencing outdated patterns **Solution**: Regular context validation and update cycles ### Agent Coordination **Pitfall**: Overlapping agent responsibilities causing confusion **Solution**: Clear agent role definitions and explicit handoff procedures **Pitfall**: Agents working in isolation without coordination **Solution**: Structured collaboration patterns and integration checkpoints **Pitfall**: Generic agent responses not utilizing comprehensive context **Solution**: Agent prompt refinement and context engineering validation ## Success Indicators ### Individual Success - Consistent delivery within appetite constraints - High first-pass implementation success with PRPs - Growing library of reusable context and patterns - Confidence in scope cutting decisions ### Team Success - Predictable feature delivery velocity - Reduced context switching and rework - Shared understanding of quality standards - Effective collaboration between agents and team members ### Organizational Success - Improved product development velocity - Higher feature adoption and user satisfaction - Reduced technical debt accumulation - Scalable development practices across teams --- These practices enable teams to maximize the effectiveness of ADCE framework and build sustainable AI-assisted development capabilities.