Project Meta-Documents: The Files That Make the Project Legible

The problem: CLAUDE.md tells Claude the current state of a project. It does not tell Claude — or you — how the project got there, who made what, what has been tried and abandoned, or where any given concept lives in the material. When those things are missing, every return to the project starts from scratch.

Meta-documents are the answer. They are plain markdown files kept in the project folder that make the project legible: to Claude, to you, and to anyone who encounters the work later.

What makes a file a meta-document

Meta-documents are about the project, not part of the project's output. They do not contain research findings, drafts, or primary materials. They contain:

None of these are automatically generated. None of them are part of Claude's built-in memory. You create them; Claude can read and update them; they persist between sessions.

The underscore prefix (_history.md, _ownership.md, _index.md) is a convention that sorts these files to the top of any directory listing — making them easy to find and hard to overlook.

The four documents

_history.md — the project narrative

Records decisions made, pivots, abandoned approaches, and open questions — with the reasoning behind each.

What it is not: A task list. A current-state summary. A log of every action taken.

What it is: The narrative of how the project developed — the kind of record you would use to write a methods section, or to brief a new collaborator on their first day.

Why Claude needs it: CLAUDE.md describes what is there. _history.md explains why. Without it, Claude operates on the current state with no knowledge of how it came to be. You end up re-debating decisions already made, repeating approaches already tried.

Why you need it: It is the first draft of your methodology section. It documents what you tried and what failed — the information that is most useful and most commonly lost. Three weeks after an abandoned approach, neither you nor Claude remembers why it was abandoned.

A single entry:

## 2025-04-08

### Decided: exclude post-1350 records from the main corpus

Reason: the quality of scribal hands changes sharply after 1350 and our
transcription method does not account for the shift. Including them produced
3x more [?] flags than the pre-1350 material.
Will keep a separate file of post-1350 records for possible inclusion later.
Open: whether to reprocess them with a different method or leave out entirely.

See A.markdown.history for the full treatment: what to put in each entry, how to start one retroactively, how to use it with Claude at session start and at decision points.

_ownership.md — the attribution record

Records who did what across the project: a classification of documents by collaboration mode, the intellectual contributions that are unambiguously yours, and a plain statement of overall distribution that could appear in a disclosure note.

Why this matters for researchers: AI-assisted work does not have a single ownership structure. A document you wrote independently, a document Claude drafted from your brief, and a document a research agent produced from a web search commission are three very different things — even if they sit in the same folder and look identical.

When you publish, submit, present, or cite this work, you need to know which is which. A vague or inaccurate disclosure claim is more problematic than a specific one, even when the specific one acknowledges significant AI contribution.

Three collaboration modes to track:

Mode Description What you can claim
User-authored You wrote it independently Ideas, structure, language — all yours
Claude-drafted from brief You identified the topic and gave a brief; Claude drafted Ideas collaborative; language primarily Claude's
Research agent + synthesis Agent did the research; Claude synthesised; you edited Brief and editorial direction; not the research itself

What it contains in practice:

The connection to B.ownership: The framework for assessing and describing AI contribution — the dimensions of ownership, the review prompts, the model disclosure statements — is in B.ownership. _ownership.md is where you apply that framework to your specific project.

When to update it: At project milestones, not daily. When a cluster of new documents has been created, add them to the appropriate mode group. A monthly or phase-end review takes ten minutes.

progress.md (or notes/progress.md) — the current task state

A running log of what has been done, what is in progress, and what remains. Not narrative, not reasoning — just practical state.

## 2025-04-10
Done: processed registers 1–24. Extracted 480 deposition entries.
In progress: cross-referencing name variants for Guilhem.
Next: registers 25–35; resolve [?] flags from last batch.
Open: Duvernoy edition discrepancy — three entries differ, cause unknown.

Why Claude needs it: Read at session start, it restores the working context without you having to reconstruct it. At the end of each session, ask Claude to append an entry — it costs thirty seconds and makes the next start frictionless:

> Append a dated entry to notes/progress.md summarising what we did today,
  what is in progress, and what comes next.

Relationship to _history.md: Progress tracks what; history tracks why. Both are useful; neither replaces the other. In a long project, the progress file is the day-to-day log; history is the curated record of decisions and turning points.

_index.md — the concept and navigation index

A term-to-documents map: each entry is a concept, tool, risk, or practice, with a one-line description and links to the documents that cover it.

**Hallucination** — plausible-sounding incorrect output; the most-discussed but not most-dangerous AI failure mode
→ [C.dangers](C.dangers.html), [A.concept.under-the-hood](A.concept.under-the-hood.html)

**Sycophancy** — structural tendency toward approval; compounds across sessions into confirmation loops
→ [B.epistemics](B.epistemics.html), [C.dangers](C.dangers.html), [A.issue.plan-mode](A.issue.plan-mode.html)

Why this is different from CLAUDE.md: CLAUDE.md describes the project's current state and conventions — it is instructions to Claude. _index.md describes the intellectual territory of the project — it is navigation infrastructure for humans and Claude alike.

Three uses:

  1. Quick search — you remember a concept but not which document covers it. Ask Claude: > Read _index.md. Which document covers [concept]? Or search the index directly.

  2. Wiki hover — on a GitHub Pages site, terms in documents can link to a popup showing relevant documents. _index.md is the data source for that feature: each term maps to 1–4 documents that pop up when a reader hovers over the term.

  3. Network visualisation entry point — the Related sections in all documents define edges between documents. _index.md defines the term layer: not just "this document connects to that document" but "this concept appears in these documents." Together they give a network that is navigable by both document and concept.

When to maintain it: Update when a new document covers a concept not yet in the index, or introduces a term that should be findable. A brief entry takes two minutes. The index does not need to be exhaustive — it needs to cover the terms a reader would search for.

Starting the set

The minimum useful set for any Claude-assisted project with more than a few sessions:

your-project/
  CLAUDE.md              ← Claude reads automatically
  _history.md            ← read on demand; append-only
  notes/progress.md      ← read at session start; append at session end

Add _ownership.md when the project produces work you will publish, present, or submit. Add _index.md when the project has enough documents that navigation becomes a problem, or when you want to build a shareable site.

When to create them: A project that starts without these files and creates them once the structure has become clear is not behind — it is being accurate rather than aspirational. The right time to create infrastructure is when you understand what it should do. What "start early" really means: create the file and start it, even with a single entry. A one-line _history.md is better than none — it is a placeholder that will grow.

Using meta-documents at session boundaries

Session start (when context matters):

> Read CLAUDE.md and notes/progress.md. Tell me where we left off.

For a longer gap:

> Read CLAUDE.md and _history.md.
  Summarise the open questions and the reasoning behind the current structure.

Session end (two minutes):

> Append a dated entry to notes/progress.md: what we did today,
  what is in progress, what comes next.

When a significant decision was made:

> Append an entry to _history.md recording the decision we just made
  and the reasoning behind it.

At publication or submission:

> Read _ownership.md and _history.md.
  Draft a disclosure statement for [venue/context] that accurately describes
  AI's role in producing these materials.

The case for the practice

None of these documents are required. Claude Code works without them. Many projects run without them. The cost is paid later:

The meta-documents do not make work happen. They make the work that already happened recoverable — for Claude, for you, and for whoever else encounters it.

Related