Contracts, Not Vibes: Guardrails for Humans and Agents

When I drop into an existing system, the presence of a living spec is the first telltale sign that you can trace intent to implementation without playing archaeologist. Greenfield or legacy, the promise is the same. You argue once, clearly, before you code, then let the spec carry the weight of alignment. Done this way, reviews stop being taste debates and become checks against an agreed contract, onboarding stops being oral tradition and starts at a single, source-of-truth document. Contract-first isn’t just ceremony for ceremony’s sake, it’s an anchor light enough to keep moving and heavy enough to keep us honest.

The advantages compound in real world projects, half-migrated stacks, overlapping paradigms, institutionalized memory in slack conversations too long to comprehend. A concrete interface contract lets you stand up mocks, generate client stubs, and run contract tests that fail fast when something important shifts. It turns quality and security reviews from forensics into verification, because behaviour is documented upfront, checked into the repository and testable. Under pressure, this doesn’t slow teams down, it removes the social friction of asking why we are doing something in a certain way by pointing to the artifact where the decision lives. Architectural Decision Records are the companion practice that makes the map three-dimensional. Specs say “what”, ADRs say “why now, why not that, under which constraints”. On stable senior teams they’re memory, on mixed or junior teams they’re governance without theatrics. I ask every meaningful change to carry an ADR written like a decision, not a diary. Context, options considered, trade-offs, consequences, date and most importantly kept close to the code. While people move on, the log becomes an organisational cortex. Start small: one template, one repo, one decision per change. It’s astonishing how much rework you avoid when “because we decided” links to a diff instead of a story retold.

Regulated environments make this non-optional. Auditors don’t grade your eloquence, they look for traceability. How did you move from requirement to spec, spec to code, code to tests, tests to gates and change control when the requirements move. Treat the spec as a first-class object in the SDLC and the cycle tightens. Evidence is generated as a byproduct of normal work instead of an end-of-project scramble. Security teams can reason about surface area from schemas, and compliance can follow the breadcrumb trail without interrupting your process.

We’re also building in an era of agent support, which raises the stakes. An eager AI pair-programmer will accelerate drift at unprecedented speed if you leave it unsupervised, but with guardrails it becomes an amplifier for good habits. The pattern that works is boring on purpose. If you make the spec the contract, make prompts reusable and reviewed like code, log agent decisions and intermediate reasoning where possible and route contributions through CI that checks conformance to the contract before a human ever writes a line of code, even a critic like me can't argue with the benefits of AI in SDLC. Treat prompts and tool configurations as change-controlled artefacts with owners and versions, lint them, test them and review them. The result isn’t magic, just fewer surprises, faster feedback and a defensible trail from intent to change. If instead you’re inheriting a system, you don’t need executive air cover to start. Extract the implicit contract into an explicit spec at the seam you touch most. Add a thin layer of contract tests. Begin rejecting changes that violate the agreement. Introduce ADRs where the pain already lives and write the first few yourself to model the tone. Let your first agents operate only inside the safest corridors, code generation behind a well-understood API, documentation updates sourced from the spec, test scaffolding that CI will happily fail if it diverges. Trust accrues where it’s earned and the spec plus ADR habit gives juniors a way to reason about trade-offs without having to guess what seniors intended.

Underneath all of this sits culture. Specs and ADRs nudge teams away from certainty theatre and toward curiosity. The spec invites “what should happen?” before the argument about “how” even arises. The ADR invites the trade-off into daylight so the next person can improve it rather than relitigate it. Over months this compounds into quieter on-call and calmer planning, because reality lives closer to what’s written down. It also gives you a language to say “no” that isn’t performative.