proxysql/doc/AI-DOCUMENTATION-FRAMEWORK.md

AI Documentation Framework

Overview

ProxySQL uses AI-generated documentation to accelerate developer onboarding and codebase exploration while maintaining transparency about accuracy limitations.

Documentation Tiers

🔬 AI-Generated (Tier 1)

• Purpose: Exploration guides and starting points
• Verification: NON-VERIFIED
• Maintenance: Community contributions encouraged
• Update: As needed when codebase changes significantly

📋 Human-Verified (Tier 2)

• Purpose: Critical operational documentation
• Verification: REQUIRED
• Maintenance: Maintainer-reviewed
• Update: With each relevant change

🔧 Living Documentation (Tier 3)

• Purpose: Auto-generated from source
• Verification: Automated validation
• Maintenance: CI/CD integration
• Update: Continuous

AI Documentation Standards

Required Disclaimer

Every AI-generated document must include:

> **⚠️ Important Notice**: This documentation was generated by AI and may contain inaccuracies.
> It should be used as a starting point for exploration only. Always verify critical information
> against the actual source code.
>
> **Last AI Update**: [DATE]
> **Status**: NON-VERIFIED
> **Maintainer**: [ASSIGNED]

File Organization

doc/
├── ai-generated/          # AI-generated exploration guides
│   ├── architecture/      # Architecture documentation
│   └── DOCUMENTATION-INDEX.md
├── internal/              # Human-verified technical docs
├── release_notes/         # Official release notes
└── README.md              # This guide

Verification Process

When to Verify

• Security-related documentation
• Build and installation instructions
• API contracts and interfaces
• Performance-critical information

Verification Checklist

• Code references are accurate
• File paths are correct
• Technical details match implementation
• Examples work as described

Maintenance Guidelines

AI Documentation Updates

1. Review after major feature changes
2. Update when architectural patterns shift
3. Community corrections welcome
4. Maintain disclaimer format

Automated Validation

Where possible, include validation commands:

**Validation Command**:
```bash
grep -n "class MySQL_Handler" src/protocol/mysql/protocol_mysql.cpp

## Contributing

### Improving AI Documentation
1. Identify inaccuracies
2. Submit corrections via PR
3. Add validation commands
4. Update disclaimer date

### Adding New AI Documentation
1. Follow the template format
2. Include required disclaimer
3. Place in appropriate `ai-generated/` subdirectory
4. Update main documentation index

## Benefits

- **Faster Onboarding**: Developers get immediate guidance
- **Reduced Burden**: Critical verification focused on essential docs
- **Transparency**: Clear status indicators for all documentation
- **Community-Driven**: Easy contribution process for improvements

## Limitations

- AI documentation may contain technical inaccuracies
- Not suitable for critical operational procedures
- Requires human verification for security-sensitive information
- May become outdated between major updates

---

This framework balances the productivity benefits of AI-generated documentation with the accuracy requirements of a critical database proxy system.