Every new Claude Code session tends to start the same way. You spend the first few minutes re-explaining where the project stands: what shipped, what is half-built, what is blocked, and why a decision three weeks ago quietly closed off an option. The context is scattered across a dozen files, so the agent burns thousands of tokens rebuilding it and you flip through the same documents trying to remember the state yourself.
There is a tidier pattern doing the rounds in the Claude Code community, and it holds up in practice: keep one PlantUML file as the single shared state between the people on a project and the agents working alongside them. Claude reads about 200 lines of structured text and recovers full context. You glance at the rendered diagram and see the whole board.
Why context keeps leaking
Most teams document a project across README files, a ticket tracker, some architecture notes, and a running chat thread. Each is fine on its own. The trouble is that none of them holds the current state of everything at once, so both people and agents reconstruct it from fragments every time they sit down. For an agent, that reconstruction is expensive and lossy. For a person, it is the quiet tax that makes Monday mornings slow. The more moving parts a project has, the worse the tax gets.
One PlantUML file as shared state
A project map is a single docs/project-map.puml file that describes the project as a graph: modules, milestones, decisions, review gates, and the dependencies between them. Markdown is written for people and code is written for machines. PlantUML sits in the middle and serves both, because it is plain text an agent can parse and a picture once rendered.
Both sides can read it. PlantUML is a plain-text language, so Claude reads and writes the file directly while you look at the rendered diagram. There is no translation step in the middle.
IDs tie everything together. Task IDs like TSK-14, decision IDs like D-03, and review gates like R-02 all live in the one diagram, connected by arrows. Any module traces back to who built it, whether it passed review, and what is blocking it.
It is a dashboard, not a code diagram. Milestones, deliverables, decisions, and dependencies form a graph. A Markdown checklist is linear and cannot show that shape.
Setting it up with Claude Code
You do not draw the map by hand. Ask Claude to build the first version, then keep it current as part of the normal task loop.
Have Claude generate the first map. Point it at the whole project, group by architecture, and mark each module with a status colour: green for done, yellow for in progress, red for not started. Tag tasks as TSK-xx and record decisions as D-xx in the notes.
Add the rules to CLAUDE.md. Tell the agent to read docs/project-map.puml before starting any task, update a module status the moment it finishes one, log major decisions as D-xx, and never spin up a parallel status document.
Render it locally. Install PlantUML with a single package on macOS, preview it in a VS Code extension or an Obsidian plugin, or paste the file into plantuml.com in a browser. The rendered view is your dashboard.
The discipline that makes this work is small but real: the map is only useful if it is never out of date. Because updating it is one instruction in CLAUDE.md rather than a separate chore, the agent keeps it honest on your behalf, and the file stays trustworthy enough that you stop checking it against the code.
PlantUML or Mermaid
Mermaid is fine for a quick flowchart inside a Markdown doc. For a living project dashboard, PlantUML earns its place: it handles package grouping, note annotations, colour semantics, and the messier dependency graphs that real projects grow into. It also diffs cleanly, so an agent can patch a few lines of the .puml file after each task rather than rewriting a whole document.
What this is worth at Australian rates
The saving is not abstract, because context re-establishment is billable time. Take a senior developer in Sydney or Melbourne at roughly A$150 an hour. Fifteen minutes a day re-briefing an agent and reorienting yourself works out to a little over A$9,000 a year per developer, as an illustrative figure. On a team of five that is the cost of a decent contract engagement lost to re-reading your own notes. A shared map does not remove that work entirely, but it turns fifteen minutes into two.
The .puml file becomes a cross-session checkpoint for Claude and a single view of the project for you. Update a few lines after each task and stop writing context briefs no one reads twice.
If you want help wiring Claude Code into the way your team actually works, book a short call and we will map it out with you.
