Skip to content

Commit 4915234

Browse files
renecannaorenecannao
authored
Merge pull request #5115 from sysown/v3.0.agentics
[skip-ci] V3.0.agentics - Add Claude Code Agent Definitions and Architecture Documentation
2 parents 3810922 + 291e5f0 commit 4915234

File tree

11 files changed

+5640
-0
lines changed

11 files changed

+5640
-0
lines changed

‎.aider.conf.yml‎

Lines changed: 456 additions & 0 deletions
Large diffs are not rendered by default.

‎.gitignore‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,24 @@
1+
# Internal Repos
2+
priv-infra/
3+
4+
# direnv
5+
.envrc.local
6+
7+
8+
# Intelij
9+
.idea/
10+
11+
# VS Code
12+
.vs/
13+
14+
# Sonar
15+
.scannerwork/
16+
.vs/
17+
bw-output/
18+
out/
19+
sonar/
20+
21+
122
# Object files
223
*.o
324
*.ko
@@ -151,4 +172,5 @@ proxysql-save.cfg
151172
test/tap/tests/test_cluster_sync_config/cluster_sync_node_stderr.txt
152173
test/tap/tests/test_cluster_sync_config/proxysql*.pem
153174
test/tap/tests/test_cluster_sync_config/test_cluster_sync.cnf
175+
.aider*
154176
GEMINI.md

‎doc/AI-DOCUMENTATION-FRAMEWORK.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# AI Documentation Framework
2+
3+
## Overview
4+
5+
ProxySQL uses AI-generated documentation to accelerate developer onboarding and codebase exploration while maintaining transparency about accuracy limitations.
6+
7+
## Documentation Tiers
8+
9+
### 🔬 AI-Generated (Tier 1)
10+
- **Purpose**: Exploration guides and starting points
11+
- **Verification**: NON-VERIFIED
12+
- **Maintenance**: Community contributions encouraged
13+
- **Update**: As needed when codebase changes significantly
14+
15+
### 📋 Human-Verified (Tier 2)
16+
- **Purpose**: Critical operational documentation
17+
- **Verification**: REQUIRED
18+
- **Maintenance**: Maintainer-reviewed
19+
- **Update**: With each relevant change
20+
21+
### 🔧 Living Documentation (Tier 3)
22+
- **Purpose**: Auto-generated from source
23+
- **Verification**: Automated validation
24+
- **Maintenance**: CI/CD integration
25+
- **Update**: Continuous
26+
27+
## AI Documentation Standards
28+
29+
### Required Disclaimer
30+
Every AI-generated document must include:
31+
32+
```markdown
33+
> **⚠️ Important Notice**: This documentation was generated by AI and may contain inaccuracies.
34+
> It should be used as a starting point for exploration only. Always verify critical information
35+
> against the actual source code.
36+
>
37+
> **Last AI Update**: [DATE]
38+
> **Status**: NON-VERIFIED
39+
> **Maintainer**: [ASSIGNED]
40+
```
41+
42+
### File Organization
43+
```
44+
doc/
45+
├── ai-generated/ # AI-generated exploration guides
46+
│ ├── architecture/ # Architecture documentation
47+
│ └── DOCUMENTATION-INDEX.md
48+
├── internal/ # Human-verified technical docs
49+
├── release_notes/ # Official release notes
50+
└── README.md # This guide
51+
```
52+
53+
## Verification Process
54+
55+
### When to Verify
56+
- Security-related documentation
57+
- Build and installation instructions
58+
- API contracts and interfaces
59+
- Performance-critical information
60+
61+
### Verification Checklist
62+
- [ ] Code references are accurate
63+
- [ ] File paths are correct
64+
- [ ] Technical details match implementation
65+
- [ ] Examples work as described
66+
67+
## Maintenance Guidelines
68+
69+
### AI Documentation Updates
70+
1. Review after major feature changes
71+
2. Update when architectural patterns shift
72+
3. Community corrections welcome
73+
4. Maintain disclaimer format
74+
75+
### Automated Validation
76+
Where possible, include validation commands:
77+
```markdown
78+
**Validation Command**:
79+
```bash
80+
grep -n "class MySQL_Handler" src/protocol/mysql/protocol_mysql.cpp
81+
```
82+
```
83+
84+
## Contributing
85+
86+
### Improving AI Documentation
87+
1. Identify inaccuracies
88+
2. Submit corrections via PR
89+
3. Add validation commands
90+
4. Update disclaimer date
91+
92+
### Adding New AI Documentation
93+
1. Follow the template format
94+
2. Include required disclaimer
95+
3. Place in appropriate `ai-generated/` subdirectory
96+
4. Update main documentation index
97+
98+
## Benefits
99+
100+
- **Faster Onboarding**: Developers get immediate guidance
101+
- **Reduced Burden**: Critical verification focused on essential docs
102+
- **Transparency**: Clear status indicators for all documentation
103+
- **Community-Driven**: Easy contribution process for improvements
104+
105+
## Limitations
106+
107+
- AI documentation may contain technical inaccuracies
108+
- Not suitable for critical operational procedures
109+
- Requires human verification for security-sensitive information
110+
- May become outdated between major updates
111+
112+
---
113+
114+
This framework balances the productivity benefits of AI-generated documentation with the accuracy requirements of a critical database proxy system.

