Why Keep a Project History File

The short answer: CLAUDE.md tells Claude how things are. A history file tells Claude — and you — how things got here and why. The combination is much more powerful than either alone.

The problem it solves

You return to a project after three weeks. You open Claude Code. CLAUDE.md gives Claude the current structure, your preferences, your conventions. But:

• Why did you decide to use this folder structure and not that one?

• Why is that source excluded from the analysis?

• What did you try last time that did not work?

• Which approach did you abandon and why?

• What is the current state of a decision that was "under discussion" three weeks ago?

CLAUDE.md does not answer these questions. A history file does.

Without a history, you and Claude both operate on the current state without the context that explains it. You end up rediscussing decisions already made, repeating approaches already tried, and missing the reasoning behind choices that now seem arbitrary.

What a history file is

A history file is a running record of:

• Decisions made — and the reasoning behind them

• Pivots — what you were doing, what changed, and why

• Dead ends — approaches tried and abandoned, so you do not revisit them

• Open questions — unresolved issues, so they do not get forgotten

• Key findings — discoveries that changed the direction of the work

It is not a task list. It is not a summary of current state. It is the narrative of how the project developed — the kind of thing you would tell a new collaborator on their first day, so they understand not just what exists but why.

What to call it and where to put it

Common patterns:

project/
  _history.md          ← underscore keeps it at top of folder listing
  CLAUDE.md
  notes/
  sources/

Or as a running log inside notes:

project/
  CLAUDE.md
  notes/
    research-log.md    ← chronological, append-only
    decisions.md       ← key decisions, extracted from the log

The underscore prefix (_history.md) is a convention that sorts the file to the top of a directory listing — making it easy to find and hard to overlook.

What to put in it

A good history entry contains:

• What you did or decided

• Why (the reasoning, constraint, or insight that drove it)

• What you tried that did not work, if applicable

• Any open questions it left behind

Template:

## 2025-03-12

### Decided: use CSV not XLSX for extraction output

Changed the default extraction format from XLSX to CSV.
Reason: XLSX requires Excel to inspect; CSV opens in any text editor and
is directly readable by Claude in subsequent sessions without conversion.
XLSX will still be offered as an alternative for outputs that go to
collaborators who expect spreadsheets.

### Tried and abandoned: processing scans with Claude directly

Attempted to have Claude read the JPEG scans directly rather than
converting to PDF first. Result: consistently worse entity extraction,
especially for names. Reverted to PDF conversion step.
Open question: whether higher-resolution scans would change this.

How to use it with Claude

The most direct use: ask Claude to read the history before starting a session where context matters.

Read _history.md and CLAUDE.md.
Summarise where the project stands and what the open questions are.
Then let's continue with [today's task].

Or at the start of a new phase:

Read _history.md.
We are starting Phase C. What decisions from Phase A and B are relevant to
what we are selecting for the workshop?

Or when something feels wrong:

Read _history.md.
I am considering changing the extraction format back to XLSX.
Have we discussed this before? What was the reasoning last time?

Claude reads the file, recalls the reasoning, and saves you from re-debating a decision already made.

Especially useful for research projects

For historians and social scientists, the habit of keeping a research log is already familiar — a lab notebook equivalent, a field diary, a methodology journal. A history file in markdown is the same practice, applied to a Claude-assisted project.

It also serves a scholarly function beyond AI use: it documents your methodology in the making. When you need to write a methods section, describe your workflow in a grant report, or explain your process to a peer reviewer, the history file is already a draft.

For DISSINET specifically: if a project involves multiple researchers returning to the same corpus at different times, a shared _history.md in the project folder (committed to the repository) means every collaborator — human or AI — can get up to speed on what has been tried, decided, and left open.

History vs. CLAUDE.md: the difference

CLAUDE.md is a configuration file. A history file is a diary. Both are valuable. Neither replaces the other.

Starting one

The best time to start a history file is at the beginning of a project. The second-best time is now.

If you have an existing project with no history, ask Claude to help reconstruct it:

Read all the files in this project folder.
Based on what you find — the file names, the content, the structure —
write a _history.md that reconstructs the likely development of this project.
Note clearly what you are inferring vs. what is explicitly stated.
I will then correct and expand it.

Claude produces a draft based on what exists. You correct and fill in the reasoning. Takes 15 minutes. Saves hours of confusion later.

Related

• A.markdown.meta-docs — all four project meta-documents as a system: _history, _ownership, progress, _index; the practice as a whole

• A9.markdown-project-memory — CLAUDE.md: the current-state complement to the history file

• A.concept.agents — why context persistence matters for agentic workflows

• B.usecases — Scenario 8 (project organisation) involves setting up both CLAUDE.md and a history file