Axiom II: Knowledge is Markdown
Last quarter, your team made a critical architecture decision: you chose event-driven messaging over synchronous REST for inter-service communication. The discussion happened across four Slack threads, two Zoom calls, a Google Doc that three people edited simultaneously, and a Confluence page that nobody can find anymore. Six months later, a new developer asks: "Why don't we just use REST calls between services?" Nobody remembers the full reasoning. The Google Doc has conflicting comments. The Confluence page references a Slack thread that's been archived. The decision rationale is effectively lost.
Now consider the alternative: that same decision lives in a file called docs/adr/007-event-driven-messaging.md, committed to your repository. It has a Status, Context, Decision, Consequences, and Alternatives Considered section. When the new developer asks "why not REST?", anyone — human or AI — can read the file and understand the complete reasoning in thirty seconds. When your AI agent proposes a change that would violate this decision, it reads the ADR and adjusts its approach automatically.
The difference between these two scenarios is Axiom II.
The Problem Without This Axiom
In Chapter 4, you learned Principle 5: "Persist State in Files." That principle established that files are the durable memory layer for agentic work — the antidote to AI's statelessness. But Principle 5 left a question unanswered: what format should those files use?
Without a format standard, teams persist knowledge in whatever seems convenient at the moment:
| Format | Example | Problem |
|---|---|---|
| Google Docs | Architecture decisions shared via link | Can't be read by CI, can't be diffed in git, requires authentication |
| Confluence wiki | Team knowledge base | Vendor lock-in, no version control integration, search quality degrades over time |
| Slack messages | "Hey, we decided to use Postgres because..." | Disappears into archive, unsearchable after 90 days on free plans |
| Word documents | requirements_v3_FINAL_v2.docx | Binary format, merge conflicts impossible to resolve, requires specific software |
| YAML/JSON files | Configuration stored as pure data | Not human-friendly for prose, no narrative structure, poor for explaining "why" |
| Plain text | notes.txt with no structure | No headers, no hierarchy, not parseable by tools expecting structure |
Each format works in isolation. None works as a system. The result: knowledge fragments across platforms, formats, and access levels. AI agents can't read half of it. Version control can't track changes to most of it. New team members can't find any of it.
The Axiom Defined
Axiom II: All persistent knowledge lives in markdown files. Markdown is the universal knowledge format because it is human-readable, version-controllable, AI-parseable, and tool-agnostic.
This axiom doesn't say "documentation should be in markdown." It says all persistent knowledge — specifications, decisions, context, guides, learning objectives, project conventions — lives in markdown. Markdown is not merely a documentation format. It is the knowledge substrate of agentic development.
From Principle to Axiom: The Format Decision
In Chapter 4, Principle 5 taught you that persisting state in files is essential for AI collaboration. You learned to create CLAUDE.md files, write ADRs, and structure projects for reproducibility. That principle answered whether to persist knowledge (yes, always) and where to persist it (in version-controlled files).
Axiom II answers the next question: how to format that knowledge.
The relationship is hierarchical:
Principle 5: "Persist state in files"
└── Axiom II: "Format that state as markdown"
└── Implementation: CLAUDE.md, ADRs, specs, README.md
The principle is about durability — ensuring knowledge survives across sessions. The axiom is about interoperability — ensuring that knowledge can be read, processed, and acted upon by every tool in the chain: humans, AI agents, linters, CI pipelines, documentation generators, and search engines.
Why Markdown?
Markdown wins not because it is the most powerful format, but because it satisfies all four requirements simultaneously. No other format does.
The Four Properties
| Property | What It Means | Why It Matters for Agents |
|---|---|---|
| Human-readable | You can read raw markdown without any special tool | Developers edit knowledge directly; no rendering step required |
| Version-controllable | Plain text diffs cleanly in git | Every knowledge change has a commit, author, and timestamp |
| AI-parseable | LLMs process markdown natively — headers, lists, tables, code blocks | AI agents extract structured information without custom parsers |
| Tool-agnostic | Works with any editor, any platform, any operating system | No vendor lock-in; knowledge survives tool migrations |
The Comparison
Consider how alternatives fail on at least one property:
| Format | Human-Readable | Version-Controllable | AI-Parseable | Tool-Agnostic |
|---|---|---|---|---|
| Markdown | Yes | Yes | Yes | Yes |
| YAML | Partial (data only, not prose) | Yes | Yes | Yes |
| JSON | No (noise from braces/quotes) | Yes | Yes | Yes |
| Word (.docx) | Yes (rendered) | No (binary) | Partial | No (requires Office) |
| Google Docs | Yes (rendered) | No (proprietary history) | No (requires API auth) | No (requires Google) |
| Confluence | Yes (rendered) | No (database-backed) | No (requires API auth) | No (requires Atlassian) |
| Plain text | Yes | Yes | Partial (no structure) | Yes |
| HTML | Partial (tag noise) | Yes | Yes | Yes |
Markdown is the only format that scores "Yes" on all four. HTML comes close but fails human-readability — raw HTML is cluttered with tags that obscure the content. Plain text fails AI-parseability — without headers and structure, an agent cannot distinguish a section title from body text.
The Structure Advantage
Markdown provides just enough structure without becoming a data format:
# Decision Title ← Parseable as section boundary
## Context ← Parseable as subsection
We needed a database... ← Prose that explains reasoning
## Alternatives ← Another parseable subsection
| Option | Pros | Cons | ← Structured data within prose
|--------|------|------|
| Postgres | ACID | Scale |
## Decision ← The conclusion, identifiable by header
We chose Postgres.
An AI agent reading this file can:
- Identify the decision by finding the
## Decisionheader - Extract alternatives from the table
- Understand reasoning from the
## Contextprose - All without a custom parser — markdown structure is the parser
Markdown as Knowledge System
Axiom II is not about individual files. It is about markdown as the substrate for an entire knowledge system. Different knowledge types use the same format but serve distinct purposes.
Specifications: What to Build
# LEARNING-SPEC.md
## Goal
Build a FastAPI skill that handles CRUD operations for task management.
## Success Criteria
- [ ] Skill creates valid endpoint definitions
- [ ] Skill handles SQLModel schema generation
- [ ] Skill produces working test scaffolds
## Constraints
- Must use SQLModel (not raw SQLAlchemy)
- Must follow RESTful conventions
- Must include error handling patterns
The spec is readable by the developer writing it, the AI agent implementing it, and the CI pipeline validating completion criteria.
Decisions: Why We Built It This Way
# ADR-003: Use SQLModel Over Raw SQLAlchemy
## Status
Accepted
## Context
Our FastAPI application needs an ORM. Team has mixed SQL experience.
SQLModel combines Pydantic validation with SQLAlchemy ORM capabilities.
## Decision
Use SQLModel for all database models.
## Consequences
- Positive: Single model definition serves as both API schema and DB model
- Positive: Type safety from Pydantic reduces runtime errors
- Negative: Less flexibility than raw SQLAlchemy for complex queries
- Negative: Smaller community, fewer Stack Overflow answers
## Alternatives Considered
- Raw SQLAlchemy: More flexible, but requires separate Pydantic models
- Tortoise ORM: Async-native, but less mature ecosystem
Context: How to Work Here
# CLAUDE.md
## Project Overview
Task management API built with FastAPI and SQLModel.
## Commands
- `uvicorn app.main:app --reload` → Start dev server
- `pytest` → Run tests
- `alembic upgrade head` → Apply migrations
## Conventions
- Models in `app/models/`
- Routes in `app/routes/`
- Every route has a corresponding test file
- Use dependency injection for database sessions
Documentation: How It Works
# API Reference
## POST /tasks
Creates a new task.
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| title | string | Yes | Task title (max 200 chars) |
| priority | enum | No | low, medium, high (default: medium) |
### Response (201)
```json
{"id": 1, "title": "Buy groceries", "priority": "medium", "status": "pending"}
All four file types — spec, decision, context, documentation — use the same format. They live in the same repository. They are tracked by the same version control. They are readable by the same AI agents.
## YAML Frontmatter: The Metadata Layer
Raw markdown provides structure through headers, lists, and tables. But some knowledge is better expressed as structured data: lesson duration, skill proficiency levels, creation dates, taxonomy categories. This is where YAML frontmatter adds a metadata layer on top of markdown content.
```markdown
---
title: "Axiom II: Knowledge is Markdown"
chapter: 14
lesson: 2
duration_minutes: 20
skills:
- name: "Knowledge Format Selection"
proficiency_level: "A2"
bloom_level: "Understand"
---
# Axiom II: Knowledge is Markdown
The lesson content begins here...
The frontmatter block (between --- delimiters) contains machine-processable metadata. The body contains human-readable prose. Together, they give you the best of both worlds:
| Layer | Format | Purpose | Processed By |
|---|---|---|---|
| Frontmatter | YAML | Structured metadata (dates, tags, numbers) | Build tools, CI, search indexes |
| Body | Markdown | Narrative content (explanations, examples, decisions) | Humans, AI agents, documentation generators |
This pattern appears throughout professional tooling: Jekyll blogs, Docusaurus documentation, Hugo sites, Obsidian notes, and Astro pages all use YAML frontmatter on markdown files. The pattern works because it respects the boundary between data and narrative.
Anti-Patterns: Knowledge Trapped Outside Markdown
| Anti-Pattern | What Happens | The Fix |
|---|---|---|
| Decisions in Slack | Knowledge archived after 90 days; unsearchable; no structure | Write an ADR in docs/adr/ and commit it |
| Specs in Google Docs | CI can't validate completion; AI can't read without auth; merge conflicts impossible | Write specs as markdown in the repo |
| Docs in Confluence | Vendor lock-in; stale pages nobody updates; separate from code | Co-locate docs with code as markdown |
| Notes without headers | AI can't parse sections; search returns whole file; no table of contents | Use # headers to create parseable structure |
| Knowledge in proprietary formats | Tool migration means knowledge migration; bus factor increases | Markdown survives any tool change |
| Unversioned documentation | No history of what changed, when, or why; no rollback | Commit all knowledge files to git |
The common thread: every anti-pattern breaks at least one of the four properties. Slack breaks version-controllability. Google Docs breaks tool-agnosticism. Plain text without headers breaks AI-parseability. Proprietary formats break all four.
The Knowledge Architecture
When you apply Axiom II consistently, your project develops a coherent knowledge architecture:
project/
├── CLAUDE.md ← Context: How to work here
├── README.md ← Context: What this project is
├── docs/
│ ├── adr/
│ │ ├── 001-database.md ← Decision: Why Postgres
│ │ ├── 002-framework.md ← Decision: Why FastAPI
│ │ └── 003-orm.md ← Decision: Why SQLModel
│ ├── specs/
│ │ ├── auth-spec.md ← Spec: Authentication requirements
│ │ └── api-spec.md ← Spec: API design
│ └── guides/
│ ├── setup.md ← Documentation: Getting started
│ └── deployment.md ← Documentation: How to deploy
├── src/ ← Implementation
└── tests/ ← Verification
Every knowledge type has a place. Every file is markdown. Every change is tracked. Every agent can read everything.
Safety Note
Markdown files committed to a repository are visible to anyone with repository access. Do not store sensitive information (API keys, passwords, customer data, internal security procedures) in markdown files, even in private repositories. Use environment variables for secrets, and reference them by name in your markdown documentation without including actual values.
Try With AI
Prompt 1: Knowledge Audit
I want to audit where my project's knowledge currently lives.
Help me categorize my project knowledge into these buckets:
1. Decisions (why we chose X over Y)
2. Specifications (what we're building and the success criteria)
3. Context (how to work on this project, conventions, patterns)
4. Documentation (how things work, API references, guides)
For each piece of knowledge I identify, help me determine:
- Where does it currently live? (Slack, Google Docs, someone's head, README, etc.)
- Is it in markdown in the repo? If not, what's the migration path?
- What breaks if this knowledge disappears tomorrow?
Start by asking me about my project and where I keep information today.
What you're learning: How to identify knowledge that is currently trapped in non-markdown, non-version-controlled locations. You are building the skill of recognizing when the four properties (human-readable, version-controllable, AI-parseable, tool-agnostic) are violated and understanding the operational cost of each violation.
Prompt 2: Markdown Knowledge Migration
I have a technical decision that currently lives outside my repository:
[Paste or describe a decision from Slack, a Google Doc, meeting notes, or memory —
for example: "We decided to use Redis for caching because..." or
"The team agreed that all API responses should follow the JSON:API spec because..."]
Help me convert this into a proper Architecture Decision Record (ADR) in markdown format.
Include: Status, Context, Decision, Consequences (positive and negative), Alternatives Considered.
Then explain:
- What information was I about to lose by not writing this down?
- How would an AI agent use this ADR when suggesting changes to my project?
- What would happen if someone proposed a change that contradicts this decision?
What you're learning: The practical mechanics of converting knowledge from ephemeral formats into durable, structured markdown. You are experiencing how the act of writing an ADR forces you to articulate reasoning that was previously implicit — making it available to both future humans and AI agents.
Prompt 3: YAML Frontmatter Design
I'm designing a markdown-based knowledge system for my project. I need to decide
what metadata belongs in YAML frontmatter versus what belongs in the markdown body.
My project involves [describe: API docs, internal guides, decision records, specs, etc.].
Help me design a frontmatter schema for my most common document types.
For each type, help me decide:
- What fields go in frontmatter? (things tools/CI need to process)
- What stays in the body? (things humans/AI need to read as narrative)
- What's the boundary between "data about the document" and "the document itself"?
Give me a concrete template for each document type with example frontmatter
and explain why each field is in frontmatter rather than the body.
What you're learning: The design principle behind YAML frontmatter — separating machine-processable metadata from human-readable content. You are learning to draw the boundary between structured data (dates, tags, numbers, categories) and narrative content (explanations, reasoning, examples), and understanding how build tools, CI pipelines, and AI agents use each layer differently.