Support This Site

If you like what I do please support me on Ko-fi

Spec sheet versus failing Excel export showing why teams must spec the non-negotiables first

Stop Prompting Features. Spec the Non-Negotiables First.

Posted on

Hey everyone,

Last week a mid-level engineer on a billing team handed me a pull request that looked like a win. The ticket asked for an Excel export of invoice history. The agent produced a download button, a clean CSV converter dressed up as XLSX, and a demo that opened clean in the browser. Product celebrated the turnaround time. Then finance opened the file and noticed every currency amount was a string, timezone stamps were local machine time, and refunded invoices still appeared in the paid column. The feature worked in the chat transcript. It failed because nobody took time to spec the non-negotiables for the agent.

That gap is the story of AI-assisted coding right now. Agents optimize for the ask sitting in the prompt window. Your non-negotiables often live in tribal knowledge, a wiki nobody updates, or a senior engineer’s memory of the last incident. When those rules stay unspoken, the model invents a plausible path and you discover the missing constraints in review, QA, or production. Teams report daily agent use as normal in 2026, which only raises the volume of plausible code that still needs engineering judgment (see JetBrains Research on AI coding agent adoption).

Hi, I am Robert Massey, a software engineer and computer science professor with twenty-plus years in the trenches. Coding agents are useful tools, and they write faster than most teams explain their constraints. The missing interface is not a prettier prompt box. It is written, reviewable specs plus standards CI can enforce.

Why the amplifier framing matters

DORA amplifier diagram for teams that spec the non-negotiables before AI coding

Research from DORA’s 2025 work on AI-assisted software development frames this cleanly. AI behaves like an amplifier. It strengthens teams that already clarify intent, keep feedback loops short, and protect stability. It also intensifies mess when standards are fuzzy and review is slow. Throughput can rise while stability stays under pressure if you ship more change without stronger control systems. Context engineering, in that research sense, means giving the model durable organizational context rather than one clever prompt per ticket. Written specs and enforceable standards are that context in plain clothes. Start with the 2025 DORA announcement and the report landing page.

So stop prompting features as if the chat box is your requirements system. Spec the non-negotiables first, then let the agent accelerate implementation inside those rails. That pairs with the same practice I argued for when teams use AI to learn the system instead of skipping the practice.

Begin with reviewable intent before any generation

Reviewable engineering intent document used to spec the non-negotiables before generation

Before you ask for code, write a short artifact a human can argue with. State the user outcome in one paragraph. List acceptance criteria that a tester could fail without reading the implementation. Call out constraints the demo will happily ignore: auth boundaries, data classification, idempotency, audit fields, PII redaction, retry limits, and which services are allowed to call which APIs. Include non-functional requirements in the same place, such as latency budgets, logging fields for support, and failure modes that must surface as typed errors instead of silent zeros. Keep the document small enough that a reviewer will actually read it. Treat it like a contract for the change, not a novel.

SSO session edge case diagram that forces you to spec the non-negotiables up front

Here is a workplace example that shows the difference. Imagine an SSO auth edge case ticket: “Support users who already have a session when their IdP group membership changes.” A prompt-only path often produces a cache bust and a cheerful re-login redirect. A spec-first path would require stating whether revoked groups must terminate active sessions immediately, whether tokens refresh on a schedule or on next request, how audit events are written, and what happens for users mid-checkout. Those answers change the design. Writing them before generation keeps the agent from optimizing for the easiest happy path.

Spec the non-negotiables so CI can enforce them

Documentation that never fails a build is advice. Lint rules, type checks, contract tests, schema validators, secret scanners, and CI gates are enforcement. If your billing retry job must never double-charge on a network blip, encode that with an idempotency key test and a CI step that blocks merge when the key is missing. If Excel exports must use a shared money type and UTC timestamps, add a unit test on the serializer and refuse green status without it. If an incident follow-up required structured logging for payment failures, turn that into a required log field assertion rather than a reminder in Slack. Isaac Sacolick’s September 2026 InfoWorld discussion of AI code versus organizational standards lands on a related point: standards only protect you when they are explicit and hard to bypass. Your job is to move tribal rules into reviewable text and then into checks the pipeline can fail — the same delivery instinct as keeping SDLC fundamentals when AI speeds up typing.

Keep changes small even when the agent is fast

Keep changes small and reviewable even when the agent can draft a large patch in minutes. A thousand-line AI diff is still a thousand-line human responsibility. Split work so each pull request maps to one slice of the spec. Ask the agent for the serializer first, then the endpoint, then the UI wiring. Review for intent drift: did the code invent a new storage shape, skip a permission check, or paper over an error the spec said must bubble up? You still own the merge. The agent is a fast junior pair that never tires and never automatically shares your team’s scars.

Industry practice is drifting toward agreeing on requirements before code, sometimes summarized as Spec, then Plan, then Code. You do not need a branded workflow to benefit. You need a habit: no generation until the change has named outcomes, constraints, and checks. That habit scales better than hunting for a magic system prompt every quarter.

A mini-workflow for one mid-sized ticket this week

Try this mini-workflow this week on one mid-sized ticket. Write a one-page change brief with outcome, acceptance criteria, constraints, and NFRs before opening your coding agent. Paste that brief as the primary context, then ask for a plan and a file list only. Review the plan against the brief and correct it in writing. Generate the implementation in thin slices rather than one giant patch. After each slice, run local tests and the same lint or contract checks CI will run. Open a pull request that links the brief, lists which criteria are covered, and calls out any intentional exceptions. During review, score the change against the brief first and the style second. If the code “works” but violates a written non-negotiable, send it back without apologizing for being picky. After merge, update the brief’s reusable bits into a team checklist or a repo rule file so the next ticket inherits the standard.

What stays true for working engineers

This is not anti-AI theater. Engineers still own intent, constraints, and outcomes. When you put those in front of the model, the speed starts compounding instead of creating expensive demos. If you are also building calmer personal AI habits, start with how working professionals can use AI to improve daily life without losing control.

If this article helped, drop a comment with the first workflow you want to try this week. Support the shenanigans buying me a coffee on Ko-fi, and follow Attune IT on YouTube or me on X.

References

Leave a Reply

Your email address will not be published. Required fields are marked *