4.8.1The README is your project's front door
A README is the file at the top of your project that answers the first questions anyone asks: what is this, why does it exist, and how do I run it. It is the first thing a teammate opens and the first thing your agent reads to orient itself.
Keep it to what a newcomer needs on day one: a one-line description, the setup steps, how to start the app, and where the important docs live. If the README is current, someone can go from clone to running in minutes without asking you.
4.8.2Architecture docs and ADRs record why you chose this
An architecture doc describes the shape of the system. An ADR, an architecture decision record, captures one decision and the reasoning behind it: short, dated, written the moment you choose. Six months on, nobody remembers why you picked Postgres over a document store, and the ADR is the answer.
Write one when a choice is hard to reverse or easy to question later. The format is deliberately small:
# ADR 0001: Use Postgres, not a document store
Date: 2026-07-20
Status: Accepted
## Context
We need relational queries across users, orders, and
invoices, with strong consistency at checkout.
## Decision
Use Postgres as the primary database.
## Consequences
Joins and transactions are easy. We add a search
index later if full-text needs grow.
4.8.3The CHANGELOG tracks what changed
A CHANGELOG is a running, human-readable list of notable changes, newest at the top, grouped by version. It answers "what is different since last time" without anyone reading the git history. The widely used convention is Keep a Changelog, which groups entries under Added, Changed, Fixed, and Removed.
You do not write it from scratch each release. If your commit messages follow a convention like Conventional Commits, the agent drafts the changelog from them and you edit for clarity.
4.8.4Your agent reads all of this before it builds
These files are not paperwork for humans alone. Your agent reads the README to orient, the ADRs to respect decisions you already made, and the CHANGELOG to see where the project stands. Stale docs mislead it exactly as they mislead a person.
That is the payoff of this whole part: a documented architecture is a system the agent can hold in its head and build against, one tested piece at a time. It will not stay clean on its own, though. Code decays as it grows, so keeping this structure healthy means refactoring it continuously, on a regular cadence and not just when something hurts, which a later part turns into a habit. This prompt gives you the starter set:
Act as a senior engineer documenting my project.
Create three starter files:
- README.md: one-line description, setup steps, how
to run it, and where key docs live.
- docs/adr/0001-*.md: one ADR for a real decision I
have already made, using Context / Decision /
Consequences, dated, marked Accepted.
- CHANGELOG.md: Keep a Changelog format, an
Unreleased section grouped Added/Changed/Fixed.
Keep each file short and skimmable. Ask me before
inventing any fact you do not have.
My project:
Do this now: paste the prompt, name your project and one real decision you made, and let your agent write the starter README, ADR, and CHANGELOG.
