Chapter 3: The Language of Control¶

Vocabulary, Structure, and AI-Readable Architecture¶

1. The Constraint You Cannot Name, You Cannot Request¶

Compare two requests made to an AI assistant.

"Make the billing service match the rest of the site and don't break anything."

"Update the billing service to use the payment.gateway.v2 interface and the existing Invoice DTO; do not introduce new database calls or alter the existing error taxonomy."

The second request is longer, and none of the extra length is padding: each added term removes an option. It is more precise because it uses vocabulary that names the exact constraint. Vocabulary is the structure you impose on a task before an assistant ever starts reasoning about it.

A team that shares precise terms for its architecture can direct AI-accelerated work in a handful of words. A team without that vocabulary has to hope the AI model infers the constraints the vague prompt failed to state. When a request is under-specified, the AI fills the gap by predicting the most probable interpretation from its training distribution — and that distribution is the internet's conventions, not yours.

That gap is paid at review. A vague request produces output that looks plausible and must be checked line by line, because nothing in the request told you what to check it against. A precise request produces output that can be checked against a stated constraint.

Of the three structures Chapter 1 named, the prompt structure is the one that can only state what the team has words for. If a team lacks the vocabulary for a constraint, it cannot ask for it, and it will not recognise the wrong answer when it arrives.

But vocabulary cannot live only in a prompt, nor can it rely solely on an enforcement tool. Before an agent ever executes a command, it must first read the codebase. Therefore, this shared language must be embedded in the very fabric of the repository. This chapter is about that fabric: the names, the folders, and the types that tell an agent what is true before it writes a single line.

The rule this chapter defends: Vocabulary turns review from auditing a stranger's taste into checking a stated constraint. A term earns its place only when it makes a constraint requestable, checkable, or enforceable.

🎯 What You'll Learn¶

The power of shared vocabulary — why naming constraints precisely is the first layer of AI governance
The working vocabulary — the architectural domains an Orchestrator must define to direct work
The shape of the code — how folders, names and types act as the strongest context you can supply
Enforcement as grammar — why a convention in prose is a suggestion, and a convention in a check is a rule the gate enforces

✅ What to Check¶

Take the last three AI-assisted changes. Could the request have been more precise using vocabulary the team already has?
Name one architectural convention that lives only in someone's memory. That is the first thing to move into a shared artefact.

2. The Working Vocabulary¶

Jargon for its own sake is a liability. A shared, precise vocabulary across four domains covers most of what an Orchestrator needs to name and control.

The test for any term is simple: does it turn a vague wish into a precise, verifiable constraint?

Domain	The Vocabulary	The Constraint It Makes Requestable
Backend & Infra	`ephemeral sandboxing`, `graceful degradation`, `CQRS`, `event sourcing`	"Execute this in an ephemeral sandbox with no persistent state," or "Implement graceful degradation by returning cached data on timeout, not a 500 error."
Workflows	`policy-as-code`, `shift-left`, `GitOps`, `observability`	"Enforce this via policy-as-code in the CI gate," or "Apply shift-left validation by adding a pre-commit hook for this schema."
Software Design	`bounded context`, `contract testing`, `cyclomatic complexity`	"Respect the bounded context of this module; do not import from outside it," or "Ensure this passes contract testing without modifying internal implementation."
Governance	`the Playbook`, `prompt-regression log`, `the Law`	"Follow the Playbook step-by-step for this database migration," or "Add this failure pattern to the prompt-regression log so the agent cannot repeat it."

Three of those concepts deserve to be artefacts in their own right, because they turn vocabulary into repository reality:

The auto-feedback loop. A check that runs on every change and reports pass or fail immediately. This is fail fast and idempotency, enforced by a machine.
The platform playbook. A documented, scoped procedure for a recurring task. This is bounded context and least astonishment, written down instead of assumed.
The prompt-regression log. The record of AI-introduced failures that became permanent tests — Chapter 2's append-only record. This is the self-improving repository in action: the same mistake becomes structurally harder to repeat.

Where those terms live, who approves one, and what makes one worth keeping are the same three questions every repository answers badly by default.

Where the terms live. One file, linked from the Map — the conventions file from §5 — so a request can cite a term and a reader can look it up. A term that lives only in conversation is a term the assistant cannot read.

Who approves one. The Orchestrator. A term is a constraint the whole estate is held to, so it is a decision rather than a preference: the same authority that approves a gate approves the vocabulary that gate enforces.

What makes a term earn its place. It must change an outcome — a request can be made more precise with it, a check can fail on it, or a boundary can be drawn with it. Words like robust, scalable, and modern do none of the three, so they are refused by name.

✅ What to Check¶

Open the file your terms live in. Can a reader find the constraint behind each one, or only the word?
Pick a term you use often. Name the check that would fail if someone broke what it means.

3. The Shape of the Code: Context by Design¶

Vocabulary names the concepts. The shape of the code is what the assistant actually loads, so the layout is not only a human collaboration surface — it is the strongest piece of context you supply.

Human-readable code is no longer sufficient on its own. A bounded reader — an AI agent — does not navigate the way a person does. A person jumps around an editor, holds a mental model, and asks a colleague. An agent reads in linear chunks, stops at a context-window limit, and will not ask a clarifying question unless it is told to.

flowchart LR
    H["human reader<br/>holds history and context"] -.->|"infers from memory"| C[code]
    A["agent reader<br/>holds only what it retrieves"] -->|"follows what is written"| C
    C --> R["a correct change<br/>or a confident invention"]

What this shows: the same code, two readers — and only one of them can supply context the code does not state.

Four rules carry most of the benefit.

Folder as Context¶

