Prompt · gate 4
Observed backend conventions
When the backend has code but no written conventions: the agent describes the ones the code already follows, and the backend owner confirms, corrects or rules them out.
File prompts/gate-4-observed-conventions.md
Describe the backend conventions the code already follows
A method by Alexis Boyer · version 4.0 · September 22, 2026
Gate 4. When the backend has code but no written conventions. The agent describes the conventions the code already follows — a recipe for the most common change, each rule with its examples and its count, what is deprecated, the questions only the owner can answer — and the backend owner confirms them, corrects them, or marks what must not be copied. It is quoted here exactly as it appears in the core guide.
What you fill in
Four brackets to replace, brackets included — three things to fill, since the backend owner appears twice.
[THE BACKEND REPOSITORY], near the top: the path of a fresh clone of the backend, made beside the project repository from where your organization keeps it. A fresh clone carries nobody's keys; a developer's own copy may. Run the prompt in a mode of your assistant that asks before it runs a command or writes outside the project repository.[ANYTHING IN IT THAT IS OFF LIMITS, …], the next line: folders or files it must not open even to read — ask the backend owner. If you cannot yet, replace the bracket with “nothing more”: the prompt already keeps the agent out of keys, environment files and data.[THE BACKEND OWNER], twice, near the end: the person or team who reviews backend work; Backend and API Ops can name them. Not you: a Product Builder cannot tell a convention from a debt, and is not asked to. If there is no backend owner, name the lead accountable for engineering, and read the core guide's Gate 4 before you run it.
Two files come back in docs/. Send the draft to the backend owner. Send the security notes to the backend owner alone, never into the channel and never into a commit, then delete them from the repository.
The text to copy
You are at Gate 4 of the method. The backend has code but no written
conventions. Your job is to describe the conventions the code actually
follows. You do not decide them.
You may read, and only read: [THE BACKEND REPOSITORY].
Do not open, even to read: [ANYTHING IN IT THAT IS OFF LIMITS, or "nothing more"].
Run nothing from the backend repository: no install, build, test, script
or migration. Reading the code and its history is enough. Do not change
anything in it, and write nothing outside the project repository — not
even a helper script. Do not open environment files, key or certificate files,
infrastructure state, database dumps or exported data. Answer where secrets
and configuration live from the code that loads them, not from the files
that hold them. If a value that looks secret appears anyway, give the file
and line, never the value.
Start from what the team already enforces or wrote down: linter and
formatter configuration, CI checks, the pull-request template, the README,
contributing notes, architecture decision records, release and upgrade
notes. Then read the code.
First, the recipe. Take the most common kind of change — usually a new
model, field or endpoint — and describe how the code makes one, end to end:
the base classes it uses, every file a change of that kind touches, in
order, and the one or two existing examples to copy. If there are several
common kinds, give a recipe for each.
Then answer, at the least, these questions:
- where code goes, and how it is layered
- how input is validated where it enters, and how errors, timeouts and
retries are handled on the server
- how the data model changes, and how a migration is written so that the
version still running keeps working during a deploy and after a rollback
- how an API contract is documented, changed and versioned
- how a request that arrives twice is kept from doing the work twice
- how transactions and concurrent writes are handled
- where work that does not finish inside the request goes, and how it is
retried
- how permissions are checked, on writes as well as on reads
- where secrets and configuration live
- what the code logs and measures, and what it avoids logging
- what response times and load it is built for, if anything says so
- how environments and infrastructure are described and changed
- how dependencies are added
- which tests exist, and at which level
- what security checks exist
- how unfinished work ships switched off, and how a release is rolled back
For each point, write:
- the rule, as one sentence a change can be checked against
- one or two real examples: the file and the line
- the basis: how many places you looked at, how many follow it, and how you
counted — a class counts when any of its bases matches, not only the first
- whether it is enforced by a tool, followed without enforcement, or
inconsistent — and whether recent and older code differ
- "Status: observed". Only the backend owner changes it, to confirmed,
corrected, or debt not to copy.
Anything the code or the notes mark as deprecated, legacy or scheduled for
removal is never a rule: list it under "Deprecated — do not copy", with
what replaces it when something does.
Put first the questions the backend owner must answer before anyone builds
on this: no more than ten, ranked by what they would block. Leave out what
the code or the notes already answer. Do not settle them yourself.
Write the result in the project repository, never in the backend
repository: `docs/backend-conventions.observed.md`. Its first line says:
"Observed, not approved — a draft for [THE BACKEND OWNER] to confirm,
correct, or mark as debt not to copy."
What could be a security weakness does not go in that file, which will
circulate: write it to `docs/backend-security-notes.md`, for
[THE BACKEND OWNER] only, and say in the draft that such notes exist,
without their content.
Then stop: what you wrote is not a convention until the backend owner
confirms it. Append an entry to the project journal saying what you read
and what you wrote, without the content of the security notes. State which gate you are at, what you have, what is
missing, and what I must decide before you cross. Saying what you will do
next is not permission to do it: you cross when I answer, not when you
announce.