Software Engineering Rules for AI Coding Agents

Why AI Agents Need a Rules File

An AI coding agent is fast and confident, and it has no memory of your last code review. Left alone, it will name a controller one way today and another tomorrow, store a delete as a hard delete in one feature and a soft delete in the next, and skip the CancellationToken whenever it is inconvenient. The output compiles, which makes the inconsistency easy to miss until it has spread.

A rules file fixes that. It is the single authoritative standard the agent must consult before it writes anything: how files are named, where they live, how data is persisted, how errors are handled, and what "done" means. In this workflow the file is SKILL-SOFTWARE-ENGINEERING.md, and it is the technical counterpart to the business-side data dictionary. The dictionary says what to build; the rules say how to build it.

The payoff is consistency across every generated file. When 18 or more files come from a single entity, consistency is not a nicety — it is the difference between a codebase a team can maintain and a pile of plausible-looking code.

There is a second, quieter benefit: the rules file is institutional memory. A new developer — or a new AI model — inherits the standard by reading one document instead of reverse-engineering a dozen features. That is the same reason teams write style guides, except here the reader is an agent that would otherwise re-decide everything from scratch on every prompt.

What Belongs in Engineering Rules

A good rules file is opinionated and short. It should leave no room for the agent to pick a default. These are the sections that change the generated code the most.

Naming and folder structure

Define where each kind of file lives and how it is named. In this standard, an entity lives under an area, a controller is named for the entity, and the Razor views and their collocated JavaScript sit together. The collocated script must be referenced by its physical path, ~/areas/{Area}/{Entity}/Views/{Page}.cshtml.js, because that is where the application looks for it. The last segment of an endpoint names the entity, and lookup endpoints follow /api/{entitylower}/{lookupentitylower}-lookup. Naming rules like these are easy to state and easy to check.

Soft delete and query filters

Deleted rows are never physically removed. Deletion is a soft delete, enforced by a global query filter configured once on the entity. The rule for code is absolute: never write an explicit !x.IsDeleted check in a query, and never call .Remove(). If a developer has to remember the filter in every query, someone will forget; if the filter is global, nobody can.

CancellationToken policy

A CancellationToken is mandatory on every CQRS handler and every Minimal API endpoint. It is threaded through to the data access call so a cancelled request actually stops work. This is another rule that is trivial to verify mechanically: a handler method signature either accepts a token or it does not.

Validation with FluentValidation

Validation lives in FluentValidation validators, not in data annotations on the entity, because the database stays open in this standard. The rules file should say which validator accompanies which command and where it lives. Putting validation in one place keeps the entity clean and keeps the rules testable.

The build gate

Define what "done" means. Here, after every feature the agent runs dotnet build and fixes all errors until the build reports zero. The agent never runs the application; a human tests it at runtime. The build is the automated ceiling of verification, and stating that clearly stops the agent from claiming success it cannot prove.

18+ Files From One Entity

One of the most useful rules is simply the file set. Given a single entity class, the standard produces a full vertical slice: a controller, the CQRS handlers for list, get-by-id, create, update, delete, and lookup, the validators, the endpoint mapping, the Razor views, and the collocated JavaScript. That is 18 or more files, and the agent should generate all of them in a consistent shape rather than improvising each time.

{Entity}/
  Controllers/{Entity}Controller.cs
  Features/{Entity}/
    List/List{Entity}Handler.cs
    GetById/GetById{Entity}Handler.cs
    Create/Create{Entity}Handler.cs
    Update/Update{Entity}Handler.cs
    Delete/Delete{Entity}Handler.cs
    Lookup/{Lookup}LookupHandler.cs
    Validators/Create{Entity}Validator.cs
    Validators/Update{Entity}Validator.cs
  Endpoints/{Entity}Endpoints.cs
  Views/{Entity}/Index.cshtml
  Views/{Entity}/Index.cshtml.js   // collocated script

The file set is part of the rules because repetition is the point. When every entity yields the same structure, a reviewer knows where to look, and the agent has a template instead of a blank page. It also makes the AutoNumber rule easy to apply everywhere: every entity implements IHasAutoNumber, and the generated value follows the format {ToShortNameConsonant(3)}/{Year}/{4-digit}, such as PRD/2026/0001, CNT/2026/0001, or TOD/2026/0001.

The READ-FIRST Protocol

Before the agent writes a single file it must read a canonical reference implementation in full. The standard names three shapes to cover the whole design space: Country for a Pure Master, Currency for a Master with Lookup, and Todo for a Master-Detail. The agent reads the relevant reference completely — not a summary, not a snippet — and then mirrors it.

This protocol is what turns a rules document into consistent code. Rules describe the shape in prose; the reference implementation demonstrates it in full. Reading first means the agent copies a known-good pattern, including the small details that prose usually omits, such as how a lookup endpoint is wired or how the collocated script is included. It also decides entity type detection mechanically: a Pure Master has no foreign key or collection, a Master with Lookup declares string {X}Id plus {X}?, and a Master-Detail declares ICollection<T>? Items.

Make Rules Mechanically Checkable

The best rules are not adjectives; they are checks. When a rule can be verified by a command, it stops being a matter of trust and becomes a gate.

• Build: dotnet build must report 0 errors after every feature. This is the primary gate.
• JavaScript: validate generated scripts with a syntax check such as node --check, or at minimum a brace-balance check, so a missing brace cannot slip into a view.
• CancellationToken: confirm every handler and endpoint signature accepts a CancellationToken.
• Collocated path: confirm each view references its script at ~/areas/{Area}/{Entity}/Views/{Page}.cshtml.js.
• Soft delete: confirm there is no hand-written IsDeleted filter and no .Remove() call.

None of these require judgement, which is exactly why they belong in the rules file. A rule that a script can check is enforced on every feature, every time, without a human in the loop.

Where a rule cannot be fully automated, make it a checklist item with an unambiguous answer. "Does each view reference its collocated script by physical path?" is checkable; "is the code clean?" is not. Every rule that passes that test removes a class of review comments a human would otherwise have to catch by reading the whole feature.

Key Takeaways

• A rules file turns ad-hoc generation into a repeatable standard, so every feature looks the same.
• Define naming and folders, soft delete with a global filter, the CancellationToken policy, FluentValidation, and the build gate.
• One entity yields 18+ files: controller, CQRS handlers, validators, endpoint mapping, views, and collocated JavaScript.
• The READ-FIRST protocol has the agent read Country, Currency, or Todo in full before writing anything.
• Make rules mechanically checkable — dotnet build with 0 errors is the ceiling, and a human tests at runtime.