Markdown-First Codebases: The Future of AI-Native Content Systems

I’ve built my AI agency on a simple principle: most business data belongs in a markdown file with frontmatter. No complex CMS, no tangled CRM—just plain text that both people and AI can read. This website, built with the Astro framework, is living proof. After a recent ‘AI that Works’ livestream, I’m certain this is the future of building for AI.

Table of contents

We Built a Monster

The tech industry created a monster. We buried our content and customer data under layers of complexity:

• Databases that need an ORM just to ask a simple question.
• APIs that abstract information into oblivion.
• Build processes that mutate data through endless stages.
• Authentication that gates even basic read access.

Each layer is another wall an AI agent has to climb. I’ve watched powerful models struggle with a WordPress site or a Salesforce API. The AI isn’t the problem; the system is. We never designed it for a machine to understand.

The Markdown-First Answer

My projects work differently. Every piece of information—a blog post, a service, a customer—is a markdown file with a rich header, called frontmatter. Frameworks like Astro embrace this natively, treating markdown as a first-class citizen.

---
title: "Client Case Study: E-commerce Transformation"
client: "RetailCo"
status: "completed"
pubDatetime: "2025-07-15T10:00:00-04:00"
---

The project began when RetailCo approached us...

This isn’t just simpler; it’s smarter. When an AI needs to understand my work, it reads directories and files, not database schemas. The filesystem is the data graph. For AI agents, code and markdown are more than enough.

A concept from the ‘AI that Works’ livestream: treat markdown files as a simple database. Frontmatter acts as the queryable index, and the body holds the content.

Let me illustrate with a couple of real-world scenarios. I’m obscuring client identities to focus on the point, but the problems are common.

A fashion company I worked with needed to manage 10,000 product images. My first instinct was traditional: a CMS and database. I built it all, then watched an AI try to use it. The AI didn’t care about my database; it navigated folders of PNGs more easily than it queried tables.

The solution was to pair each image with a markdown file for its metadata. When the client asks, ‘Show me all evening dresses under $500,’ the AI reads the files and filters by price. No database. No API calls. Just files. For large images, we use Git LFS, which turns a repository nightmare into an elegant solution.

This same principle works for an AI-powered sales engine. Many clients have thousands of contacts trapped in a clunky CRM where the API is a bottleneck.

So we export everything to markdown.

crm/
├── contacts/
│   ├── jane-doe.md
│   └── john-smith.md
└── interactions/
    └── 2025-08-27-call-with-jane-doe.md

Each contact becomes a simple file:

---
name: Jane Doe
email: "jane.doe@example.com"
status: "lead"
last_contact: "2025-08-27"
tags: ["webinar-q3", "interested-in-ai"]
---

### August 27, 2025 - Initial Call
Discussed their need for an agentic workflow solution...

Agentic workflows suddenly become trivial. ‘Find all leads we haven’t contacted in 30 days and draft a follow-up’ is no longer a slow sequence of API calls. It’s a fast, local file search. This markdown approach has been incredibly successful for projects involving CRMs, CMSs, landing sites, blogs, and documentation.

Databases were never designed for the messy, contextual world of content and customer relationships. We forced our data into rigid tables, creating the complexity we live with today.

For most business operations, a traditional database or SaaS platform is not needed. Markdown gives us flexible schemas, a human-readable format, and a natural hierarchy. It’s a recognition that AI agents don’t need REST APIs or GraphQL. They need readable, accessible, semantic files.

The truth is stark: most businesses don’t need a CMS. They don’t need a complex CRM. What they need is simple, maintainable, and most importantly—understandable by both humans and AI.

The Reality Check

Contributing insight from Vincent Ge, Technical Writer at PostHog

Vincent shared a perspective that cuts to the heart of our industry’s problem:

You’re 100% right on the CMS point. I think we’ve entirely forgotten about the size and complexity of most businesses on this planet when we build dev tools. Very very few businesses truly need a CMS. We love building for scale that doesn’t exist.

Vincent’s observation perfectly captures why markdown-first approaches work. Most businesses aren’t Facebook or Amazon. They don’t need enterprise CMSs, complex CRMs, or multi-layer architectures. They need simple, readable, maintainable systems that both humans and AI can understand.

When we build for imaginary scale, we create real complexity. Markdown-first codebases flip this: they start simple and only add complexity when truly needed—which, as Vincent points out, is far less often than we think.

How to Start

If you’re convinced, here’s how I began:

1. Start Small. Write all new content or log new customer data in markdown.
2. Export Everything. Most CMSs and CRMs can export to CSV or JSON. Write scripts to convert the data into markdown files.
3. Think in Files. Organize data in directories that make sense to you. Let the structure mirror your mental model.
4. Build Tiny Tools. A 20-line script that indexes your markdown is more valuable to an AI than a thousand-line enterprise plugin.

The True Unlock: Your Own Tools

Once you’ve started with markdown-first basics, the real power comes from building custom tools on top—for yourself and for your AI agents.

Imagine giving an AI a tool like this:

tools edit-markdown --query 'tags includes "react"' --set 'featured: false'

Or asking it to find related content:

tools find-related-posts --post 'markdown-first-codebases.md'

These custom tools allow an AI to operate on your content with precision. You’re not just giving it data; you’re giving it levers to pull. The AI can then chain these tools together, turning a passive content store into an active, agent-driven system.

The Agentic Era

We are entering an era where AI agents are active partners. They must be able to read, understand, and change our data as easily as we do. Markdown-first systems, championed by tools like Astro, are designed for this future.

The next time you reach for a CMS or a CRM, ask yourself: would an AI thank you for this complexity? Or would it prefer a simple markdown file?

The answer might change how you build.

Inspired by the AI that Works livestream on using Claude Code for non-coding tasks.