kerbelp/context-md

Context.md is a proposal for a standard file format that AI coding agents should read before they start working on a codebase and append to after they finish. The idea is simple: a single Markdown file, stored alongside the code in git, that captures what the project is trying to do, the hard rules that cannot be broken (and crucially, why those rules exist), and a running log of things that agents and humans have learned while working on it. The file has three sections. Intent states what the project is and what design philosophy it follows. Constraints list the non-negotiable rules with reasons: the rejected ORM because query opacity broke an offline repair path, the pinned package version because the newer one breaks ARM64 builds. The Evolved Context section is an append-only dated log where agents record what they discovered during their work. When a log entry proves reliable over time, a human can promote it into the Constraints section through a normal code review. The proposal describes a four-step contract: read the context before planning, treat constraints as binding, append what the work taught, and commit the context update alongside the code change in the same pull request so a human reviews both together. Because the file lives in git, it automatically branches, merges, and rolls back with the code. Conflicting things learned on two different branches become a merge conflict that a human resolves during review. The README explains why existing tools do not fill this role. README files describe how to use a project, not how to change it. Architecture decision records are write-once documents that agents are not required to read. RAG-based retrieval fails for constraints because a rule matters most when nothing in the current prompt resembles it. IDE memory files are private to one tool and invisible to code review. Context.md is meant to fill that gap: versioned with the code, required reading by contract, and updated by the agent under human oversight. Adoption requires no SDK, no server, and no vendor. Any agent that can read a file can participate. The repository includes a full example file and a whitepaper.