How I Lock a Decision Before It Becomes Code

Starting to code creates a strong sense of progress. With AI coding, a visible interface can appear in minutes.

That speed is useful. It also means unresolved product decisions can expand into code faster than before.

I therefore lock a small set of decisions before implementation begins.

Locking is not waterfall planning

I am not trying to predict the next six months. I only want the current increment to stop asking foundational questions while it is being built.

What problem are we solving? What is outside scope? Which domain owns the behaviour? Where is canonical state? Which states are supported? How will we accept the result?

If those answers are missing, the developer or agent will invent them during implementation. Those local inventions eventually become product architecture.

The core build contract

I use a compact structure:

Problem — the real user or system constraint. Evidence — why I believe it exists. Decision — the behaviour we are choosing. Scope — what this iteration contains. Non-goals — what it explicitly does not contain. Architecture impact — which domain, state, data and platform boundaries change. Acceptance — what observable behaviour proves the work is correct.

A clear feature may fit on one screen. Length is not the point. Ownership of the decisions is.

Why this matters even more for AI agents

Agents do not stop because requirements are ambiguous. They fill the gap.

“Improve Settings” can produce a new tab, new state, a dependency or a second storage pattern. Each choice can look sensible in isolation and still conflict with the existing system.

A strong prompt is therefore not merely detailed prose. It carries authority context:

• which source is canonical,
• which decisions are already closed,
• which dependencies are disallowed,
• which acceptance gates are mandatory,
• how production is actually deployed.

Context architecture and product architecture begin to overlap.

Protect scope with non-goals

“Fix mobile notes UX” is not a safe scope.

A stronger contract is closer to:

Problem: note selection on mobile conflicts with destructive actions. Scope: row interaction, selected state and back behaviour. Non-goal: do not redesign the notes data model, editor or folder architecture. Acceptance: at 390px a tap opens the note; archive/delete remain explicit; Android back returns one level in the expected hierarchy.

Non-goals matter because good intentions create accidental refactors.

Architecture impact makes small tasks honest

A change has architectural impact when it touches source of truth, mutation, cache, routing, platform behaviour, permissions, billing, release or shared components.

The code diff can be tiny while the risk surface is large.

Acceptance is behavioural

“Looks good” is not an acceptance criterion.

Keyboard access, visible focus, 390/768/1440 behaviour, error state, native back hierarchy and a live production commit can all be explicit acceptance conditions.

That turns QA from a later phase into part of the decision itself.

AI has made code cheaper. It has not made wrong production decisions cheap. I prefer to spend clarity before implementation rather than pay for ambiguity after it ships.