Markdown in /src

The piece argues that Markdown is migrating from lightweight documentation into the actual source of truth for software systems as agentic coding (LLMs generating code) becomes common. It claims ephemeral prompt sessions leave intent scattered and generated code becomes the de facto ground truth, so teams should instead capture human-authored, diffable, and agent-readable Markdown alongside code in the repository. Markdown in /src would encode architectural, source-level, and data-design decisions at a level between formal specs and high-level design notes, making intent local to modules and accessible to both developers and agents.

Concretely, a proposed convention places module-focused Markdown under src/md with README, OVERVIEW, TODO, and subfolders for features, data models, APIs, and infrastructure. Tests remain automated checks derived from that Markdown rather than serving as the primary human-facing spec; developers are expected to edit both Markdown and generated code and synchronize changes. The recommendation emphasizes human curation of /src/md, minimal agent-authored content there, and treating Markdown as versioned, reviewable source that preserves intent, improves locality, and reduces reliance on distant wikis or ephemeral prompts.