Constraints — what you were not free to choose

The distinguishing question is whether you had a choice. If you did and you made it, it is a decision and it belongs in the decisions folder with its rejected options. If you did not, it is a constraint: you can note that you dislike it, but there are no alternatives to enumerate because none were available to you.

The line matters because the two are reviewed differently. A decision is revisited when the goal it serves changes rank. A constraint is revisited when the external fact changes — a contract ends, a licence expires, a team reorganises, a regulation lands. Filing one as the other means it gets reviewed on the wrong trigger, which in practice means never.

And a preference is neither. "We use this ORM" is a preference unless something forced it. The test is whether you can name the external fact or the authority that removed the choice. If you cannot, you are recording taste, and taste in the constraints list is how a team ends up believing it is trapped by something it could change tomorrow.

Technical: a mandated runtime, a legacy interface you cannot change, a fixed integration protocol, a device or browser floor. Usually the most visible in the code and the least contentious to write down.

Organisational: team boundaries, who owns which system, the size of the team, the fact that a required skill exists in one person. These shape the architecture more than most technical constraints do — Conway's law is not a metaphor — and they are the ones teams are most reluctant to write down, because they read as criticism.

Regulatory: data residency, retention floors and ceilings, auditability, consent, sector-specific regimes. Non-negotiable, expensive to discover late, and the type most likely to be stated second-hand and inaccurately. Cite the actual obligation, not the summary someone repeated in a meeting.

Commercial: contractual response times, licence terms, a fixed launch date, a vendor commitment tied to a discount. These expire more often than any other type, which is exactly why they need dates.

"We cannot use managed services" survives for years after the person who knew why has left. Then two things happen: engineers route around it in ways nobody planned, and any attempt to challenge it fails because there is nothing to challenge — no reason to examine, only a rule.

So the reason is not documentation courtesy, it is the mechanism by which a constraint can be retired. One sentence naming the authority or the external fact — the security review of 2025, the contract with this customer, the regulation, the fact that only one team can deploy to that network — is what makes the constraint falsifiable later. Without it, the constraint is permanent by default.

Most constraints are true for a period. A licence runs to a date. A legacy system is scheduled for decommission. A team is short-staffed for a quarter. A deadline passes. Write the date, and the constraint stops being a permanent feature of the landscape and becomes something with a known end.

Where no date is knowable, write the condition instead: valid while we are on this contract, while that system exists, while the team is under five people. A condition is checkable in the same way a date is, which is all the review needs.

The cost of skipping this is specific and common: an architecture still paying for a constraint that ended eighteen months ago. Nobody re-examines a rule that presents itself as permanent, and the work it forces looks like normal engineering overhead rather than a bill for something that no longer exists.

A constraint list that reads as neutral facts is missing its most useful column. Note what the constraint prevents or makes more expensive: the deployment model it rules out, the goal it caps, the workaround it forces you to maintain.

That is the sentence that gets a constraint removed. Somebody with the authority to change a vendor contract or a team boundary will not act on a line in a spec, but they will act on the observation that it is costing a week per release. It is also what stops a quality goal from being written in a way the constraints make unreachable — the conflict becomes visible at authoring time rather than at delivery time.

Where data may live, how long it must be kept, how long it may be kept, and who may see it in an incident — these now appear in ordinary commercial contracts, not just in regulated sectors. They are architectural, because they decide region topology, backup strategy, log handling and which managed services are even usable.

Discovered late, they are the most expensive class of constraint there is: a residency requirement that arrives after launch is a data migration and a redeployment, not a configuration change. Ask for them during design, and record which customer or regime each one comes from — because the answer is frequently one contract, and one contract can be renegotiated.

Where model inference may run, whether provider training on your data is permitted, what has to be disclosed to a user, what must be logged for an audit, whether a human decision point is required. These behave like classical regulatory constraints and they land on features teams often treat as experimental.

The practical failure is scope drift: a constraint accepted for a prototype — no customer data leaves this region, no third-party model — is silently violated when the prototype becomes a product and someone adds a provider. Record it as a constraint with the feature named, so the next person adding a model call meets it in the spec.

On a team using an internal platform, a real share of the architecture is not chosen: the deployment target, the ingress, the service mesh, the base images, the observability stack, the languages the pipeline supports. That is usually a good trade, and it is still a set of constraints.

Write them as inherited, with the platform named and, if there is one, the escape hatch. Two failures follow from leaving them out. A team designs something the platform cannot deploy and finds out at the end. Or a team treats a platform default as immovable when an exception process exists — and pays for years to avoid a conversation it never had.

Reserved capacity, committed spend, discount agreements tied to a vendor's services. They are commercial constraints with hard dates, and they legitimately shape a design — but only until the term ends.

This is where dated constraints pay most obviously. A commitment expiring in fourteen months is a planning input; the same commitment recorded as "we are on this cloud" is a permanent conclusion. Same fact, two very different architectures downstream.

The team is four people. One person understands the payment integration. Two teams share a database because they used to be one team. Deploys need a change window because a separate group owns the network. These constrain the architecture at least as hard as any technical rule, and they are almost always absent from the spec.

Write them factually and without blame: the constraint is the structure, not anybody's competence. A spec that records "one team owns both services, so the boundary between them is not enforced by process" is describing a real property of the system. Left unwritten, the same fact shows up later as an unexplained coupling that the next architect will read as an error.

A decision usually leaves fingerprints: an interface, a pattern, a package boundary an agent can notice and follow. A constraint often leaves nothing at all. Code that keeps data in one region looks exactly like code that has never considered regions. Code that avoids a licensed library looks like code that did not need it.

So the agent infers freely and adds the obvious dependency, the convenient managed service, the second region for resilience — each a reasonable suggestion in general and a violation here. The cost is not the wasted patch; it is that the reviewer has to hold the entire constraint list in their head to catch it, every time.

Constraints are the cheapest high-value entries in spine.yaml: an id, one line of text, a type, a reason, an expiry. Ten of them cost almost nothing in a context window, which means they can be included in every session rather than fetched when someone remembers to.

Prefer the enforceable phrasing. "No third-party model providers for customer data" is checkable; "be careful with customer data" is not. Where a constraint can be expressed as a rule about the repository — a banned dependency, a forbidden import, a region allowlist — it should also become a guardrail, because prose in a prompt is guidance and only the check is enforcement.

An agent cannot discover that your largest customer's contract forbids something. It is genuinely good at the upkeep: finding constraints referenced in decisions but absent from the list, flagging the three whose expiry dates have passed, noticing that a proposed change conflicts with C-4, spotting that two constraints say incompatible things.

That is the right division. The list's content comes from contracts, regulators and the organisation chart; the hygiene — completeness, expiry, contradiction — is mechanical, and mechanical work is what the agent should be doing.

A stale constraint used to slow a team down. Now it also steers every agent session: each one designs around a rule that ended last year, and the resulting code looks correct because it is internally consistent and passes review.

Which makes the expiry field an operational control rather than an act of tidiness. Check the dates on the same cadence as the quality-goal ranking, retire what has ended, and note the retirement — the decisions taken under a constraint that no longer exists are exactly the ones worth reopening.