The specific touchpoints that make every audience feel welcome

Think of interfaces as the doorways into your codebase. Just as a building has different entrances for visitors, staff, and deliveries, your codebase needs distinct, well-designed interfaces for each audience.

Who uses it: Service consumers looking to understand and use your project

The front door of your codebase - where first impressions are made and decisions happen.

# Project Name
> One-line description that instantly conveys value

## 🚀 Quick Start

```bash
# Get running in 30 seconds
npm install your-project
your-project --demo

Clear explanation without technical jargon

• 📚 Full Documentation
• 🎯 Examples
• 💬 Community

#### 💡 **Pro Tips**

- **Lead with value**, not features
- **Show, don't tell** - use examples liberally  
- **Test with newcomers** - if they can't understand it in 2 minutes, simplify

---

### 🤝 **Contributor Interface** → `CONTRIBUTING.md`

**Who uses it:** Developers wanting to improve or extend your project

**The workshop entrance** - where potential contributors decide if they want to join your mission.

#### 🎯 **Core Elements**

```markdown
# Contributing Guide

## 🎯 Ways to Contribute

- 🐛 Report bugs
- ✨ Suggest features  
- 📝 Improve documentation
- 🔧 Submit code changes

## 🚀 Quick Setup

```bash
git clone repo-url
cd project
task setup    # or npm install, make setup, etc.
task test     # verify everything works

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-thing)
3. Make changes with tests
4. Submit pull request

#### 💡 **Pro Tips**

- **Make contributing feel achievable** - start with easy wins
- **Standardize on universal commands** - `task setup`, not `npm run setup`
- **Automate quality checks** - let tools catch style issues

---

### 🛠️ **Operator Interface** → `RUNBOOK.md`

**Who uses it:** People deploying, monitoring, and maintaining your service

**The control room manual** - where operators find everything needed for reliable operations.

#### 🎯 **Core Elements**

```markdown
```markdown
# Operations Runbook

## 🚀 Deployment

```bash
# Production deployment
task deploy:prod

# Staging deployment  
task deploy:staging

• Health Check: /health
• Metrics: /metrics
• Logs: tail -f logs/app.log

1. Check configuration: task validate-config
2. Verify dependencies: task check-deps
3. Review logs: task logs

• On-call: +1-555-ONCALL
• On-call: +1-555-ONCALL
• Slack: #ops-alerts

• Think 3am scenarios - write for stressed, tired operators
• Include examples for every command and procedure
• Test your runbook regularly with actual deployments

Who uses it: AI assistants helping with development, support, and analysis

The AI briefing room - where artificial intelligence learns to be genuinely helpful.

# AI Agent Interface

## 🎯 Project Context
**Purpose**: [What this codebase does]
**Architecture**: [Key patterns and decisions]
**Dependencies**: [Critical external services]

## 🔧 Common Tasks
- **Setup**: `task setup`
- **Test**: `task test`
- **Build**: `task build`
- **Deploy**: `task deploy`

## 📁 Key Directories
- `src/`: Core application code
- `tests/`: Test suites
- `docs/`: Documentation
- `scripts/`: Automation tools

## ⚠️ Important Notes
- Always run tests before suggesting changes
- Configuration lives in `config/`
- See CONTRIBUTING.md for workflow

• Be explicit about context - AIs need more details than humans
• Explain your patterns - why you chose certain architectures
• • Include gotchas - things that commonly trip up newcomers

Who uses it: CI/CD systems and developers running consistent commands

The automation hub - where all your project's tasks are defined and standardized.

version: '3'

tasks:
  setup:
    desc: Install dependencies and prepare environment
    cmds:
      - echo "Installing dependencies..."
      # Platform-specific setup commands

  test:
    desc: Run all tests
    cmds:
      - echo "Running tests..."
      # Test execution commands

  build:
    desc: Build the project
    cmds:
      - echo "Building project..."
      # Build commands

  deploy:
    desc: Deploy to production
    cmds:
      - echo "Deploying..."
      # Deployment commands

• Use descriptive task names - task deploy:prod, not task dp
• Add helpful descriptions - make task --list informative
• Keep it platform-neutral - avoid OS-specific commands when possible

Design each interface for its primary audience's mental model and workflow patterns.

Start simple, then provide pathways to deeper information when needed.

Use the same conventions across all interfaces - consistent structure, commands, and terminology.

Every interface should help people do something, not just understand something.

Work across different tools, platforms, and experience levels.

When all interfaces work together harmoniously:

• 🎯 Consumers discover your project and get value quickly
• 🤝 Contributors can jump in and add value immediately
• 🛠️ Operators deploy and maintain with confidence
• 🤖 AI Agents provide accurate, contextual assistance
• ⚡ Build Systems process your code reliably

Result: A codebase that welcomes everyone and enables rapid, confident collaboration.

Grade your current interfaces:

• ✅ README.md: Would a newcomer understand and try your project in 5 minutes?
• ✅ CONTRIBUTING.md: Could someone make their first contribution today?
• ✅ RUNBOOK.md: Could a new team member deploy without help?
• ✅ AGENTS.md: Do AI tools give accurate suggestions about your project?
• ✅ Taskfile.yml: Do all common tasks work with simple, consistent commands?

Understanding interfaces is just the beginning. Next, discover how these thoughtful touchpoints create measurable value for everyone involved.

← Previous: Audiences
→ Next: Benefits ⭐

Remember: Great interfaces aren't just documentation - they're experiences that invite people into your world.