AI Code Generation Practices
AI Code Generation Practices for Development Team
Section titled “AI Code Generation Practices for Development Team”rev. 7-26-25
Problem Statement
Section titled “Problem Statement”With the introduction of Claude Code and AI-assisted development, we need to adapt our practices to maintain code quality and understanding while leveraging AI’s speed.
Core Philosophy
Section titled “Core Philosophy”AI as a Fast but Inconsistent Developer: AI tools are incredibly fast and capable at pattern matching and code generation, but can be inconsistent in their approaches and lack understanding of business context, architectural implications, and edge cases. Our role shifts from primarily writing code to architecting, reviewing strategically, and maintaining system understanding.
Values and Intent
Section titled “Values and Intent”Why We Embrace AI-Assisted Development
Section titled “Why We Embrace AI-Assisted Development”Velocity with Purpose: We use AI to accelerate delivery of climate impact solutions. Speed matters, but not at the expense of reliability or maintainability.
Human Judgment at the Center: AI amplifies our capabilities but doesn’t replace our responsibility. We maintain ownership of architectural decisions, business logic, and system understanding.
Continuous Learning: Both humans and AI improve through feedback loops. We document patterns, review outcomes, and refine our approaches based on real-world results.
Transparency and Trust: We’re open about using AI tools with our stakeholders. Our risk-based review process ensures appropriate oversight while building confidence in AI-assisted development.
What Success Looks Like
Section titled “What Success Looks Like”- Developers spend more time on architecture and problem-solving, less on boilerplate
- AI suggestions improve over time through better context (momentum-docs MCP)
- Code quality remains high or improves through consistent automated checks
- Team maintains deep understanding of the codebase despite increased velocity
- Customers benefit from faster feature delivery without stability compromises
Review Strategy Framework
Section titled “Review Strategy Framework”The review strategy has evolved into a risk-based approach rather than time-based tiers. See the Risk-Based PR Review Policy for current guidelines.
Key Principles from Implementation
Section titled “Key Principles from Implementation”Risk Assessment
- Developer judgment determines risk level, not review duration
- Context matters more than file types (e.g., test data migration vs production data migration)
- Feature flags and parallel refactors reduce risk levels
AI Review Capabilities
- Zero-risk changes: AI-only review sufficient
- Low-risk changes: AI review with 20% post-merge sampling
- Medium-risk changes: Either human review OR AI + mandatory post-merge
- High-risk changes: Human review required
What We’ve Learned So Far July 2025
- AI reviewers excel at syntax, patterns, and security vulnerabilities
- Human reviewers needed for business logic, architectural decisions, and context
Technical Implementation
Section titled “Technical Implementation”AI Development Tools
Section titled “AI Development Tools”Code Generation: Claude Code - Our primary AI pair programming tool AI Code Review:
- CodeRabbit - Automated PR review for best practices and patterns
- Korbit - Security vulnerabilities and code quality analysis
Context Provider: Momentum-Docs MCP (Model Context Protocol)
- Provides Claude Code with up-to-date documentation on domains, APIs, and patterns
- Reduces repetitive codebase searches and improves AI accuracy
- Must be kept current with released features and established patterns
AI Review Comment Policy
Section titled “AI Review Comment Policy”All AI review comments must be addressed - This means:
- Respond to each comment explaining your decision
- Implement suggested fixes when appropriate
- Resolve the comment thread with justification if not implementing
This policy ensures we don’t miss valuable automated insights while maintaining developer judgment on implementation decisions.
Documentation as Context
Section titled “Documentation as Context”Momentum-Docs MCP Maintenance: When discovering architectural patterns, API usage, or domain knowledge through code exploration:
- Consider if this knowledge would benefit future AI-assisted development
- Document stable patterns in momentum-docs to minimize future search overhead
- Keep documentation current as patterns evolve
- Skip documenting work-in-progress or experimental features
This creates a virtuous cycle where AI assistance becomes more accurate and efficient over time.
PHPStan Configuration
Section titled “PHPStan Configuration”- Run at maximum level (9) for all AI-generated code
- Enable strict rules:
strictRules: true - Add bleeding edge rules
- Create custom rules for domain-specific patterns
- Set up CI to fail builds on PHPStan violations
Team Practices
Section titled “Team Practices”AI Prompting Standards
Section titled “AI Prompting Standards”To make generated code more reviewable, remind AI to follow MCP and rules document.
- PHPStan level 9 compliance
- Specific test coverage targets (minimum 80% for new features)
- Adherence to existing architectural patterns
- Inline documentation for complex business logic
- Error handling for expected failure modes
Success Metrics
Section titled “Success Metrics”- Code Quality: PHPStan violations, test coverage percentages
- Production Stability: Error rates, performance metrics
- Team Velocity: Feature delivery speed while maintaining quality
- Knowledge Retention: Team confidence in explaining system behavior
Implementation Status (July 2025)
Section titled “Implementation Status (July 2025)”Completed
Section titled “Completed”- ✅ Risk-based review policy documented
- ✅ AI code generation practices defined
- ✅ Claude Code, CodeRabbit, and Korbit integrated into workflow
- ✅ AI review comment policy established (all comments must be addressed)
- ✅ Momentum-docs MCP deployed for context management
- ✅ PHPStan level 9 enforcement for new code
In Progress
Section titled “In Progress”- 🚧 Risk assessment automation tools (Python script created, GitHub Actions pending)
- 🚧 Post-merge review tracking implementation
- 🚧 Team training on risk categorization
Future Expansion: Toward a Complete Model Specification
Section titled “Future Expansion: Toward a Complete Model Specification”This document could evolve into a comprehensive Model Specification (Model Card) for our AI-assisted development system. Additional sections to consider:
Technical Specifications
Section titled “Technical Specifications”- Model versions and capabilities for each AI tool
- Training data characteristics and limitations
- Update cycles and version control
- Integration points and dependencies
Quantitative Evaluation
Section titled “Quantitative Evaluation”- Baseline metrics: pre-AI vs post-AI development velocity
- Defect rates by risk category and review type
- False positive/negative rates in automated reviews
- Time-to-resolution for AI-flagged issues
Risk Analysis & Mitigations
Section titled “Risk Analysis & Mitigations”- Documented failure modes and recovery procedures
- Incident response protocols for AI-related issues
- Human escalation paths and override mechanisms
- Business continuity without AI tools
Governance & Compliance
Section titled “Governance & Compliance”- Data sharing agreements with AI providers
- Code privacy and intellectual property protections
- Audit trails for AI-assisted decisions
- Regulatory compliance considerations
Stakeholder Impact Assessment
Section titled “Stakeholder Impact Assessment”- Developer experience and job satisfaction metrics
- Training requirements and skill development
- Client communication about AI usage
- Long-term maintainability considerations
Creating a full Model Specification would provide transparency for SOC2 audits, support responsible AI practices, and establish Cadence OneFive as a leader in climate tech AI adoption.