Every repository has a README that takes a newcomer from clone to running. It also has a CLAUDE.md that explains its architecture and conventions. These files are the source of truth for both people and AI agents. Docs live next to the code and change in the same pull request. Runbooks explain deploys, environments, secrets and flags, on-call work, and dashboards.
AI-assisted development is normal. Prototype freely, but send production changes through the same gates. Mark commits written by AI, and keep a human responsible. An agent is never the independent approver.
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. CLAUDE.md stores lasting facts, architecture, conventions, build and test commands, and gotchas. It never 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.