‎doc/README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# ProxySQL Documentation Guide
2+
3+
## Documentation Structure
4+
5+
ProxySQL documentation is organized into different tiers to help developers find the information they need:
6+
7+
### 🔬 AI-Generated Documentation (Exploration Guides)
8+
9+
The `ai-generated/` directory contains documentation created by AI assistants to help developers explore the codebase:
10+
11+
> **⚠️ Important Notice**: AI-generated documentation may contain inaccuracies and should be used as a starting point for exploration only. Always verify critical information against the actual source code.
12+
13+
**Available AI-generated guides:**
14+
- **`ai-generated/DOCUMENTATION-INDEX.md`** - Comprehensive index of all documentation
15+
- **`ai-generated/architecture/ARCHITECTURE-OVERVIEW.md`** - System architecture and design patterns
16+
- **`ai-generated/architecture/PROJECT-LAYOUT.md`** - Directory structure and module organization
17+
- **`ai-generated/architecture/VISUAL-GUIDE.md`** - Architecture diagrams and visual references
18+
- **`ai-generated/architecture/TEST-PIPELINE.md`** - Testing framework and CI/CD workflows
19+
- **`ai-generated/architecture/RELEASE-PIPELINE.md`** - Release process and packaging
20+
21+
**Status: NON-VERIFIED**
22+
- **Last AI Update**: 2025-09-11
23+
- **Maintainer**: Rene Cannao
24+
25+
### 📋 Human-Verified Documentation
26+
27+
Critical documentation that has been reviewed and verified by maintainers:
28+
29+
- **`README.md`** - Main project overview and quick start
30+
- **`INSTALL.md`** - Installation instructions
31+
- **`FAQ.md`** - Frequently asked questions
32+
33+
### 🔧 Internal Documentation
34+
35+
Detailed technical documentation for specific components:
36+
37+
- **`doc/internal/`** - In-depth technical guides
38+
- **`doc/release_notes/`** - Release notes and changelogs
39+
40+
## Using AI-Generated Documentation
41+
42+
1. **Start Here**: Use AI-generated docs to understand the codebase structure
43+
2. **Verify Information**: Always cross-reference with actual source code
44+
3. **Report Issues**: Help improve accuracy by reporting discrepancies
45+
46+
## Contributing to Documentation
47+
48+
- **AI Documentation**: Contributions are welcome - please verify against source code
49+
- **Verified Documentation**: Follow the existing review process
50+
- **Framework**: See `AI-DOCUMENTATION-FRAMEWORK.md` for guidelines
51+
52+
---
53+
54+
> This approach provides the benefits of AI-generated assistance while being transparent about limitations and reducing verification overhead.

0 commit comments

Comments
 (0)