🌟 Imagine a world where every developer, operator, AI agent, and build system knows exactly how to interact with your codebase. Where onboarding takes minutes, not days. Where your code is as welcoming as your team.

The Codebase Interface Initiative is a set of principles and practices that transforms how we think about codebases. Instead of treating them as mere collections of files, we treat them as products with multiple consumers - each deserving a great experience.

Developers who improve your code

DevOps/SRE who deploy & maintain

Copilot, ChatGPT, and other AI tools

CI/CD systems and automation

Start here → Understand the foundations → See it in action → Join the movement

• Principles - The 8 core principles that drive everything
• Audiences - Meet the 5 types of users

• Interfaces - How to serve each audience
• Tooling - Recommended tools & practices

• Benefits - Why this approach works
• Examples - Real implementations

• Contribute - Join our mission
• Presentations - Share the knowledge

🎆 The Vision: Your codebase should be a welcoming, well-organized digital space where everyone knows their way around.

🎨 The Method: Create dedicated interfaces (files and practices) for each audience, just like a well-designed building has different entrances for different purposes.

🏆 The Result: Faster onboarding, better collaboration, AI-ready documentation, and happier teams.

Think of your codebase as a digital building with dedicated interfaces for each type of visitor:

graph TD
    %% Central Codebase
    CODEBASE[🏗️ Codebase<br/>Product]
    
    %% Interface Files
    README["📖 README.md<br/><small>User Interface</small>"]
    CONTRIBUTING["👥 CONTRIBUTING.md<br/><small>Contributor Interface</small>"]
    RUNBOOK["🔧 RUNBOOK.md<br/><small>Operations Interface</small>"]
    AGENTS["🤖 AGENTS.md<br/><small>AI Interface</small>"]
    BUILD["⚙️ Taskfile<br/><small>Build Interface</small>"]
    
    %% Audience Groups
    CONSUMERS["👤 Service Users<br/><small>End Users</small>"]
    CONTRIBUTORS["🧑‍💻 Contributors<br/><small>Developers</small>"]
    OPERATORS["🛠️ Operators<br/><small>DevOps/SRE</small>"]
    AI_AGENTS["🤖 AI Agents<br/><small>Copilot/ChatGPT</small>"]
    BUILD_AGENTS["🚀 Build Agents<br/><small>CI/CD Systems</small>"]
    
    %% Connections: Interfaces to Codebase
    README -.-> CODEBASE
    CONTRIBUTING -.-> CODEBASE
    RUNBOOK -.-> CODEBASE
    AGENTS -.-> CODEBASE
    BUILD -.-> CODEBASE
    
    %% Connections: Audiences to Interfaces
    CONSUMERS ==> README
    CONTRIBUTORS ==> CONTRIBUTING
    OPERATORS ==> RUNBOOK
    AI_AGENTS ==> AGENTS
    BUILD_AGENTS ==> BUILD
    
    %% Styling
    classDef codebase fill:#4b9ce2,stroke:#333,stroke-width:3px,color:#fff
    classDef interface fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#1565c0
    classDef audience fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    
    class CODEBASE codebase
    class README,CONTRIBUTING,RUNBOOK,AGENTS,BUILD interface
    class CONSUMERS,CONTRIBUTORS,OPERATORS,AI_AGENTS,BUILD_AGENTS audience

Thousands of developers are already transforming their codebases. Join us in making software development more welcoming and efficient for everyone!

⭐ Star on GitHub • 💬 Join Discussions

If your codebase follows the Codebase Interface principles, help spread the word!

Choose the style that fits your project:

[![Codebase Interface Principles](https://img.shields.io/badge/Codebase%20Interface-Principles-4b9ce2?style=flat-square&logo=semanticweb&logoColor=white)](https://codebaseinterface.org)

> This repository follows the **Codebase Interface Principles** — for a better experience for everyone who works with it.

Simple:

Footer: Follows the Codebase Interface Principles.