OpenStack AI Style Guide

A comprehensive style guide and ruleset designed for AI code generation tools working with OpenStack Python projects.

🚀 Quick Start for AI Tools

Primary Files

• quick-rules.md (710 tokens) - Essential rules for immediate use
• comprehensive-guide.md (4700 tokens) - Detailed explanations and examples

Integration Commands

# Claude Code
claude-code --context-file docs/quick-rules.md

# Cursor
# Add to .cursorrules: @docs/quick-rules.md

# Generic AI tool
curl https://raw.githubusercontent.com/username/openstack-ai-style-guide/main/docs/quick-rules.md

# Local usage
cat docs/quick-rules.md | pbcopy  # macOS
cat docs/quick-rules.md | xclip -selection clipboard  # Linux

📁 Repository Structure

openstack-ai-style-guide/
├── docs/                          # Style guide documentation
│   ├── quick-rules.md            # Concise reference (710 tokens)
│   ├── comprehensive-guide.md    # Detailed guide (4700 tokens)
│   ├── examples/                 # Code examples and patterns
│   │   ├── good/                # Correct OpenStack patterns
│   │   └── bad/                 # Anti-patterns to avoid
│   ├── checklists/              # Validation checklists
│   │   ├── pre-submit.md       # Before committing and pushing
│   │   └── code-review.md      # Reviewing AI code
│   └── templates/               # Code and commit templates
│       ├── python_module.py.template
│       ├── python_test.py.template
│       ├── commit_message.txt
│       └── pre-commit-config.yaml
├── references/                   # Authoritative source documents
│   ├── ai-policy.md             # OpenInfra AI Policy
│   ├── dco.md                   # Developer Certificate of Origin
│   ├── hacking.md               # OpenStack Hacking Rules
│   └── pep8.md                  # PEP 8 Style Guide
├── tools/                        # Validation and helper scripts
├── CONTRIBUTING.md               # Contribution guidelines
├── LICENSE                       # Apache 2.0 license
└── README.md                     # This file

🎯 When to Use Which Guide

Use quick-rules.md for

• ✅ Real-time code generation
• ✅ Quick validation checks
• ✅ Context-constrained AI tools
• ✅ Fast reference lookups

Use comprehensive-guide.md for

• 📚 Learning OpenStack patterns
• 🐛 Complex debugging scenarios
• 📝 Policy and compliance questions
• 🔍 Detailed implementation guidance

🛠 AI Tool Configuration

Claude Code

# Include in system prompt or use context file
claude-code --context-file docs/quick-rules.md --model claude-3-sonnet

GitHub Copilot

Add to your .github/copilot-instructions.md:

Follow the OpenStack style guide at docs/quick-rules.md for all Python code generation.

Cursor

Add to .cursorrules:

@docs/quick-rules.md

Always follow OpenStack Python style guidelines for code generation.

Custom AI Tools

Include the quick rules as system context:

with open('docs/quick-rules.md', 'r') as f:
    style_guide = f.read()

# Pass style_guide as system context to your AI model

🚦 Compliance Checklist

Before submitting AI-generated OpenStack code:

• Apache 2.0 license header included
• Line length ≤ 79 characters
• No bare except: statements
• autospec=True in all mock decorators
• Delayed logging interpolation used
• Proper import organization
• AI attribution in commit message (Generated-By/Assisted-By)
• DCO sign-off included (git commit -s - REQUIRED)

📊 Token Usage Guide

Context	File	Tokens	Use Case
Minimal	quick-rules.md	710	Real-time generation
Standard	Both files	5410	Complex implementations
Full	All docs + examples	~7100+	Learning/training

Token Constraints:

• quick-rules.md: Target < 1000 tokens for standalone copying to other repos
• comprehensive-guide.md: Target < 5000 tokens for comprehensive reference
• Both files designed to be self-contained and readable without external dependencies

🤝 Contributing

See CONTRIBUTING.md for guidelines on:

• Adding new rules and patterns
• Contributing examples
• AI-generated content attribution
• Community review process

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔗 Related Resources

• OpenStack Contributor Guide
• OpenInfra Foundation AI Policy
• Python PEP 8 Style Guide
• Hacking Style Checks