I've been experimenting with making AI generate literate code. The goal is to have the AI produce a bunch of prose alongside the code. A lot of context for the purpose and design of what you are doing usually gets thrown away, but with literate programming you can save it. And this way I can have some hope of understanding the code being created. I've liked it so far.
I am using a literate programming project I built (https://github.com/adam-ard/organic-markdown) and I have an AGENTS.md file that looks like this:
"All the work we do on this project should utilize the organic-markdown literate style that you see explained/demonstrated in the `organic-markdown` project: https://github.com/adam-ard/organic-markdown
Some guidelines for how you should utilize organic-markdown literate programming..."
Then I list a bunch of conventions for making literate code the way I like it.
Nice.
There have been some similar activities on this front. In case you didn't already know of them;
Literate Programming in the Age of LLMs - https://news.ycombinator.com/item?id=48691666
Natural Language Outlines for Code: Literate Programming in the LLM Era (inspired by LP) - https://dl.acm.org/doi/10.1145/3696630.3728541
Visual Programming + Literate Programming: A Better Way to Build Business Logic With AI - https://www.leapter.com/ai-verification-problem/
Renaissance of Literate Programming in the Era of LLMs: Enhancing LLM-Based Code Generation in Large-Scale Projects - https://arxiv.org/abs/2502.17441
This is wonderful, thanks! I was unaware of these!
You might also find my previous comment chains useful - https://news.ycombinator.com/item?id=48431591 https://news.ycombinator.com/item?id=48618662 and https://news.ycombinator.com/item?id=48264680
With AI agents we need some way to specify requirements, trace that they are met through the generated code and verify them against the requirements. All with the ability to generate documentation and facilitating understanding. Changes made to the specification should update code and vice-versa auto-magically. That is the holy grail of "Round-Trip Engineering".