Published on: Sat Oct 03 2026

Tags: claude-code, productivity

How I organise AI-generated documents with CLAUDE.md

Background

I use Claude Code for more than code changes. It also writes research notes, design docs, implementation plans, QA results and review notes for me.

At first I didn’t tell it where to put these files. It saved them in the repo root, in /tmp, or wherever the current directory was. That was fine for one task, but I usually work on several tickets at the same time. After a week I couldn’t remember where the investigation for one ticket was, or which CSV belonged to which runbook.

So I added a section to my global ~/.claude/CLAUDE.md that decides where every document goes without my instructions.

The rule

1. Everything goes under ~/Documents/

Any prose that isn’t a code change is written under ~/Documents/, and Claude doesn’t ask me where to put it. Code changes still go into the repo.

2. Pick the directory by the question the document answers

This is the core of the rule. The directory isn’t chosen by topic, but by what question the document answers.

A topic like “payment retries” can produce an investigation, a design, a plan and a test checklist. If I sorted by topic, all of them would end up in one pile. Sorting by question keeps each kind of document in one predictable place.

For cases that are not clear, there are a few tie-breakers. For example:

• If it contains a decision about what to build, it goes to design/, even if it started as an investigation.
• Checking facts before building goes to findings/. Checking that the built thing works goes to qa/.
• If Claude is still unsure, it asks me before writing.

3. Group by ticket, then by date

The file path looks like this:

~/Documents/<dir>/<TICKET-KEY>/YYYY-MM-DD-<short-slug>.md

Claude gets the ticket key from the branch name, the PR, or the conversation, and asks me if it can’t find one.

reference/ is the only exception. Those documents are kept up to date rather than written once, so they have no ticket and no date in the path, and Claude updates them in place.

4. Links use full paths

When one document links to another, it uses the full path, e.g. ~/Documents/findings/PROJ-123/..., not a relative path. The link still works if either file is moved.

What it looks like with several tickets

Here is roughly what my ~/Documents/ looks like when I’m working on three tickets at once:

~/Documents/
├── findings/
│   ├── PROJ-101/
│   │   └── 2026-09-22-slow-checkout-root-cause.md
│   └── PROJ-130/
│       └── 2026-09-29-legacy-api-usage.md
├── design/
│   └── PROJ-101/
│       └── 2026-09-24-checkout-query-cache.md
├── implementation/
│   ├── PROJ-101/
│   │   └── 2026-09-25-cache-rollout-plan.md
│   └── PROJ-115/
│       └── 2026-09-26-backfill-runbook.md
├── qa/
│   └── PROJ-101/
│       └── 2026-10-01-checkout-cache-verification.md
└── reference/
    └── order-status-lifecycle.md

When I come back to a ticket, I only need two things to find a file:

1. The ticket key, which I already know because it’s in the branch name.
2. The question I want answered, e.g. “what did we find?” → findings/, “what’s the plan?” → implementation/.

That’s usually enough to go straight to the file. If not, ls ~/Documents/*/PROJ-101/ lists everything for that ticket across all stages, in date order. The tickets don’t get mixed up with each other, and I don’t have to remember which session wrote what.

Why this rule matters

Writing a rule like this may look like over-engineering, but I think it’s one of the most useful parts of my CLAUDE.md.

• Claude doesn’t remember where it saved things. Each session starts mostly fresh. If the location isn’t fixed by a rule, files end up wherever the session happened to be, and nobody remembers the path, including Claude.
• Switching between tickets is where files get lost. With one task, any location works. With three or four tickets at once, a fixed structure is the only thing that keeps them apart.
• It’s predictable for both of us. Because the rule is written down, Claude can find old documents too. When I say “check the findings for PROJ-101”, it knows exactly where to look.
• The documents stay after the session ends. Claude Code has its own memory, but that’s its working notes. ~/Documents/ is the human-readable record I can open, search and share.
• Fewer questions. Claude doesn’t ask “where should I save this?” every time. It only asks when it really can’t decide.

Summary

Adding a few rules for where documents go made Claude Code’s output much easier to manage. Routing by the question a document answers, then grouping by ticket and date, means I can find any document from the ticket key alone, even when I’m working on several tickets at the same time.