` | | `---` | Horizontal rule | `

---

` | | `[[wikilink]]` | Internal link | App-specific | --- ## Why LLMs Love Markdown Markdown didn't become the interface layer between humans and AI by accident. Its properties align perfectly with how language models process and generate text. ### 1. Structured but Flexible Markdown provides just enough structure for LLMs to parse intent without being overly rigid. Headings create hierarchy. Lists organize ideas. Code blocks isolate syntax. But there's no schema to validate, no required fields—just natural organization. ### 2. Token Efficient In a world where context windows are precious, every token matters. Markdown is minimal: - A heading is `# Title` not `

Title

` - Bold is `**word**` not `word` **The math:** Same semantic meaning, ~4.5x fewer tokens. At scale, this difference is massive. ### 3. Native to Training Data LLMs learned from the internet, and the internet runs on Markdown: - GitHub READMEs - Stack Overflow answers - Documentation sites - Personal blogs Billions of well-structured Markdown documents in the training corpus. ### 4. Bi-directional Clarity LLMs can both parse and generate Markdown fluently. When an AI responds with a code block or a bulleted list, it's not fighting the format—it's using the same syntax it learned to recognize as meaningful structure. --- ## CLAUDE.md: Teaching AI About Your Code When you work with [Claude Code](https://claude.ai/claude-code), it automatically looks for a `CLAUDE.md` file in your project root. This simple markdown file becomes the AI's understanding of your codebase—a persistent briefing document that survives across sessions. ### What to Include Think about what you'd tell a new developer on day one: 1. **Project overview** — what does this code actually do? 2. **Key commands** — how to run, test, deploy 3. **Architecture** — where things live and why 4. **Conventions** — the unwritten rules 5. **Current focus** — what we're working on now ### Example CLAUDE.md ```markdown # CLAUDE.md This file provides guidance to Claude Code when working with this repository. ## Project Overview A Next.js application for real-time collaborative document editing. Built with TypeScript, Prisma, and WebSockets. ## Key Commands - `npm run dev` - Start development server - `npm run test` - Run test suite - `npm run db:migrate` - Run database migrations ## Architecture - /src/app - Next.js app router pages - /src/components - React components - /src/lib - Shared utilities and database client - /src/hooks - Custom React hooks - /prisma - Database schema and migrations ## Code Conventions - Use TypeScript strict mode - Prefer named exports over default exports - Use Tailwind CSS for styling - All API routes should validate input with Zod ## Current Focus Implementing real-time cursor presence for collaborative editing. See /docs/cursor-presence.md for the technical spec. ``` --- ## The Context Hierarchy AI assistants don't just read one file—they build understanding from multiple layers of markdown context. Each layer adds specificity: | File | Scope | Purpose | |------|-------|---------| | `CLAUDE.md` | Project root | Global project context, conventions, architecture | | `README.md` | Any directory | Directory-specific documentation | | `docs/*.md` | Documentation folder | Deep dives, technical specs | | `~/.claude/config.md` | User home | Personal preferences across all projects | --- ## Obsidian: Markdown as Knowledge Graph [Obsidian](https://obsidian.md) demonstrates what happens when you treat markdown files as **nodes in a graph**. The magic ingredient? `[[wikilinks]]`. ### How It Works Every `[[link]]` creates a bidirectional connection: - `[[Alice Chen]]` → links to Alice Chen.md - `[[Project Atlas]]` → links to Project Atlas.md - `[[2026-01-15 Planning Session]]` → links to dated note Link to a page that doesn't exist? Obsidian creates it. Rename a file? All links update automatically. Your notes become an interconnected web—a **second brain** built from plain text. ### Example: Meeting Notes with Links ```markdown # Meeting Notes - Jan 2026 ## Attendees - [[Alice Chen]] - Engineering Lead - [[Bob Martinez]] - Product Manager ## Context Follow-up to [[2026-01-15 Planning Session]]. Reviewing progress on [[Project Atlas]]. ## Discussion We need to migrate from [[Legacy Auth System]] to [[OAuth 2.0]]. - Timeline: 2 weeks - Owner: [[Alice Chen]] - Blocked by: [[API Rate Limiting]] decision ## Action Items - [ ] [[Alice Chen]] to create migration plan - [ ] Schedule [[Architecture Review]] for next week ## Related Notes - [[Previous Meeting - Jan 8]] - [[Technical Debt Register]] ``` --- ## From Files to Networks When every link is a connection, your file system becomes a queryable knowledge graph: - **Files as Nodes** — Each .md file is a node. Its filename is its identity. Its content is its knowledge. - **Links as Edges** — [[wikilinks]] create edges between nodes. Bidirectional by default. Traversable both ways. - **Folders as Clusters** — Directory structure provides natural clustering. /projects/, /people/, /meetings/ become semantic groupings. --- ## Your File System Is Already a Context Graph Here's the insight most people miss: **a folder structure is already a knowledge graph**. - Directories are categories - Files are entities - Paths encode hierarchical relationships When an AI reads your project, it's not just seeing code—it's building a mental model of how everything connects. The `.md` files are the **semantic layer** that explains the structure. ### Common Markdown Files and Their Roles | File | Purpose | |------|---------| | `README.md` | Project entry point, first thing anyone reads | | `CLAUDE.md` | AI-specific context, how to work here | | `CONTRIBUTING.md` | How to participate, code standards | | `docs/*.md` | Deep knowledge, specs, guides | | `CHANGELOG.md` | History of changes | | `API.md` | API documentation | --- ## .md Files as the Semantic Layer Code files tell you *what* the system does. Markdown files tell you *why* and *how to think about it*. This distinction matters enormously for AI. ### What Code Tells You - Function signatures and implementations - Data structures and types - Control flow and logic - Dependencies and imports ### What Markdown Tells You - Why this architecture was chosen - What problems this solves - How to extend or modify safely - What conventions to follow --- ## .md Files Are the Lifeblood In the age of AI-assisted development, markdown files aren't just documentation—they're the **interface between human intent and machine understanding**. ### Benefits for Humans - Readable without special software - Version control shows meaningful diffs - Works in any editor on any platform - No vendor lock-in, ever - Searchable with simple grep - Portable across decades ### Benefits for AI - Structured yet natural language - Semantic hierarchy from headers - Links express relationships explicitly - Token efficient for context windows - Familiar from training data - Easy to generate and parse > "The best format for human-AI collaboration is one that both can read, write, and understand without translation." > > That format is Markdown. --- ## Practical Tips How to write markdown that works well for both humans and AI systems: ### 1. Use Headers for Hierarchy - ✗ Write everything in paragraphs without structure - ✓ Use # for main topics, ## for subtopics, ### for details ### 2. Be Explicit About Context - ✗ Assume the reader knows the background - ✓ Include a brief overview section explaining what and why ### 3. Link Related Concepts - ✗ Mention related files without linking - ✓ Use [[wikilinks]] or [relative links](./path.md) to connect ### 4. Keep It Current - ✗ Let documentation drift from reality - ✓ Update docs when code changes; outdated context hurts more than none --- ## Start Writing The best way to understand markdown is to use it: 1. Create a `CLAUDE.md` for your next project 2. Let your file system tell a story 3. Build your second brain with linked notes ```markdown # Your turn ``` --- *This page is available as an [interactive web version](index.html) with demos and animations.*