The Documentation Layer — Standards an Agent Can Follow

AI assistants read your repository's documentation the way a diligent new developer would — except they read it on every task, instantly. That makes a thin set of well-structured documents the highest-leverage AI investment a large ASP.NET MVC repo can make. The goal isn't documentation for its own sake; it's turning implicit conventions into text an agent can retrieve and obey.

The core document set

A practical baseline (and exactly what the capstone's Repository Initialization Platform generates):

• README.md — what the system is, how to build/run/test it locally. The front door.
• ARCHITECTURE.md — the layering (controllers → services → repositories), project map, key data flows, and why the big decisions were made.
• CODING-STANDARDS.md — naming, async rules, error handling, logging, DI patterns — written as enforceable statements ("controllers contain no business logic; they validate, call a service, map to a ViewModel"), not vibes ("keep code clean").
• CONTRIBUTING.md / RUNBOOK.md / SECURITY.md — branch/PR workflow, operational procedures, and the security boundaries an agent must never cross.
• The AI instructions file — CLAUDE.md, .clinerules, or copilot-instructions.md depending on your tooling. This is the one the agent loads every session: the distilled rules, the landmines ("the legacy Reports area is frozen — don't refactor it"), and how to verify changes.

Write for retrieval, not for a bookshelf

These documents double as RAG source material, so structure matters: clear headings (they become chunks), one topic per section, concrete examples over abstractions, and explicit names — "the ClaimApprovalService owns all approval state transitions" retrieves; "the service layer handles workflows" doesn't. State the why alongside the rule, because agents (and humans) extrapolate correctly only when they understand intent.

Stale documentation is worse than none

An agent treats your docs as ground truth. If ARCHITECTURE.md describes a layering you abandoned two years ago, the agent will faithfully build to the wrong design — a confidently misleading repo. So: keep the documents in the repo (versioned with the code they describe), review them in PRs that change what they document, and periodically ask an AI to audit them against the code ("list claims in this doc that no longer match the codebase") — a cheap drift detector. This is also why generating the initial set with a tool beats a heroic manual writing effort: the marginal cost of regeneration is low, so the docs can actually track reality. The discipline is the same one this course applies to its own knowledge base: content is only trustworthy if something re-syncs it when the source changes.