# Man and Machine: The \#Scroll

![Man and Machine: The \#Scroll](/writing/man-and-machine/the-scroll/assets/hero.jpg)

A \#Markdown file is running my entire development workflow, and it's not a shell script or a Python program\.

I stumbled across Brad Feld's latest blog post yesterday, where he described a 1,400\-line markdown document that acts as a literal state machine for his AI coding agent\. He types one command and walks away for 30 seconds; when he comes back, Claude has fetched the ticket, checked out a branch, explored the codebase, generated an implementation plan, posted it back to the project tracker, and is waiting for approval\.

Here's what stopped me: I built the same thing, independently, without ever comparing notes with Brad\.

My agent \#Steve runs off markdown files too\. SOUL\.md defines who he is, MEMORY\.md stores what he knows, HEARTBEAT\.md tells him what to check when I'm not around, and daily logs give him continuity across sessions\. The architecture is remarkably similar, and neither of us designed it by reading the other's work\.

That convergence is meaningful because it tells us what actually works when running AI agents in production\. Markdown turns out to be the perfect control language for three reasons\.

First, it's readable by both humans and machines\. I can open SOUL\.md and understand exactly what Steve will do without needing an interpreter or a debugger\. The instructions are plain language, structured just enough to be precise but flexible enough to evolve\.

Second, it survives context loss\. When the AI's memory compresses during long sessions, the markdown file on disk remains the source of truth\. Brad solved this with session checkpoint files; I solved it with daily memory logs\. Different implementations, however, the instinct was identical: give the agent something durable to fall back on\.

Third, it's versionable\. I can track every change to my agent's behavior in git, review the diffs, and understand exactly when and why a behavior changed\. Consequently, debugging an agent becomes no different from debugging code\. Try doing that with a prompt buried inside an API call\.

The pattern is emerging across the AI builder community\. The people who are actually running agents in production, not just demoing them, are all converging on structured text files as the control layer\. Not because it's elegant or theoretically sound, but because it works in real\-world conditions, with real failures and real recovery needs\.

We're watching a new programming paradigm form in real time, and the language isn't Python or JavaScript\.

It's \#Markdown\.

What files are controlling your AI workflows?  
\-dg

\#ManAndMachine \#AI \#BuildInPublic \#CEO \#CFO \#CIO \#Fintech \#Leadership

## Sources

- [Original LinkedIn post](https://www.linkedin.com/feed/update/urn:li:activity:7437808438375616513/)