---
slug: interface
type: pattern
summary: "The surface where two parts of a system meet: the operations, inputs, outputs, and expectations through which one thing uses another."
created: 2026-04-04
updated: 2026-04-05
related:
  abstraction:
    relation: enables
    note: "An interface is the visible face of an abstraction."
  architecture:
    relation: used-by
    note: "The building blocks of architectural decisions."
  boundary:
    relation: lives-at
    note: "Interfaces exist where boundaries exist."
  bounded-context:
    relation: enabled-by
    note: "The translation layer between contexts is a defined interface."
  component:
    relation: used-by
    note: "Every component and module exposes an interface."
  composition:
    relation: used-by
    note: "Parts compose through compatible interfaces."
  consumer:
    relation: consumed-by
    note: "Someone or something uses every interface."
  consumer-driven-contract-testing:
    relation: depended-on-by
    note: "The interface is what the recorded pact describes."
  contract:
    relation: defines
    note: "The contract spells out what the interface promises."
  coupling:
    relation: manages
    note: "These tools let you make coupling explicit and stable."
  dependency:
    relation: manages
    note: "Wrapping dependencies behind interfaces reduces direct coupling."
  module:
    relation: used-by
    note: "Every component and module exposes an interface."
  parallel-change:
    relation: used-by
    note: "The interface holds both forms during the middle phase."
  platform-as-a-product:
    relation: used-by
    note: "Determines whether teams adopt the platform or route around it."
  strangler-fig:
    relation: used-by
    note: "The routing layer works because it preserves the existing interface, decoupling consumers from implementation."
---
# Interface

> **Pattern**
>
> A named solution to a recurring problem.

> "Program to an interface, not an implementation."
> — Gang of Four, *Design Patterns*

## Context

Whenever two parts of a system need to work together, they meet at a surface. An **interface** is that surface: the set of operations, inputs, outputs, and expectations through which one thing uses another. It operates at the **architectural** scale and is one of the most fundamental ideas in software construction.

Interfaces appear everywhere: a function signature is an interface, an HTTP API is an interface, a command-line tool's flags are an interface, and the system prompt for an AI agent is a kind of interface. Wherever there is a [boundary](boundary.md), there is an interface.

## Problem

How do you let two parts of a system communicate without requiring each to know the other's internals?

## Forces

- Parts that know each other's internals become tightly [coupled](coupling.md). Changing one breaks the other.
- Making the interface too narrow limits what [consumers](consumer.md) can do.
- Making the interface too broad exposes details that should be hidden.
- Interfaces are hard to change once consumers depend on them.

## Solution

Define the interface as the minimum surface a [consumer](consumer.md) needs to accomplish its goals. An interface should answer: what can I ask for, what do I provide, and what can I expect in return? Everything else (the data structures, algorithms, and strategies behind the interface) belongs to the implementation.

Good interfaces are:

- **Discoverable** — a consumer can figure out what is available.
- **Consistent** — similar operations work in similar ways.
- **Stable** — they change rarely, and when they do, changes are backward-compatible where possible.
- **Documented** — the [contract](contract.md) is explicit, not guessed at.

In agentic coding, interfaces take on special importance. An AI agent's ability to use a tool depends entirely on the quality of the tool's interface description. A well-documented function with clear parameter names and return types is easy for an agent to call correctly. A function with ambiguous parameters and side effects is a trap.

## How It Plays Out

A team defines a `StorageService` interface with methods like `save(key, data)` and `load(key)`. One implementation writes to a local filesystem, another to cloud storage. The rest of the application uses the interface without caring which implementation is behind it. When performance requirements change, they swap implementations without touching the callers.

An AI agent is given access to a set of tools: `read_file`, `write_file`, `run_tests`. Each tool has a clear interface: name, description, parameters, and return value. The agent can plan its work by reasoning about what each tool does, without knowing how they're implemented. If the tool descriptions are vague ("does stuff with files"), the agent will misuse them.

> **💡 Example Prompt**
>
> "Define a StorageService interface with save(key, data) and load(key) methods. Write two implementations: one for local filesystem and one for S3. The rest of the app should use only the interface."

## Consequences

Well-designed interfaces enable [abstraction](abstraction.md), support independent development, and make testing easier (you can substitute a mock implementation). They are the foundation of pluggable, extensible systems.

The cost is rigidity: once an interface is published and consumers depend on it, changing it requires careful coordination. This is why interface design deserves more thought than implementation design. The implementation can always be rewritten, but the interface is a promise.

---

- [Next: Consumer](consumer.md)
- [Previous: Module](module.md)