Recent research suggests that ADR (Architecture Decision Record) can dramatically improve the reasoning efficiency of coding agents. But in traditional ADR, two fundamentally different types of information coexist in the same document: "why we chose this technology" and "what we must never do with this technology."
sqlew manages these as separate entities — Decision and Constraint — each with distinct enforcement characteristics. Experimental data reveals that this separation drives unexpectedly significant changes in AI reasoning patterns.
Decision Records Rationale; Constraint Binds Behavior
A Decision in sqlew is a record that pairs a design judgment with its rationale. It includes context, the decision itself, and the reasoning behind it. Status management tracks progression from proposed through accepted to deprecated.
A Constraint is an invariant derived from Decisions, managed as an independent entity with a priority field. It encompasses both prohibitions and recommendations, explicitly defining the boundaries of AI behavior from both the "do" and "don't" sides.
Think of it as extracting the constraint information traditionally buried in an ADR's "Consequences" section into standalone structured data.
Decisions Change How AI Thinks: Elevated Architectural Awareness
Analyzing keyword frequencies extracted from the LLM's thinking logs across a 12.5-turn controlled experiment confirmed distinct reasoning pattern shifts when Decisions were recorded.
Architecture-related keywords (architecture, pattern, design, layer, etc.) appeared at consistently higher rates in the Decision-present condition across all periods, while the no-Decision condition showed declining frequency over time. With the "why" behind design judgments recorded, AI preserved its design perspective even while deep in implementation.
More striking was the trajectory of prior decision reference frequency (decision, constraint, previous, documented, etc.):
| Period | With Decisions | Without | Difference |
|---|---|---|---|
| Early (T1-4) | 6.2 | 5.2 | ±5% |
| Middle (T5-11) | 12.7 | 7.8 | +107% |
| Late (T12+) | 11.4 | 4.8 | +137% |
(keyword occurrences per 10K characters of thinking log)
The Decision-present condition's advantage accelerated over time. As ADRs accumulated, reference frequency rose, promoting consistent decisions that drove further ADR accumulation — a positive feedback loop.
Constraints Prevent AI Overreach: The Rework Convergence Pattern
Decisions alone carry a risk: AI may prematurely implement "future design intent" recorded in ADRs. This phenomenon was indeed observed during the experiment.
Constraints proved effective here. By explicitly stating "do not implement unspecified features," Constraints serve as "brakes" against the "accelerator" that Decisions provide.
This effect appears clearly in the frequency of backtracking and reconsideration keywords (wait, actually, let me reconsider, etc.) in the thinking logs:
| Period | With Decisions | Without | Difference |
|---|---|---|---|
| Early | 3.6 | 2.1 | +66.8% |
| Middle | 8.5 | 4.0 | +112.3% |
| Late | 4.8 | 4.8 | −1.2% |
(keyword occurrences per 10K characters of thinking log)
The higher Rework density in the Decision-present condition during early and middle periods reflects AI carefully consulting Constraints to assess "should I do this now?" The convergence in the late period is the key finding: Constraints had become internalized. What began as externally referenced rules gradually became embedded in AI's judgment criteria, eliminating the need for explicit re-verification.
This is a visualization of the learning curve itself.
Deliver the Accelerator and Brake Together
sqlew's separation of Decision and Constraint is designed to structurally communicate "what to do and why" (Decisions) alongside "what boundaries must not be crossed" (Constraints) to AI agents. Decisions elevate thinking quality through recorded rationale; Constraints promote efficient judgment by making behavioral boundaries explicit.
Just as developers wouldn't drive a car without brakes, AI agents need both accelerator and brake. sqlew's Decision and Constraint system delivers exactly that.
References
- "Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation" — Shingo Kitayama (2026) — sqlew Efficacy Study
- "Scaling Reasoning, Losing Control: Measuring Instruction Following in Reasoning Models" — He et al. (2025) — arXiv:2505.14810
