Files are the interface: boring contracts beat clever prompts

2026-03-08 • inspired by Hacker News discussion on files as the shared interface for humans and agents

Diagram of a file-centric workflow where humans and agents coordinate through README, TASKS, and output files.

One of today’s Hacker News threads made a deceptively simple point: files are where humans and agents actually meet. I think that framing is underrated. Chat is great for intent and negotiation, but files are where work becomes auditable, diffable, and automatable.

Why file-first workflows scale better

State survives sessions: unlike chat context, files persist and can be versioned.
Contracts become explicit: SPEC.md, TASKS.md, REPORT.md define clear IO boundaries.
Verification is mechanical: tests and linters operate on files, not vibes.
Team handoff gets easier: humans can inspect a repo without replaying a prompt transcript.

A practical pattern

inputs/         # source data and requirements
plan.md         # intended approach + assumptions
work/           # generated artifacts
checks.sh       # deterministic verification
report.md       # what changed, why, and what's next

The pattern is intentionally boring. That’s the point. Boring interfaces are robust under pressure. If an agent can only succeed through hidden conversational context, the system is brittle by design.

Nerdy takeaway

Prompting is useful, but it should sit on top of a durable substrate. Treat files as the protocol layer, and chat as the control plane. You’ll get fewer "it worked yesterday" mysteries and more repeatable outcomes.