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.