A method for building software with AIPrinciples
- Document
- PRI-PR-001
- Status
- Draft
- Applies to
- SaaS, games, sites
Generation is cheap. Deciding what to generate, and knowing whether it is right, is not.
Priori organises software work around that fact. A priori: known before experience. Decide what is true before an agent writes it, and keep those decisions as the asset.
100.00
A model is software
A language model is a program: a fixed set of trained weights that turns a sequence of tokens into a probability for each possible next token, sampled one token at a time. Between calls it keeps nothing. Anything it “remembers” is text that other software put back into its input.
An agent is also a program: a loop of model, harness and tools. Its abilities belong to the loop, and so do its failures.
A model has no goals that outlast the call and no stake in the outcome. A reasoning trace is generated text that tends to improve the answer; it is not a reliable record of how the answer was reached.
Priori treats a model as a stochastic component and engineers it as one. Pin the version and test upgrades like any dependency. Verify every output. Never use a model where a function will do: a compiler, type checker, test or query is deterministic and cheap, and one belongs behind every model.
| Instead of | Say |
|---|---|
| “It lied.” | It output a claim with no source, and nothing required one. |
| “It understands the codebase.” | The relevant files were in its context. |
| “It forgot.” | That fact was not in this call’s input. |
| “It got lazy.” | The task had no check for it to fail. |
| “It wants to help.” | It was trained to produce answers shaped like this one. |
200.00
The minimum system
Every project is a system of four parts: You (intent), the Agent (action), Tasks (work) and the Vault (memory). Four points is the fewest that enclose a space; Fuller calls the tetrahedron the minimum system (Synergetics 400.00). Remove a part and the system does not close.
Each of the six edges is an interface, and most failures happen on an edge rather than inside a part. Give every edge an artifact. Nothing lives only in the chat.
| Ref | Interface | Artifact |
|---|---|---|
| 1 | BriefYou → Agent | Spec, acceptance checks, change dials |
| 2 | ReadVault → Agent | Design and brand specs, decision records |
| 3 | WorkAgent → Tasks | Ticket, branch, diff, handoff |
| 4 | ReportTasks → You | Result against its checks |
| 5 | RecallVault → You | History, decisions and their reasons |
| 6 | RecordTasks ↔ Vault | What the work writes back to memory, without you |
The method does not depend on the domain. A SaaS product, a game, a library and a marketing site each have an intent, an actor, units of work and a memory. Name where each lives before building.
300.00
The dynamo problem
Electric motors were practical by the 1880s, yet in 1899 they supplied under 5% of the mechanical power in American factories. Most early adopters replaced the steam engine with one large motor that turned the same line shaft, and kept the building, the layout and the work arranged around it.
The gains came with unit drive, a motor in each machine. Once power no longer ran along a shaft, plants could be single-storey, laid out by the flow of work, with lighter buildings and different jobs. Paul David drew the lesson for computing in 1990: a general-purpose technology pays off only after the work is reorganised around it, and that takes decades.
Most AI adoption today is the motor on the line shaft. The agent is bolted onto a process built around a constraint that has gone: the scarcity of human typing time. Sprints, story points, line-by-line review, pull-request size limits and ten-person teams are all ways of rationing code. When code is no longer scarce, the rationing becomes the bottleneck.
The transition costs output before it returns it. Experienced developers in METR’s 2025 study were slower with AI on their own mature repositories while believing they were faster. That is the bottom of the curve: a new motor turning the old shaft.
| Part | Floor built for scarce code | Floor built for scarce judgment |
|---|---|---|
| Unit of work | Sprints and story points | A task an agent can finish against one check |
| Source of truth | The code | The decisions in the Vault; code is regenerated from them |
| Review | Line by line, after the fact | A designed verification stage with its own checks and people |
| Team | Ten people, most of them typing | Four people ordered by judgment, each with agents |
| Memory | Hand-off documents and whoever remembers | Records the work writes as it goes |
| Measure | Lines, tickets, velocity | Outcomes against checks |
400.00
What models are for
Models are strong where the output can be checked and the pattern is common in their training data. They are weak off the distribution, where exactness is required, and where the judge is the same component as the author. Design every task so its output can be checked.
The strengths, in order of reliability: breadth, taking an unfamiliar language, API or domain to a working first version; translation between representations, from spec to code, code to tests and code to docs; iterating against a check far past human patience; search, extraction and summary at volume; and applying a known pattern.
| Weakness | Seen as | Control |
|---|---|---|
| Edge cases outside the training data | In one study every frontier model walked only the top-level files of a directory; none recursed. | List the boundaries in the spec; test each one. |
| Consistency across a codebase | Repositories that adopted Cursor gained velocity briefly and kept the added technical debt. | Decisions in the Vault, conventions as lint rules, reuse before adding. |
| Exactness: counts, pixels, colours, arithmetic | Values read off an image or estimated in prose. | Measure with a function. |
| Grading its own work | Two-thirds of developers call AI output “almost correct, but not quite”. | A check or a refuter that did not write the work. |
| Knowing what it does not know | Confident answers with invented sources or dependencies. | A citation or a check for every claim; doubt counts as refuted. |
| Stability across runs and versions | The same prompt yields different code; an update changes behaviour overnight. | Pinned versions, acceptance checks, regression evals. |
| Type | Good for | Not for | Check behind it |
|---|---|---|---|
| Frontier reasoning | Architecture, cross-module debugging, spec critique, refutation, risky reviews | Volume work, or anything a smaller model passes | A second refuter, or your decision |
| General mid-tier | Bounded implementation from a clear spec, refactors, tests | Open design | Tests, type checks, review |
| Small and fast | Search, extraction, classification, routing, summaries | Judgment; synthesis across many sources | Cited spans, re-read before use |
| Inline completion | The next few lines at the cursor | Anything beyond the cursor | The compiler |
| Embedding | Retrieval, deduplication, clustering | Generation or exact match | Spot-checked recall |
| Image and video | Concepts, mood, texture, placeholder art | Marks, type, exact geometry, anything redrawn identically | Your pick; final assets made by code or by hand |
| Speech to text | Transcription, locally and privately | Speaker attribution without review | Review of the excerpt you use |
| Deterministic tools | Everything they cover: compilers, linters, tests, queries | — | They are the check |
Route each task to the cheapest type that passes its check. When it fails, rerun it one level up with the failure attached. Deciding what to build stays with You.
500.00
Principles
- 510
Decide before generating
A priori: settle what is true before an agent writes it. Generation multiplies whatever the spec gets wrong, so the spec is the cheapest place to fix it.
CheckA problem found in review is traced to a spec line and fixed there first.
- 520
Pattern over material
A knot can slide along a rope: the knot is the pattern, the rope is material passing through it. In software built with agents the decisions are the pattern and the code is the material. Code can be regenerated; a lost decision cannot.
CheckAn agent given only the Vault could rebuild the module to the same checks.
- 530
Triangulate
The triangle is the only polygon that holds its shape with pinned joints. A claim held only by spec and implementation can swing between them; an independent check fixes it in place.
CheckNothing is done until a check the author did not write passes. SEE Fig. 500.01.
- 540
Make it checkable
A task without a check is not ready to delegate. Write the check first, or as part of the spec. Models are strongest exactly where a check exists.
CheckEvery delegated task states its acceptance as a command or a measurement.
- 550
Tension, not mass
Tensegrity holds islands of compression in a continuous net of tension (Synergetics 700.00). Lock a few things hard; hold the rest with tests, budgets and change dials. A lock opens only when its owner names it.
CheckEvery layer is locked, with a date and an owner, or governed by a dial.
- 560
Change the environment
Fuller argued for reforming the environment rather than the people in it. For a model, the environment is the context: instructions, skills, hooks and checks.
CheckA correction made twice becomes a rule, a skill, a hook or a test.
- 570
Ephemeralization
Do more with less (Fuller, 1938). Generating code keeps getting cheaper; carrying it does not. Spend the savings on cutting.
CheckThe system has the fewest parts that pass its checks; each addition names what it replaces.
The simplest system. Every rule above reduces to one: build the fewest parts that close the system, and put a check on every edge. One line, one node, one accent. A proposal that adds a second way to do the same thing fails before anyone argues taste.
600.00
People
Judgment flows up; execution flows down. Agents execute. Junior engineers direct agents, verify their output and escalate. Senior engineers direct juniors, decide architecture and keep their own agents for review and monitoring.
Judgment comes only from practice. A team that stops hiring juniors is eating its seed corn: today’s juniors are the only source of tomorrow’s seniors. Directing and verifying agents is the fastest apprenticeship in judgment the field has had.
Measure outcomes against checks, not lines written or tokens spent.
700.00 Sources
- 700.01
Paul A. David, “The Dynamo and the Computer: An Historical Perspective on the Modern Productivity Paradox”, American Economic Review 80(2), 1990, 355–361.
- 700.02
Warren D. Devine Jr., “From Shafts to Wires: Historical Perspective on Electrification”, Journal of Economic History 43(2), 1983, 347–372.
- 700.03
Erik Brynjolfsson, Daniel Rock and Chad Syverson, “The Productivity J-Curve”, American Economic Journal: Macroeconomics 13(1), 2021, 333–372.
- 700.04
- 700.05
R. Buckminster Fuller, Synergetics, 1975: 400.00 System; 700.00 Tensegrity.
- 700.06
R. Buckminster Fuller, Nine Chains to the Moon, 1938 (ephemeralization).
- 700.07
Historical Statistics of the United States, series Dd848–853 (installed horsepower in manufacturing).
- 700.08
Stack Overflow Developer Survey 2025 (“almost correct, but not quite”).