Agent operating notes

Write the ritual so the agent does not invent one

Cold-start completeness is a documentation problem as much as a code problem. One obvious way to add an operation, a map of files, and a portable skill beat folklore in folder names.

One way to add an operation

  1. 1Copy the operation template to a named file.
  2. 2Keep request, response, closed outcome, validation, persistence, provider rules, and HTTP mapping in that file.
  3. 3Map the route at the composition root. Construct the data context there. Do not register the feature in DI.
  4. 4Add a row to the feature map in the same change.
  5. 5Add a behaviour test named When_<condition>_<result>.

Feature map

A table the agent reads first. If the map is current, sibling operations do not need to be opened “just in case.”

Example feature map with method, route, file, and statuses for three operations.
Method Route File Statuses
POST/commandsFeatures/Command.csSuccess, Invalid, Declined
GET/resources/{id}Features/GetResource.csSuccess, NotFound
PUT/resources/{id}/limitFeatures/SetLimit.csSuccess, Invalid, NotFound

Product spec

Behaviour defined once: operations, domain rules, schema, seed data, and which outcomes exist. The architecture is not allowed to invent a second set of product rules.

Agent notes

Per-app notes: the ritual, the do-not-add list, the error model, and pointers to the spec and principles. Read these before changing anything.

Portable skill

The same ritual as a skill the agent can load out of tree. Description text should say when to use it: copying the template, mapping a route, updating the map.

Error model the agent can switch on

Handled outcomes return a stable HTTP success with a status field. HTTP 400 is reserved for malformed payloads. Exceptions are not the business flow. This is the only closed set this guide publishes. The feature map above lists the subset each operation can actually produce.

  • Success
  • NotFound
  • Invalid
  • Insufficient
  • Unknown
  • Declined
  • LimitExceeded

The payment reference implementation names the same seven outcomes Success, AccountNotFound, InvalidAmount, InsufficientFunds, UnknownProvider, ProviderDeclined, and DailyLimitExceeded. Same closed set, product-specific names.

Repo-root docs when more than one deployable exists

  • SPEC — product behaviour
  • SYSTEM-MAP — which app owns which operation
  • FEATURE-MAP — entry file, statuses, tables
  • AGENTS — how to add an operation in that app

The agent should not infer topology from folder folklore.

What this does to the three pillars

Token cost. A map prevents opening sibling files. A template prevents inventing eleven types. You still pay for comments and unions inside the file — that is the intended spend.

Developer involvement. Reviewers check the map row and the test name instead of hunting four projects. Forgotten DI registrations are no longer a class of review comment.

Correct output. First-pass completeness rises toward the estimated 90% when the ritual is literal. Missing a status fails the switch. Missing a map row is visible in the same diff.