Markdown in /src

In the rapidly evolving world of software development, a new trend is emerging: agentic coding, which utilizes large language models (LLMs) to generate code instead of traditional hand coding. As an expert in this field, the author argues that Markdown, traditionally used for documentation, is becoming the new source code. This shift is being driven by the increasing reliance on LLMs to generate code, making the generated code the closest thing to a "ground truth" for a feature in professional environments.

The author suggests creating a new directory, /src/md, to house Markdown files that capture the lower-level specifications of software systems, closer to actual code than traditional design documents. This proposed directory would help maintain a higher level of locality and facilitate a more direct connection between the intent behind the code and its implementation.

The author acknowledges the need for thoughtful management of this new Markdown directory to keep it clean and well-factored, while also emphasizing that developers should primarily interact with both the Markdown and the generated code.