Grouping files by technical layer (controllers/, services/, models/) forces a reader to cross the whole repository to understand one feature, exhausting the context window before the task starts. Group by feature or domain instead, so one directory answers one question:

infrastructure/
  network/
    main.tf              # the resources
    variables.tf         # inputs, with their constraints
    outputs.tf           # the contract other modules consume
    network.tftest.hcl   # verification

Key Insight: The boundary of the directory is the boundary of the reasoning task. What sits inside one folder is exactly what one request has to hold. This is separation of concerns, expressed where the agent actually reads it.

Explicit Over Clever¶

An assistant predicts the most likely next token. If names are abbreviated or abstract, that prediction has to guess. Descriptive, slightly boring names align the agent with your domain and reduce invention.

Weak	Strong	Why
`module "x" {}`	`module "private_subnets" {}`	the call states what is being built
`var.a`	`var.ingress_cidr_blocks`	the name is the documentation
`# loop over zones`	`# one NAT gateway per AZ: the audit log joins on the zone name`	the comment carries a constraint

Types as Guardrails¶

A type is not documentation — it is a constraint on what can be generated at all. A typed variable with a validation block closes off whole categories of wrong output before the plan runs:

variable "instance_count" {
  type = number
  validation {
    condition     = var.instance_count > 0 && var.instance_count <= 10
    error_message = "instance_count must be between 1 and 10."
  }
}

Types shrink the generation space to a valid subset. In a language without types, the boundary is a schema or a validator; the principle is the same.

Comments Explain Why, Not What¶

Do not spend context restating what the code already says. Spend it on what the code cannot say: the business constraint, the workaround, the reason a decision was made. That is the context an assistant cannot recover by reading the file.

✅ What to Check¶

Does each feature folder answer "how does this work?" without forcing the reader to leave it?
Are your types and names descriptive enough that an agent guesses their purpose correctly on the first try?

4. Enforcement Is the Language's Grammar¶

A convention in prose competes with every other instruction in the context. A convention in a check competes with nothing.

Convention	Enforced by	If it is not enforced
naming	lint rule	a plausible name that means something else
types	the type checker in the gate	`any` where the agent gave up
folder shape	a structure test	a new folder per feature, named by taste
dependency direction	an architecture test	an import that closes a loop nobody chose
contracts	a schema validator	a field added on one side of a boundary

💰 Cost Check: an unnamed constraint is paid for at review. A vague request costs one round of line-by-line checking; a named constraint costs one sentence at request time and one check at review. The expensive version is the one that reads as plausible and has no stated criterion.

The point is not policing. It is that the enforced set is the set an agent can rely on. An unenforced convention is a rule the agent must guess at, and a guess in a generated diff is a review burden with no signal.

One canonical config, thin per-repo adapters. Ten repositories with ten lint configs produce ten dialects of the same language. One canonical config with a declared exemption beats ten opinions.

✅ What to Check¶

For each convention in your conventions file, name the check that fails. If none, it is a wish.
Count your lint configs. More than one canonical configuration is a dialect problem.

5. Build the Language¶

This is the build: four artefacts, four shapes. Keep the keys; replace the tool names with your stack's.

Artefacts¶

Artefact	What it is for	Where it lives
conventions file	the language stated once, in one place	`docs/conventions.md`, linked from the Map
canonical config	lint, format and type rules shared across repositories	`config/quality/`, vendored or a shared package
architecture tests	the dependency rule, checked	`test/architecture/`
conformance check	the conventions file, tested	the commit or release gate

The conventions file, as a shape — one section per concern, each with the rule and how it is enforced:

# docs/conventions.yaml — the language, stated once
naming:        { rule: "<behaviour, not pattern>", enforced_by: "<lint rule>" }
types:         { rule: "<no untyped public boundary>", enforced_by: "<type checker>" }
folders:       { rule: "<feature slicing, one obvious way>", enforced_by: "<structure test>" }
dependencies:  { rule: "<direction>", enforced_by: "<architecture test>" }
contracts:     { rule: "<beside the implementation>", enforced_by: "<schema validator>" }
exemptions:
  - { id: "<stable name>", path: "<where>", reason: "<why>", owner: "<who>", expires: "<date>" }

The architecture test, as a shape — a rule, not a diagram:

# test/architecture/no-inward-dependency.test
domain/* may not import adapters/* or infrastructure/*
a failure names the importing file, the imported path, and the rule it broke

Sequence¶

Write the conventions file — five concerns, each with its rule. Checkpoint: every rule names its enforcement.
Vendor the canonical config and point every repository at it. Checkpoint: one config, declared exemptions only.
Write the architecture test for the dependency rule. Checkpoint: a planted inward import fails it.
Add the conformance check to the gate. Checkpoint: the gate fails on a broken convention.

Done When¶

A reader can learn the language from one file, and the file names the check for each rule.
A planted violation of the dependency rule fails before review.
No repository carries a second lint dialect without a declared exemption.

6. 🔑 Chapter Summary¶

The codebase is the prompt, and the prompt is only as clear as the vocabulary and the shape of the code.

The constraint you cannot name, you cannot request. Vocabulary is the structure imposed on a task before reasoning begins.
Review becomes checking, not auditing. A constraint with a name can be verified; an unnamed intention can only be judged.
The shape of the code is context. Feature-shaped directories, explicit naming, strict types and "why" comments shrink the generation space and bound the reasoning task.
Enforcement is the grammar. An unenforced convention is a suggestion; an enforced convention is a boundary both a person and an agent can rely on.
Four artefacts build the language: the conventions file, the canonical config, the architecture tests and the conformance check. Each needs a shape, and each needs a check.