Grounding AI Instructions in Living Documentation

Context engineering shows interesting potential to ground documentation to actual code, or as how I sometimes refer to it: reality.
Linking AI instruction files (CLAUDE.md, .rules, .cursorrules, etc) to development documentation may turn static docs into living resources. Each code generation cycle tests documentation accuracy and real-world application. This creates a direct feedback loop that keeps documentation aligned with actual development workflows.
Also, this coupling of documentation and implementation may create friction but I expect this to a good thing long-term. It signals opportunities for documentation improvement, encouraging streamlined, practical documentation that genuinely serves developers, while also identifying code that diverges from documented standards.
Some quick thoughts:
The feedback loop is fuzzy given how LLMs work, but an LLM can likely explain why it implemented something based on the documentation.
Documentation will likely become more actionable and directive.
The 'why' behind guidelines typically belongs elsewhere, but could become an evaluation against actual code.
Developer documentation may work better in the code repository (and in markdown).
LLMs currently work best with concise instruction files - this constraint likely benefits developer documentation too.
Subscribe to my newsletter
Read articles from Hans L'Hoest directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by

Hans L'Hoest
Hans L'Hoest
I write about: Software architecture and engineering, Better software better. DDD, Scala and Rust