How I Use AI: A Documentation-Driven Approach

2026-07-07

I jokingly mentioned to a colleague that Markdown may very well be the programming language of the future. This stems from the realization that I’ve spent progressively more time cross-checking requirements and business logic, verifying technical documents, and ensuring feature implementations align with stakeholder needs—both internally and client-facing.

I’ve always believed that code matters less than the value being delivered or the problem it solves. In the context of cross-functional teams delivering that value, getting everyone—engineers, business analysts, IT infrastructure, and customer support—on the same page is paramount. This is why I appreciate the skill of intentional documentation before writing any code, and why Markdown files can serve as the "same page" for team members in this age of AI software development.

Documentation-Driven Development as an approach to software delivery is not new. I stumbled across the concept while trying to restrict my AI tools with specific context boundaries beyond just an AGENTS.md file in my codebase. As a multipotentialite and entrepreneur, I quickly realized this practice applies to more than just technical requirements. An entire business entity could leverage this kind of documentation alignment with AI—which might make for a great future blog post!

But let's focus on the software development slice for now. I’ve found that the most effective way to leverage AI isn’t through blind code generation, but through a structured, documentation-centric workflow. By treating documentation as the foundation, I maintain higher code quality and clearer intent.

Documentation-Driven Development: "Documentation is the Source Code for AI"

If there is one massive lesson I’ve learned from building Tackshare, it’s this: **when you are working with AI, documentation isn't an afterthought—it is the source code**.

In traditional development, the code is the absolute source of truth. Documentation is just that helpful (but often outdated) guide sitting next to it. But when you introduce an LLM into your workflow, the dynamic flips entirely. If you just point an AI at a codebase and tell it to "build a feature," it's going to hallucinate dependencies, forget your architectural constraints, and quickly turn your app into spaghetti code.

To solve this, I completely shifted my product development process. I now use a Documentation-Driven Approach where my /docs folder acts as the ultimate prompt, providing absolute context and strict boundaries for the AI.

Here is how I break it down:

The 3-Tiered Context Architecture

I realized that an AI needs different levels of context depending on the task, so I structured my /docs folder into three distinct tiers:

• The "What & Why" (Product & Planning): My PRODUCT.md file serves as a living spec, while the docs/planning/ folder holds my user personas and roadmap. Before the AI writes a single line of code, it understands exactly who it is building for and what the business goals are.
• The "How & Rules" (Architecture): Inside docs/architecture/, I keep a strict log of Architecture Decision Records (ADRs). By documenting core decisions—like why we use Cloudflare Workers instead of Node, or our specific Firebase Auth invariants—I prevent the AI from improvising and accidentally bringing in standard, but incorrect, tech stacks.
• The "Action" (Implementation Specs): This is the engine of the workflow. Instead of giving the AI a massive task, I break development down into highly granular, numbered markdown files in docs/implementation/ (e.g., 0014_notice_crud.md). Each file is a bite-sized, single-concern spec that acts as a perfect, atomic prompt.

Markdown as a State Machine

One of the biggest struggles with AI is the context window. Over a long session, the AI inevitably loses the plot. To counter this, I use Markdown to maintain the exact state of the project.

My backlog.md acts as a literal ledger. When a phase is completed, the AI flips the ledger to "Done," updates the implementation notes, and logs the work in an UNRELEASED.md changelog.

The beauty of this? I can spin up a completely fresh AI session, point it to the docs folder, and it instantly knows the exact state of the project without having to read a thousand lines of source code.

Strict "Operating System" Protocols

Finally, I created a CLAUDE.md file at the root of my project that essentially acts as the AI’s operating system. It enforces strict "rules of engagement":

• Read before writing. (No guessing allowed).
• Test-Driven Development. (Write failing tests first to define expected behavior).
• The Verification Loop. (After every change, the AI is forced to run my linting, unit tests, and e2e tests to self-correct any regressions).

By externalizing my strategy, state, and history into concise Markdown, I’ve stopped using AI as just a fancy autocomplete. Instead, I’ve engineered a system where Markdown is the interface between human strategy and machine execution. And honestly? It’s completely changed how I build software.