What

Keep Markdown checked into your /src (or equivalent) directory to capture the intent of your module.

Why

Today, agents often generate code from ephemeral prompts, informal messages, etc.

Generated code is both lossy & noisy when it comes to the original intent that created it.

To address this, we suggest keeping the original intent near the generated code in the form of Markdown.

This enables humans and agents to quickly find the original intent, design decisions & subtleties that went into the current shape of the generated code.

Note that the intent captured here is not a formal specification or documentation, but rather an informal yet technical capture of the thinking that went into a module, feature, API, etc. It is developer (and agent) focused.

Suggested Layout

src/md/
  README.md           overview + index, agent entry point
  features/           login.md, ...
  data/               user.md, ...
  api/                accounts.md, ...
  infrastructure/     database.md, ...

All subdirectories are optional.

Suggested Content

• README.md should hold a technical overview of the module and note any particularly important subtleties, as well as a file index
  • The file index lists and links every other file in /src/md
  • The heading is ## File Index
  • Each line is one link and a brief description of what that file holds
  • Paths are relative to /src/md
• All other documents in /src/md should focus on capturing intent, design decisions and tricky aspects of the module
• All documents in /src/md should strive for a high signal-to-noise ratio, capturing important concepts and decisions, omitting obvious and unimportant information
• Simplified Technical English is suggested for all files
• Formal specifications, documentation, process documents, etc. may be linked from /src/md files, but these types of artifacts should not be included in /src/md

Example File Index

## File Index

- [features/login.md](features/login.md): login & session rules
- [data/user.md](data/user.md): user data model

Suggested Workflows

• Humans work to curate the Markdown with agents
• Markdown is changed to establish intent, then code and tests are derived from it
• Tests create an executable specification for the intent

Suggested Extensions

• A tmp directory, listed in .gitignore, can be used for capturing ongoing plans, TODO.mds, etc.

Example

This site follows this layout. See its src/md.