一句话
用 markdown 文件当系统——配置、规则、知识、流程、agent 的人格——全都写在 md 里，AI 读 md 干活。
为啥这个词重要
因为它是分水岭。理解之前：你以为 AI 是个”更聪明的 Google”。理解之后：AI 是你写下的 md 的执行器。
Karpathy 在 autoresearch 项目里有一个说法非常硬（karpathy/autoresearch/other-md/program.md）：
“The agent is programmed in markdown.”
他用 markdown 文件本身当 agent 的程序代码——不是 Python 不是 TypeScript，就是 md。md 里写 “当 X 发生，做 Y”，agent 按 md 跑。
它具体长啥样
MD-based System 不是一个抽象哲学，是一组可以看得见摸得着的文件：
~/my-project/
├── CLAUDE.md ← 项目级规则（见 [[CLAUDE.md 完全解读]]）
├── .claude/
│ ├── agents/
│ │ ├── reviewer.md ← 一个 agent 就是一个 md
│ │ └── tester.md
│ └── skills/
│ └── my-skill/
│ └── SKILL.md ← 一个 skill 就是一个 md
└── src/...
每个 md 文件就是一个可被 AI 读懂的独立模块。
跟传统编程的差异（不是平替，是换范式）
| 传统编程 | MD-based System |
|---|---|
| 用代码指令告诉机器每一步 | 用自然语言写意图、规则、边界 |
| 改一行要编译/部署 | 改 md 保存就生效 |
| 工程师才能写 | 会写文档的人就能写 |
| 逻辑藏在代码里 | 逻辑必须显式写出来 |
最后一条最关键——md 逼你把脑子里的隐性规则写出来。写不出来的规则 = 其实你也没想清楚。
为什么适合”非程序员搭系统”
来自 Karpathy、花叔橙书 01 和 04、awesome-claude-code 23 份真实 CLAUDE.md 样本的共同特征：
- 门槛低：中文也行，不会代码也行
- 版本可控：md 进 git，改啥都留痕
- 复用性高：好用的 md 直接复制给别人
- 可组合：一个主 CLAUDE.md + 几个专项 agent md + 几个 skill md，像搭乐高
关键但容易误解的一点
MD-based 不是”把文档写漂亮”。是”把规则写明白”。两者差别：
- 写漂亮：读者是人，目的是易读
- 写明白：读者是 AI + 人，目的是不留歧义
一个”写明白”的 md 往往看起来像说明书——平淡、准确、不带文学修辞。这种风格在本 wiki 里是对的。
陈彬视角（独立观点）
MD-based 的真正门槛不是技术，是你是否愿意把自己工作方式写下来。很多人会说”我方法说不清”——那就是你还没想清楚。想清楚了，md 自然写得出来。写不出来 = 你自己都没搞懂你的活儿是怎么干的。
AI 只是放大器。你 md 写得清 → 它干得漂亮。你 md 含糊 → 它就瞎蒙。坏消息：AI 无法替你想清楚。
关联
- 实操层：CLAUDE.md 完全解读 · Agent vs Skill vs Workflow
- 工具入口：Claude Code 入门
- 失败案例：案例_Karpathy 的 8-agent 实验为什么失败（P0.2 会写）
needs_sources（待补源）
- 有没有人把 MD-based 搞砸了的故事？现有素材全是成功面——明显单边。