Markdown in /src
summary
As AI agents generate more code, the primary source of truth for a software system's intent and logic should shift from the generated code itself to version-controlled Markdown files stored directly in the source directory. This approach prevents the loss of design intent that occurs during ephemeral prompting sessions and ensures that both humans and agents have a localized, accessible record of why a system behaves as it does.
key points
- Markdown files in /src/md should capture low-level architectural and data design decisions, acting as a specification that is more detailed than a high-level design document but less ceremonious than automated tests.
- Storing documentation directly alongside the code provides strong locality, eliminating the 'specification at a distance' problem where critical logic is scattered across external wikis, Jira tickets, or chat logs.
- The workflow should shift so that developers curate human-authored Markdown files, which then serve as the basis for deriving both the implementation code and the corresponding tests.
who should read it
Software engineers and technical leads who are integrating AI-driven development into their workflows and seeking a way to maintain long-term project maintainability.
discussion skeptical
consensus
Commenters generally agree that while providing context to AI agents is useful, storing extensive markdown prompts within the source directory leads to 'prompt rot' and creates conflicting sources of truth. The prevailing sentiment is that source code should remain the primary authority, and documentation should be kept minimal, updated, or stored in dedicated directories to avoid cluttering the context window. Many suggest that inline code comments are the most effective way to maintain locality and accuracy.
top insight
The concept of 'prompt rot' highlights a critical failure mode where outdated instructions in markdown files mislead AI agents, causing them to follow obsolete logic over current code. This suggests that prompts should be treated as transient change specifications—perhaps stored in commit messages—rather than permanent repository resources. This shift prevents agents from treating stale documentation as 'gospel' while preserving the historical intent behind code changes.
Generated by an LLM from the article and thread. Check the sources before relying on it.