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:

markdown

> **⚠️ 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

Review after major feature changes
Update when architectural patterns shift
Community corrections welcome
Maintain disclaimer format

Automated Validation

Where possible, include validation commands:

markdown

**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.