Markdown in /src
7 hours ago
- Markdown is becoming the new source code, not just documentation, in agentic coding workflows.
- Markdown should be checked in to /src alongside generated code to retain the intent behind the code.
- Prompt sessions are ephemeral; persisting Markdown captures the specification and decisions.
- Markdown is diffable, greppable, reviewable, and readable by both humans and LLMs.
- Proposed /src/md directory holds low-level specifications, architectural decisions, and data design.
- Local Markdown avoids scattered documentation in wikis or other tools.
- Tests should be derived from Markdown, not from ephemeral prompts.
- Developers interact with both Markdown and derived code, synchronizing changes when needed.
- /src/md content should be mainly human-authored, not generated by agents.
- A proposed /src/md structure includes README.md, TODO.md, OVERVIEW.md, and subdirectories for features, data, APIs, infrastructure.