proomt

Search

Search posts, papers, and topics

All posts

Lobsters6 min readintro

Markdown in /src

Read on htmx.orgLobsters 12

Summary

The essay argues that Markdown should be treated as source code and checked into a /src/md directory alongside the implementation it describes. Keeping intent in diffable, reviewable Markdown lets teams generate code and tests from it while preserving locality for both humans and AI agents.

  • Store high‑level intent in Markdown files under /src/md alongside code.
  • Treat those Markdown files as the primary specification; generate code and tests from them.
  • Keep /src/md content human‑authored; avoid using agents to write it.
  • Organize /src/md with README, TODO, OVERVIEW, and optional feature/data/api subfolders for locality.

Engineers using LLM‑assisted coding need a stable, reviewable source of truth, and this approach offers a practical way to capture and version intent.

5/10
llmarchitectureaidocumentationmarkdown

Related reading

  1. Serving Markdown for AI Agents, Now as a Jekyll Plugin

    The author turned a one‑off script that rendered each Jekyll page to Markdown and added a `<link rel="alternate" type="text/markdown">` tag into a reusable Jekyll plugin (jekyll‑md). The gem hooks into the build, extracts the main content (defaulting to `<main>` or `[role="main"]`), converts it to Markdown, injects the discovery link, and requires no per‑page front‑matter. Configuration is option…

    Daniel Doubrovkine (dB.)dblock.org2 min

  3. How to Review AI-Generated Python Code Efficiently

    A practical five‑step workflow for reviewing AI‑generated Python code, covering intent clarification, automated quality checks (linters, type checkers, security scanners, tests), risk‑first manual reading, a checklist of common AI mistakes, and fix‑verify loops, plus a ready‑to‑use dev‑environment setup.

    Real Pythonrealpython.com26 min

  4. How Generative AI Is Changing Modern Software Development

    Generative AI tools can assist developers by producing code snippets, tests, documentation, and debugging hints, but their output must be reviewed and validated. Engineers should adopt prompt‑writing skills and maintain core software‑engineering expertise to use AI safely and productively.

    SitePointsitepoint.com4 min

  5. Should you read the code, is RAG dead, and did Skills kill MCP?

    The article debunks five common AI‑tool hot takes, arguing you still must read AI‑generated code, AI fluency matters in hiring, MCP and Skills serve different purposes, RAG remains useful, and needing fine‑tuning signals a messy codebase. It offers concrete rules for reviewing generated code and integrating AI components responsibly.

    GitHub Oldgithub.blog5 minHN3