Document: Write It Down for Every Session

Step 2 of 7.

The exploring chats ended with a short list of decisions. If they stay in those chats, they are gone by tomorrow, because a new session starts empty. This lesson turns the decisions into a small set of documents that every session, and every teammate, can read.

Our goal: write a project document (the README) and an ordered task list, and know why a document is how a team, and an AI, remembers.

Here is the route:

Why a document: every session is a new teammate.
Start by saving the decisions.
What the project document holds.
What the team likes and does not like.
The task list.
The folder, before and after.
Keeping it true: rule 1 and rule 2.

We leave out writing each feature's detail (lesson 09) and how Claude Code loads these files (lesson 10).

Why a document

Good software process is the same whether the people are human or AI. Ask a team to start coding with nothing but spoken instructions, and each person builds their own version of the idea. The result is rework and arguments. A team that starts from one written document builds in one direction.

The document does not have to be complete or final. It only has to be good enough to start building the next few features. It grows as you learn (rule 2, at the end of this lesson). Everyone follows the decisions in it. And a person who joins next month starts from it, instead of repeating mistakes the team already made.

With an AI this matters even more. Lesson 01 showed that a long session costs more and gets less reliable, so the habit is one session for one task. That means every new task is like hiring a new developer for that task alone. A new hire with no document spends the day guessing. With one, they read it and catch up in minutes. If you have to explain the project from scratch every time, you are Alex from lesson 06.

This is the handbook from lesson 02, made real. It also works for people: the same file gets a new teammate started.

Start by saving the decisions

The first job is the simplest one. At the end of the exploring chats (lesson 07), ask the AI to write down what you agreed. You do not need a list of sections yet. A plain request is enough, and the AI can tidy it up later. The answers will differ. If your chat cannot write files, copy the text into a file called README.md yourself. (The .md ending means Markdown, a plain text file with simple formatting.)

Read what it saved before you trust it. The line "Do not add anything we did not decide" matters. Left alone, the AI fills gaps with the typical answer, and the document would start to contain guesses (lesson 02).

Here is the file it saved:

# Bookshop Back Office

Features: login, add a book by hand, add a book by scanning
its barcode, search and list books.
Not included: payments, customers and orders, an online storefront.

Technical: C# web app with server-rendered pages, SQLite database,
a budget VPS for hosting. A book is identified by its ISBN.

It is short and loosely organised, and that is fine for now.

What the project document holds

A document that people and AI both read works best with the same few sections every time. Here are six.

To get there, ask the AI to organise README.md into these sections, and not to add anything you did not decide. Conventions are yours to write, and the next section shows how. Keep the whole file short enough to read in a few minutes, because it is the first thing a person or an AI reads.

What the team likes and does not like

The Conventions section is where your standards go. An AI writes the typical code. Your team's way is not always the typical one, so say what it is.

Where do they come from? From code reviews you have been through, from a past project that hurt, or from a guide your team already follows. With none of those yet, start with the two or three that annoy you most, or ask the AI for the common habits in your language and keep only the ones you agree with. Do not write fifty rules on day one. Add a convention when something goes wrong or irritates you in review. This list grows as you work, which is rule 2.

The task list

The second document is a plain list of what to build, in order. It is how you and the AI agree on what comes next.

# Tasks

Order matters. Tick a task when it is built, tested and approved.

- [ ] 01 Project setup: web app, SQLite, one empty page
- [ ] 02 Login
- [ ] 03 Add a book by hand
- [ ] 04 Scan a barcode to add a book
- [ ] 05 Search and list books

You can ask the AI to draft the list from the README:

Turn the scope into an ordered task list, smallest first. Put a task after anything it depends on.

The order matters. Scanning (04) comes after adding by hand (03) because it reuses the same form, and search (05) needs books to exist.

The task list is not a spec. Each line is a pointer, and lesson 09 writes each feature out before it is built.

The folder

A new project starts nearly empty. After this lesson it holds two files.

Before:

bookshop-backoffice/

After:

bookshop-backoffice/
├── README.md          <- NEW  the project document
└── docs/
    └── tasks.md       <- NEW  the ordered task list

Put the files in the project folder, next to the code that will come, so every session finds them. The docs folder grows later: lesson 09 adds a specs folder inside it, and lesson 10 adds the file Claude Code reads when it starts.

Keeping it true

Documents only help while they are true. Two rules keep them true.

Rule 1: a change of plan goes into the docs first, then the code. If you change your mind about the database, edit the README, and then change the code. Otherwise the AI reads the old decision and builds on it.
Rule 2: what you learn goes back in. If the AI keeps using abbreviations, add that to "We avoid". It stops. This is how a document improves with use.

Lesson 14 shows both in action, when the team learns something that changes a decision.

Recap

Good process is the same for people and AI: a team that starts from a written document builds in one direction, and spoken instructions alone give three guesses.
One session per task means every task is a new teammate. A project document is how it catches up, and how a future joiner starts well.
The document does not have to be complete or final. It only has to be good enough to start building the next few features.
Keep one README with six sections: purpose, scope, decisions with reasons, conventions, constraints, open questions. Ask the AI to save the decisions first and organise them into these sections after.
Conventions say what the team likes and avoids, because the AI writes the typical code. Start small and add as you learn.
An ordered task list says what to build next. Each line is a pointer, not a spec.
Tell the AI not to add anything you did not decide.
Rule 1: docs first, then code. Rule 2: what you learn goes back into the docs.

Questions to think about

The answers are left out on purpose. Try them in your own words first.

Why does a team, human or AI, need a written document and not only spoken instructions?
Why does starting a fresh session for each task make the document more important?
Why write the reason next to each decision?
What goes wrong if the code changes before the docs?
Why is a task list not enough to start building from?

Next lesson: step 3, Specify. Write each feature out in detail before any code is written.