Building2 min read
4 docs that keep your AI coding agent from losing the plot
AI agents forget everything between sessions. These 4 files are how you give them memory.
01
CLAUDE.md
The rulebook Claude reads at the start of every session.
- Where
- Repo root. Claude Code loads it automatically.
- Put in it
- What the project is, the stack, the commands, your always and never rules, and which other docs to read first.
- Update when
- Your stack, rules, or commands change.
Starter template
# Project name
## What this is
## Stack
## Commands
## Always
## Never
## Read first
- docs/progress.md
- docs/decisions.md
- docs/known-issues.md02
progress.md
Where the project stands right now.
- Where
- /docs
- Put in it
- Current phase, what's done, what's in progress, what's next, blockers, and a short dated log for each session.
- Update when
- The end of every session.
Starter template
# Progress
## Current phase
## Done
## In progress
## Next
## Blockers
## Log
### YYYY-MM-DD03
known-issues.md
Bugs, workarounds, and code that looks wrong but is intentional.
- Where
- /docs
- Put in it
- Open issues with IDs and severity, gotchas, workarounds, and resolved items with the fix.
- Update when
- You hit a bug or find something weird that works.
- Why it matters
- It stops the AI from "fixing" something and breaking prod.
Starter template
# Known issues
## Open
### KI-001: Title (high)
## Gotchas
## Workarounds
## Resolved
### KI-000: Title
Fix:04
decisions.md
What you chose, what you passed on, and why.
- Where
- /docs
- Put in it
- One entry per decision with an ID, status, date, the reason, and what it replaced.
- Update when
- You pick a library, a service, or a pattern.
- Why it matters
- It stops the AI from swapping out your tools or reopening choices you already made.
Starter template
# Decisions
## D-001: Title
Status:
Date:
Why:
Replaced:How to set it up
- 1.Create CLAUDE.md at the root and a /docs folder with the other three.
- 2.In CLAUDE.md, tell the agent to read progress.md, decisions.md, and known-issues.md before starting work.
- 3.End every session with: "Update progress.md, log any new decisions, and add any new gotchas."
- 4.Start every new session with: "Read CLAUDE.md and progress.md, then tell me where we left off."
These four docs are for building an app. For an agent that runs jobs for you, use the folder method instead. It also drops the Always and Never sections on purpose, since newer models follow them too literally.
