Agent Context Examples

Illustrative only. The AI Agent Context page states the rules; this page shows the shapes.

1. A root AGENTS.md

Everything here is true for every stack in the repo. Framework rules live in the stack files.

AGENTS.md

## Read first
- README.md — scope, stack, first-time setup
- docs/architecture.md — topology, project boundaries, data ownership
- docs/adr/README.md — accepted decisions (start at the index)

Stack rules: backend/AGENTS.md · frontend/AGENTS.md · mobile/*/AGENTS.md
Read this file plus the stack file you are working in.

## Big picture
Browser → Angular SPA → FastEndpoints API
                          ├── AppDbContext     → app-sql (writable)
                          └── ErpReadDbContext → erp-sql (READ-ONLY)

## Non-negotiable rules
- Never write to the ERP database. Migrations target AppDbContext only.
- Never collapse AppDbContext and ErpReadDbContext — that split is the
  load-bearing safety mechanism (ADR-0003; SaveChanges throws).
- Do not edit an applied migration — add a new one.
- Protected endpoints enforce authorization server-side, not only in guards.

## Commands
Run from the stack directory, not the repo root.
- Start everything: scripts/run-apphost.ps1
- Backend tests:    dotnet test  (add --filter "Category!=RequiresDocker" without Docker)
- Frontend:         npm test · npm run build

## Verification discipline
Run the narrowest useful check for the change. If it cannot run locally
(no Docker, for example), say so in your final response rather than
skipping silently.

## Standards — follow these, don't restate them
- https://<wiki>/engineering/
- Decisions: /docs/adr in this repo
- Rules are enforced in CI; the linter is the standard.

That is ~40 lines and it is doing real work. Note what is absent: no coding style, no branching model, no restated ADR text.

2. The pointer file

The entire CLAUDE.md:

CLAUDE.md

The canonical instructions are in [AGENTS.md](./AGENTS.md) beside this file.
Read that. This file exists only so tools that look for `CLAUDE.md` find it.

Committed as a real file — not a symlink. core.symlinks is unreliable across Windows clones, and a broken symlink means the agent silently gets no instructions at all.

3. A stack file’s routing table

The highest-value six rows in any context file. It answers the question agents get wrong most often, in less space than a paragraph explaining the layering would take.

## What goes where

| You want to add… | It belongs in |
|---|---|
| Pure business behaviour or an invariant | `DomainModel/` |
| An EF mapping or a migration | `Infrastructure/Persistence/` |
| An endpoint + its DTO and validator | `ApplicationAPI/Endpoints/<Feature>/<UseCase>/` |
| A contract for an external system | `Integration.Abstraction/` |
| An HTTP adapter for that contract | `Integration.Implementation/` |
| A cross-cutting host concern | `ServiceDefaults/` |

4. The size gate

The budget is only a rule because something checks it.

- script: |
    fail=0
    for f in $(git ls-files '**/AGENTS.md' 'AGENTS.md'); do
      lines=$(wc -l < "$f")
      if [ "$lines" -gt 200 ]; then
        echo "##vso[task.logissue type=error]$f is $lines lines (max 200)"
        fail=1
      elif [ "$lines" -gt 150 ]; then
        echo "##vso[task.logissue type=warning]$f is $lines lines (target 150)"
      fi
    done
    exit $fail
  displayName: 'Agent context files stay inside budget'

5. A rule that earns its line, and one that does not

<!-- Earns it: names the incident and demands a checkable artifact. -->
## Performance impact
Every change ships with an answer to "how often does this run, and what does
it cost per run?" A 4.9 regression added one provider that fired ~20 ERP
queries on *every* authenticated request. When you touch a per-request path,
a loop over I/O, or a background job, state the calls-per-run before and
after in the PR.

<!-- Does not: true, harmless, and already in the model. Delete it. -->
## Think before coding
Don't assume. State your assumptions. If something is unclear, ask.

Back to AI Agent Context.