Grounding AI Instructions in Living Documentation

Hans L'HoestHans L'Hoest
1 min read

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.

0
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