In the “before times”—roughly pre-2023—we built software for two main audiences: our users and our fellow human developers. Today, a third, incredibly powerful stakeholder has entered the chat: Artificial Intelligence.
Whether you are using GitHub Copilot to autocomplete functions, or feeding an entire codebase into a Large Language Model (LLM) to refactor a legacy module, the way we structure our repositories now determines how effectively AI can assist us.
As a software engineer who views coding as a grand puzzle, I’ve found that the “cleaner” the puzzle pieces, the faster the AI helps me solve it. Here is how you can prepare your repository for the AI era.
1. Embrace “Screaming Architecture”
AI models have a limited “context window”—the amount of text they can process at once. If your project structure is a generic maze of controllers/, models/, and services/, the AI has to open every folder to understand the business intent.
The Fix: Use Screaming Architecture. Your folder names should scream what the application does.
- Bad:
src/services/user_service.py - Good:
src/billing/calculate_invoice_use_case.py
When an AI sees a domain-driven structure, it immediately categorizes the logic. It understands that “Billing” and “Shipping” are separate concerns, making it less likely to hallucinate cross-contaminations.
2. Implement the Hexagonal Pattern (Ports and Adapters)
If your business logic is tangled up with SQL queries or specific AWS SDKs, an AI will struggle to refactor the logic without breaking the infrastructure.
The Strategy: Use Hexagonal Architecture.
By defining Ports (interfaces) for your repositories and Adapters for your implementation (e.g., Postgres, DynamoDB), you create a “pluggable” system.
- AI Benefit: You can ask an AI: “Here is my Input Port for ‘Order Processing’. Generate a new Adapter for a MongoDB implementation.” Because the boundary is clear, the AI can generate the technical code without touching—or breaking—the sacred business rules in the core.
3. Create “AI-Friendly” Metadata
We’ve spent decades writing documentation for humans, often resulting in 50-page PDFs that no one reads. AI needs something different: structured, concise context.
- Architecture Decision Records (ADRs): Keep a folder of small Markdown files explaining why you chose a specific technology. When you ask an AI to add a feature, it can read these ADRs to ensure the new code aligns with your previous architectural choices.
- System Blueprints: Use Mermaid.js or simple text-based diagrams in your
README.md. AIs are surprisingly good at parsing text-based flowcharts to understand the “big picture” before they dive into the lines of code.
4. Consistent “Ubiquitous Language”
In Domain-Driven Design (DDD), we speak of a Ubiquitous Language—a shared vocabulary between developers and stakeholders. In the AI era, this is your secret weapon.
If your database calls it account_status, your code calls it is_active, and your UI calls it user_level, the AI will get confused. By being pedantically consistent with naming across the entire repository, you provide the AI with a “semantic map” that drastically improves the accuracy of its code generation.
5. Automated Testing as Living Documentation
Unit tests and integration tests are no longer just safety nets; they are specifications.
When an AI sees a test case like test_should_reject_order_when_credit_limit_exceeded, it understands the expected behavior better than any comment could explain. It can then use that “context” to write the implementation or suggest edge cases you missed.
The Verdict: Clean Code is AI Code
The irony of the AI era is that it doesn’t reward “clever” or “magical” code. It rewards predictable, modular, and well-organized code. By applying classic principles like Hexagonal Architecture and DDD, you aren’t just making your life easier today; you are building a repository that an AI can navigate, maintain, and improve alongside you.
References
Based on the architectural principles and expert insights discussed in the article, here is the source list of the foundational materials used:
- Hombergs, T. (2023). Get Your Hands Dirty on Clean Architecture (2nd ed.). This source provides the core definition of the Hexagonal Architecture (Ports and Adapters), emphasizing the separation of domain logic from technical details and the inward flow of dependencies.
- Sifuentes, E. M., & Wille, S. (2024). Domain-Driven Refactoring. This book explores the impact of Domain-Driven Design in the AI era and introduces the concept of using modules as “data bags” to simplify implementation and improve efficiency in specific contexts.
- Timofti, A. (2024). Software Architecture with Kotlin. This reference details the structure of Hexagonal Architecture, specifically identifying the roles of the Core, Ports, and Adapters in creating maintainable and testable software.
- Ghorai, A. (2024). Clean Architecture with Python. This source discusses the implementation of interface adapters and architectural boundaries, as well as the use of the “Humble Object” pattern to keep business logic isolated from frameworks.
- Aniche, M. (2021). Clean Code in Python. This book provides the foundational reference for “Screaming Architecture,” arguing that a project’s structure should immediately reveal its functional intent rather than its technical framework.