Coding standards context for AI agents building backend services with Domain Driven Design and Hexagonal Architecture.
AI coding agents like Claude Code, Cursor, and Windsurf can generate incredible amounts of code quickly. But I still care about the code quality. We're not at the point where we can be completely hands-off—I constantly review, iterate, and guide these tools toward better implementations.
For effective code review and collaboration with AI agents, we need predictable design patterns. This is even more crucial with AI-generated code since these tools can produce entire features at once, making architectural consistency vital for maintainability.
These rules are based on years of building backend services using:
- Domain Driven Design (DDD) - Rich domain models, ubiquitous language, clear boundaries
- Hexagonal Architecture (Ports & Adapters) - Separation of concerns, testability, technology independence
- Python Best Practices - Leveraging Python's strengths while maintaining clean architecture
Copy the rules into your AI agent's context when starting a new project or feature:
Please follow the architectural rules in this repository when implementing backend services.
Focus on DDD and Hexagonal Architecture patterns as outlined in the guidelines.
Add these rules to your project's documentation and reference them:
Implement this feature following our backend standards:
[link to relevant rule sections]
Many AI coding tools support project-specific context files:
- Copy rules to
.cursorrulesfor Cursor - Add as project context in Claude Code
- Reference in Windsurf workspace settings
This repository currently focuses on Python implementations, providing concrete examples and patterns optimized for Python's language features and ecosystem.
However, I'd love to collaborate with experts in other languages to expand this into a comprehensive reference for all major backend languages. If you're experienced with Java, C#, Go, TypeScript, or other languages, I welcome contributions that translate these architectural principles into language-specific implementations.
The goal is to make this the go-to reference for backend development standards across the entire ecosystem.
This is a living document based on real-world experience, but there's always room for improvement!
- Open an Issue - Propose new rules, improvements, or discuss existing ones
- Submit a PR - Add new patterns, fix examples, or improve clarity
- Share Examples - Real-world implementations that follow these patterns
- Language Adaptations - Help translate patterns to other languages
- 🔍 Uncovered Scenarios - Backend development situations not yet addressed by the current rules
- 🎨 Missing Design Patterns - Additional patterns that complement DDD and Hexagonal Architecture
- 🛠️ Implementation Strategies - Better approaches for complex scenarios like distributed systems, event sourcing, or CQRS
- 🧪 Advanced Testing Patterns - Testing strategies for complex domain logic and integration scenarios
- 📊 Real-World Examples - Case studies showing these patterns in production systems
"I think of AI coding agents as another developer on my team—I expect them to follow the same best practices."
These standards ensure that:
- Code is reviewable - Predictable patterns make AI-generated code easier to understand
- Architecture is consistent - Clear rules prevent architectural drift
- Teams can collaborate - Shared standards improve team efficiency
- Systems remain maintainable - Good architecture scales with your codebase
- Medium Article: Why I Still Care About Code Quality with AI Agents
- Domain Driven Design by Eric Evans
- Hexagonal Architecture by Alistair Cockburn
- Clean Architecture by Robert Martin
MIT License - see LICENSE file for details.
If these standards help you build better backend services with AI agents, please:
- ⭐ Star this repository
- 🔗 Share with your team
- 💬 Open discussions for improvements
- 🤝 Contribute your own learnings
Let's build better backend services together, one AI-generated feature at a time.