Every repository has a README that takes a newcomer from clone to running. Every actively maintained production repository also follows the agent instructions standard: AGENTS.md is canonical, and CLAUDE.md is its exact import shim. Docs live next to the code and change in the same pull request. Runbooks explain deploys, environments, secret names, flags, on-call work, and dashboards.
Coding-agent changes pass through the same production gates as other changes. A human remains responsible, and an agent is never the independent approver. Do not add generated-by notices, tool attribution, or AI co-author trailers to commits or pull requests.
What a README must contain
- One-line purpose and the owning team (point at CODEOWNERS).
- Prerequisites and toolchain versions.
- Clone-to-run commands, and how to test.
- How to deploy, or a link to the runbook.
The steps from clone to running depend on the surface, so name the toolchain: sbt for Scala 2.13 / JDK 17-21, uv for Python, pnpm for TypeScript, flutter for Dart, dotnet for C#.
# orders-service
One line: what this service does. Owner: @squad-trading (CODEOWNERS).
## Prerequisites
JDK 21, sbt 1.10.x (see .tool-versions)
## Run locally
sbt run # starts on :8080
sbt test # unit + property tests
## Deploy / rollback
See docs/runbook.md.Runbooks
Each service runbook uses this structure and links to its SLOs and dashboards:
# Runbook: orders-service
## Deploy
## Rollback
## Environments (dev / staging / prod)
## Secrets (names only; values in Secret Manager)
## Feature flags
## On-call & escalation
## Dashboards & alerts (SLO links)A stale runbook becomes an incident action item. See release and incidents.
Diagrams and API docs
Commit diagrams as code so they are reviewed and versioned with the source. Write them as <pre class="mermaid"> blocks. They load lazily and match the site’s theme:
flowchart LR client --> gateway --> orders[orders svc] --> db[(Cloud SQL)]
Document HTTP services with OpenAPI, and publish reference docs (scaladoc, TypeDoc, dartdoc, DocFX) from CI instead of by hand.
Versioned artifacts
Every published library or versioned service keeps a CHANGELOG.md that follows Keep a Changelog and Semantic Versioning.
Keeping docs honest
Docs change in the same PR as the code, and docs paths have CODEOWNERS reviewers. AGENTS.md stores the required repository instructions. CLAUDE.md contains only the exact import defined by the agent instructions standard. Neither file stores secrets or temporary TODOs. Design docs and RFCs live where design docs, RFCs and ADRs says. The repository README and runbook explain how to build and run.
The Diataxis split helps authors write the right type of doc: tutorial, how-to, reference, or explanation. House style: NT-NinjaTrader/ntc-core projectMDs/_TEMPLATE.md.