A fresh coding-agent session can read the code, but the reasons behind it are often harder to recover. Why was a design chosen? Which paths are misleading? What is a regression test protecting?
I built docs-governance to make that context easier to maintain across Claude Code and Codex sessions. It is an MIT-licensed project with reusable skills, templates, and audit scripts.
Separate information by how it changes
The basic workflow uses small Markdown files with different responsibilities:
- CLAUDE.md holds durable project rules and constraints.
- CLAUDE_MAP.md holds navigation notes and non-obvious paths.
- PROJECT_STATUS.md tracks current work and remaining blockers.
- PROJECT_LOG.md records changes and the reasoning worth preserving.
Larger projects can add architecture documents, decision records, interface contracts, and test evidence as needed. The aim is to give the next session a clear place to look without putting every detail into one growing instruction file.
A concrete example
Suppose a regression test protects an unusual compatibility requirement. The test shows the expected behavior but may not explain why a simpler implementation is wrong.
In this workflow, the lasting constraint belongs in the rules or a decision record. Navigation notes point to the relevant module and test. Current status records unfinished work. The change log records what changed and why. This is an example of organizing context, not a guarantee that an agent will follow it perfectly.
Start with a read-only audit
You can begin with a governance audit before changing existing project documents. The repository includes installation instructions for Claude Code and Codex and the shared methodology.
https://github.com/qshanx/docs-governance
The trade-off
These records still need maintenance. Stale status notes or outdated decisions can mislead the next session. I would appreciate feedback on whether the audit identifies useful problems and whether keeping the files current is manageable in an existing project.
If you try it, an issue describing what worked or failed would help shape the project. A GitHub star is welcome if you want to follow development.
How do you preserve project decisions between coding-agent sessions today?
Top comments (0)