一句话定义
MD-based System 指的是：把 markdown 文件当成系统底座，规则、知识、角色、流程都优先写在 md 里，让人和 AI 都直接读这层文本来工作。
人话版：系统不是先藏在数据库、界面或代码后面，而是先落在一堆结构清楚的 md 文件里。
为什么重要 / 什么场景会听到
它重要，因为这决定你是在“给 AI 喂散乱材料”，还是在“给 AI 一个可读、可改、可版控的系统底座”。
最典型的两个场景：
- 对比 Notion 式知识库和 markdown 知识库时，后者对 AI 的消费性通常更直接，因为它本来就是纯文本。
- AIBuilder 这种项目里，agent、skill、wiki、
CLAUDE.md都是 md；改系统，很多时候就是改文本，而不是先改 UI。
技术机制
Karpathy 在 autoresearch 项目里有一句很硬的话：
“The agent is programmed in markdown.”
它不是抽象哲学，而是一组可见的文件和结构：
~/my-project/
├── CLAUDE.md
├── .claude/
│ ├── agents/
│ │ └── reviewer.md
│ └── skills/
│ └── my-skill/
│ └── SKILL.md
└── wiki/
└── 概念/在这个范式里，常见的机制有：
- 纯文本本身就是模块边界
- frontmatter 负责元数据
- heading / section 负责分块
[[双链]]负责互相引用- git 负责版本控制和回滚
最小可跑通例子
一个最小的 MD-based System 可以简单到这样：
- 一个
[[CLAUDE.md]]：写项目规则 - 一个
[[agent]]：写角色和边界 - 一个
[[skill]]：写一件可复用的具体技能 - 一个 wiki 页面：写知识条目
换句话说，改系统 = 改文本；不是每次都要先写代码。
常见误解 / 陷阱
- 误解一：md 太原始。不是，够用且直接被 AI 消费，恰恰是它的优势。
- 误解二：数据库一定更高级。不是，对强 schema 场景数据库当然有价值，但对 AI 直接消费的知识和规则，md 往往更顺手。
- 误解三：所有东西都适合 md。不是，超大规模、强约束、重事务场景并不适合全靠 md 承载。
- 误解四：只要用了 md，结构自然就清楚。不是，把 md 堆成很多层嵌套、命名混乱，AI 一样会迷失。
跟传统做法的对比
| 传统编程 / 配置方式 | MD-based System |
|---|---|
| 逻辑容易藏在代码或工具后面 | 逻辑被迫写出来给人和 AI 看 |
| 改动往往要编译、部署、点界面 | 改 md 保存就能改变系统行为边界 |
| 工程师更容易上手 | 会写说明书的人也能参与搭系统 |
| 供应商和产品格式绑定更重 | 纯文本和 git 更容易迁移 |
与其他术语的关系
[[CLAUDE.md]]：最典型的 MD-based 实践。[[agent]]/[[skill]]：在这个项目语境里，它们本身就是 md 底座。[[workflow]]：workflow 是这些 md 模块被编排起来之后的过程。[[22 份真实 CLAUDE.md 共同结构]]：这是对 MD-based 说明书层的实证分析。[[Harness]]：md 说明书、规则和知识层共同构成 harness 的一部分。
陈彬视角
MD-based 的真正门槛不是技术，是你是否愿意把自己工作方式写下来。
很多人会说”我方法说不清”——那就是你还没想清楚。想清楚了，md 自然写得出来。写不出来 = 你自己都没搞懂你的活儿是怎么干的。
AI 只是放大器。你 md 写得清 → 它干得漂亮。你 md 含糊 → 它就瞎蒙。坏消息：AI 无法替你想清楚。
延伸阅读 / 官方链接
🎬 3 个场景（读者最可能用到的情境）
场景 1 · Obsidian / Logseq 本地 md 知识库
写作者的笔记全在本地 md 里，用 Obsidian 双链连接。AI 接进来直接读 md 文件，不需要导出/转格式。知识库、AI 工具、版本控制、对外发布（Quartz 等）用的是同一套文件。
场景 2 · Karpathy LLM Wiki 范式
Karpathy 2026-04 发布的 gist 把 LLM 项目按三层文件夹组织：raw（原料）/ wiki（LLM 领地）/ CLAUDE.md（配置层）。AI 既是读者也是维护者，人只策展不手写。AIBuilder 本 wiki 就是这个范式的实例。
场景 3 · AIBuilder 本 wiki
wiki/ 下分 IA v3 的 6 个栈（路径/基建/概念/系统/术语/…），每个文件是一个 md 条目，git 版控，Quartz 静态发布，AnythingLLM 按 md 做 RAG。整个系统的骨架、规则、知识、角色、流程都在 md 里。
⚖️ 和最像的邻居比
| 术语 | 本质区别 | 适用边界 |
|---|---|---|
| MD-based System | 文件 = 纯文本 md · 人/AI 都直读直改 | 知识、规则、角色、流程 |
| DB-based System | 结构化数据 · 强 schema | 业务数据、事务、大并发 |
| Notion-based | 富文本 + DB 混合 · 格式封闭 | 团队协作 UI 优先 |
| Code-based config（JSON/YAML） | 机器可解析但人读吃力 | 机器配置、非人类对象 |
🚫 反例（不该这么用）
反例 1 · md 当代码库不做版本控制
把所有 md 堆在本地文件夹，从不 git init。某天 AI 帮你”整理”一下，误删几十个文件，无从恢复。正确做法：MD-based 的前提就是 git，每次 AI 动过都能回滚。
反例 2 · 堆成多层嵌套 + 命名混乱
wiki 下 7 层目录 + 每个文件名都是”笔记 3（副本）副本最终版.md”。md 本身没错，但结构乱了 AI 一样迷失。正确做法：有明确 IA（信息架构），命名稳定，双链连接关键条目。
❓ 常见误解
- 误解 1：“md 太原始、不高级” → 实际：恰恰是”纯文本”让它能被任何模型直读、被 git 版控、被任意工具处理，是 AI 时代最低成本的底座。
- 误解 2：“所有东西都适合 md” → 实际：超大规模、强事务、高并发、强 schema 的场景（订单、财务、实时数据）数据库更合适，md 主场是知识/规则/角色/流程。
- 误解 3：“md 只适合个人或小团队” → 实际：Karpathy、Anthropic、Cursor 社群已经把 md 推到”LLM 系统底座”级别，规模不是瓶颈，结构和纪律才是。
🧬 历史坐标（最早谁提 · 本质 · 分型 · git）
最早谁提
Plain-text + markdown 当知识底座的思路，可以追溯到 2004 年 Jeremy Ruston 的 TiddlyWiki（单文件 wiki）；2014 年 GitHub Flavored Markdown 标准化后进入主流；2020 年 Shida Li & Erica Xu 的 Obsidian 把”本地 md + 双链”推成大众工作流。把这条线推到”AI 时代的系统底座”的，是 2026-04-03 Karpathy 发布的 LLM Wiki gist——明确提出三层 md 文件夹 + LLM 维护的范式，短期获得极高关注。
本质（一句话 · 20 字内）
用 md 当系统底座 · 人和 AI 都直读直改。
分型 / 演化（2-4 行主线）
- 2004 TiddlyWiki（单文件）→ 2014 GFM 规范化 → 2020 Obsidian / Logseq / Foam（本地+双链）
- 2022-2024 Claude Code / Cursor 把
CLAUDE.md/.cursorrules作为项目级 md 底座 - 2026 Karpathy LLM Wiki：md 不只是人读，也是 LLM 的”知识所有权底座”
- 分叉：工具派（Obsidian/Logseq，强调人用）vs AI 派（Karpathy/Claude Code，md = LLM territory）
代表 git / 文档
- LLM Wiki gist · Karpathy 2026-04 · AI 时代 md-first 范式的明文
- Obsidian · 2020 · 本地 md + 双链的事实标准
- Quartz · jackyzha0 · 把 md 笔记静态发布成 wiki 站（AIBuilder 在用）