Skip to content
DomAInEspañol
Back to the six
03

Standards

What does “done well” mean on this project?

Writing the project's rules, conventions and procedures once, somewhere the agent reads on its own without being reminded.

Memory01Context02Standards03Capability04Method05Control06

The idea that outlives the tools

What you say three times, write down. What admits no exception, automate.

The model knows how software is written in general. It does not know how software is written here. That difference — the naming convention, where tests live, which library is banned and why — is not in its weights and never will be.

There are two kinds of standard and it pays not to mix them. Rules are permanent and always apply: they belong in the project's instructions file, loaded at startup. Procedures are conditional and apply to a specific task: they belong in something that loads only when that task appears, so it costs nothing the rest of the time.

There is a third level people discover late: whatever must happen every time, without exception, does not belong in text at all. Telling the model to “always run the linter” is a suggestion, and sometimes it will comply. If it is non-negotiable, it has to be a deterministic command that runs regardless, without passing through the model.

The most common mistake here is writing the instructions file as documentation for humans. It is not. It is executable orders: short, concrete, unambiguous, no introductory paragraphs.

How it works, stage by stage

That was the why. This is the machine: what happens at each stage and, above all, which decision is yours at each one. If there is a stage where you decide nothing, that stage is being decided for you by the tool.

  1. 01

    Declaration

    What happens

    The rules are written in a file that lives in the repository — not in your head, and not in the prompt you retype every morning. Whoever clones the project, person or agent, inherits them without being told.

    What you decide

    What is a rule and what is a preference of yours. Everything you declare as a rule gets applied wherever it seems to fit, including where you never meant it to.

  2. 02

    Loading

    What happens

    Some rules enter the window on every request; others load only when the task touches them. The first kind costs room every time; the second costs a judgement call, because something has to decide correctly when they apply.

    What you decide

    What earns permanent presence. A three-hundred-line instruction file is paid for on every message, including the one that only asked for a typo.

  3. 03

    Scope

    What happens

    A rule can hold for the whole repository or for one folder. In a monorepo that difference is what stops the backend's convention from being applied to the frontend.

    What you decide

    Where each rule starts and stops. A rule with no declared scope applies to everything, which is almost never what you wanted.

  4. 04

    Enforcement

    What happens

    There are two ways a rule gets followed. Written in the prompt, it is followed almost always. Executed by a tool — a formatter, a linter, a hook — it is followed always.

    What you decide

    Which ones become mechanical. Every rule you can turn into a check stops depending on the agent remembering it.

  5. 05

    Conflict

    What happens

    When two rules collide, something has to decide which wins. Most harnesses let the more specific one win — the folder over the repository — and put your message on top, but that order is theirs, not a law. If a rule only works when it beats another, say so inside the rule.

    What you decide

    Resolving the collision in the file, not in the chat. If you have to clarify it every time, the contradiction is still alive.

  6. 06

    Erosion

    What happens

    A rule nobody follows any more but that is still written down is worse than no rule: it teaches that the file can be ignored, and from then on it is ignored entirely.

    What you decide

    Deleting what died. This is the part of the upkeep no tool does for you.

Signs you are missing it

  • You repeat the same style correction every session.
  • Two similar features were solved two different ways.
  • You explain the same procedure every time that task comes up.
  • You asked for “always do X” and sometimes it does not.

Common mistakes covering it

  • Writing the instructions file as long prose. Nobody reads it and the agent dilutes it.
  • Putting everything in the permanent rules. What applies to one task costs context in the other thousand.
  • Trusting a prompt with something non-negotiable instead of a deterministic command.

Jobs that lean on this discipline

Practices that cover it

Ways of working, not products. You apply them with whatever tool you already have.

SDDSpec-driven developmentWrite the contract — what has to happen, and how it will be checked — before asking for the code, then verify against that contract rather than against your memory of what you wanted.RDDReceipt-driven developmentHave review produce a receipt bound to the exact content reviewed, and have every exit point — commit, push, pull request, release — validate that receipt instead of reviewing again.ADRArchitecture decision recordsWrite down the decisions the project has to live with — the ones that cost an argument, and the ones nobody argued about because they did not look like a decision at the time — in a short file with the context, the options, the one you took and what it costs you, versioned with the code.DDDDomain-driven designUse the business's own words in the code, one meaning per word, and put an explicit border where that meaning changes.Ports and adaptersHexagonal architecturePut the business rule at the centre, isolated, and leave outside everything that can change: the database, the framework, the interface — and the model.

Tools that cover this discipline

None of them is mandatory. Covering the discipline is mandatory; these are known ways of doing it.

AGENTS.md

Open standard, Agentic AI FoundationFile

A file in the repository holding the project's rules, which the agent loads on its own at startup. An open format read by a couple of dozen agents, from Codex and Gemini CLI to Cursor, Copilot and Devin.

Problem, mechanism & fit
The actual pain
Repeating “use pnpm”, “tests go here”, “don't touch that folder” in every conversation is pure waste, and it walks out when the team changes.
How it works
The agent reads the file at startup and prepends it to context. Tool-specific equivalents — CLAUDE.md in Claude Code, and others — are adapters around the same project knowledge: the contents are portable, while the filename, the loading rules and the precedence between several of them belong to the harness. It is the cheapest coverage there is and the most underrated: it costs an afternoon and depends on installing nothing.
When it fits
Always, and it is the first thing to do. The usual mistake is writing it as documentation for humans: these are executable orders, short and unambiguous.

Agent Skills

Anthropic, open standardPackage

Procedures packaged as a folder — instructions, scripts, resources — that the agent loads on its own when the task that needs them appears.

Problem, mechanism & fit
The actual pain
The agent solves the same task differently every time, and your team's correct way of doing it is not in its weights.
How it works
A directory with a SKILL.md at its root: instructions, plus a description of when they apply, plus whatever scripts and files the procedure needs. Loading is progressive — the agent holds only the name and description until a task matches, then reads the rest — so what an idle skill costs you is its description, not its contents.
When it fits
When a procedure repeats and has a right answer. It is the difference between asking for an outcome and teaching a method.

Also helps with

Skills for Real Engineers

Matt PocockPackage

Control

A procedure collection built around the specific failures of AI-assisted development.

Hooks

Ecosystem patternPattern

Control

Deterministic commands that run at defined moments, without passing through the model.

Claude Code

AnthropicHarness

Capability

Terminal agent with declared permissions, hooks, subagents and skills; also on desktop, web and IDEs.

Codex CLI

OpenAIHarness

Capability

OpenAI's terminal agent, with support for procedures and external services.

OpenSpec

Fission AIWorkflow

Method

File-backed spec-driven development: what is already agreed, kept apart from what is being proposed.

Gentle AI

Gentleman ProgrammingWorkflow

Method

Reproducible configuration installer, spec-driven phased development, and review with a budget.

gstack

Garry TanWorkflow

Method

Twenty-plus procedures assigning product roles — product, design, QA, release — across a sprint cycle.