Keeping project decisions across Claude Code and Codex sessions with docs-governance

Managing coding decisions across different sessions of Claude Code and Codex can be challenging. The docs-governance project aims to simplify this process by providing a structured approach to document the context behind design choices and test protections.

At its core, docs-governance consists of several Markdown files, each serving a distinct purpose. CLAUDE.md contains the core project rules and constraints, which remain consistent throughout the project's lifecycle. CLAUDE_MAP.md holds navigation notes and any non-obvious paths that may not be immediately apparent. PROJECT_STATUS.md tracks current tasks and any remaining blockers that need attention.

PROJECT_LOG.md records all changes made to the project, along with the reasoning behind those changes, ensuring that important context is preserved.

For larger projects, additional documents like architecture documents, decision records, interface contracts, and test evidence can be included as needed. This modular approach allows the project to scale without overwhelming any single document with an overwhelming amount of detail.

A practical example illustrates how this workflow can be applied. Consider a regression test that protects an unusual compatibility requirement. While the test demonstrates the expected behavior, it may not explain why a simpler implementation is inappropriate. In this scenario, the essential constraint should be documented in the rules or a decision record for future reference.

Navigation notes would then point to the specific module and test, while the current status file would track any ongoing work related to that constraint. The change log would record the modifications made and provide a clear explanation of the rationale behind those changes.

It's important to note that this workflow does not guarantee perfect adherence to the documented context. The next coding-agent session may still need to interpret and apply the information appropriately. To address this, the process begins with a read-only audit using the governance audit scripts provided in the project's GitHub repository. This initial step helps identify any potential issues or outdated decisions that may need to be updated before making changes to existing project documents.

The trade-off is that these records require regular maintenance. Stale status notes or outdated decisions can lead to confusion for the next coding-agent session. The project welcomes feedback on the effectiveness of the audit process and is interested in hearing if maintaining these records is manageable within an existing project.

If you decide to implement this workflow, providing a GitHub issue describing your experience, whether positive or negative, would be greatly appreciated. It will help shape the project and make it more useful for the broader coding community.

If you find this approach helpful, a GitHub star is always appreciated to show support for the project's continued development.