我用JSON管了7天AI團(tuán)隊(duì)，第8天全換成了Markdown

協(xié)調(diào)3個(gè)以上AI編程代理（agent）時(shí)，你會(huì)本能地選JSON定義任務(wù)。結(jié)構(gòu)清晰、機(jī)器友好、毫無(wú)歧義。我堅(jiān)持了整整7天，第8天全刪了。

問(wèn)題不在解析。問(wèn)題在于"解析之外的一切"。

JSON的隱形稅：每次查看都要交

這是典型的JSON任務(wù)定義：

{"id": 27, "title": "Add JWT authentication to the API", "status": "in-progress", "assigned_to": "engineer-1", "description": "Implement JWT-based auth middleware...", "acceptance_criteria": ["All protected routes return 401...", "Login endpoint returns...", "Tests cover happy path..."]}

機(jī)器讀這個(gè)毫無(wú)壓力。但當(dāng)你監(jiān)督AI團(tuán)隊(duì)、需要快速掃一眼進(jìn)展時(shí)，每次交互都要借助工具。你不能直接"看"懂它。

同樣的任務(wù)換成Markdown：

id: 27

status: in-progress

assigned_to: engineer-1

# Add JWT authentication to the API

Implement JWT-based auth middleware for all protected routes. Use the jsonwebtoken crate. Add login and refresh endpoints.

## Acceptance criteria

- All protected routes return 401 without valid token

- Login endpoint returns access + refresh tokens

- Tests cover happy path and expired token

YAML前置元數(shù)據(jù)承載結(jié)構(gòu)化數(shù)據(jù)（ID、狀態(tài)、負(fù)責(zé)人），正文是自由格式的Markdown——人類和AI都能原生閱讀。

忘掉Jira：一個(gè)目錄就是看板

不需要數(shù)據(jù)庫(kù)，不需要API，不需要特殊工具。

看板就是一個(gè)Markdown文件目錄：

board/tasks/

027-add-jwt-authentication.md # status: in-progress

028-write-api-tests.md # status: todo

029-fix-dashboard-css.md # status: done

想看進(jìn)行中的任務(wù)？一行命令：

grep -l "status: in-progress" board/tasks/*.md

想看完整看板？shell腳本搞定：

for f in board/tasks/*.md; do

status=$(grep "^status:" "$f" | cut -d' ' -f2)

title=$(grep "^# " "$f" | head -1 | sed 's/^# //')

printf "%-15s %s\n" "$status" "$title"

done

輸出：

in-progress Add JWT authentication to the API

todo Write API endpoint tests

done Fix dashboard CSS bug

標(biāo)準(zhǔn)Unix命令操作標(biāo)準(zhǔn)文件。沒有供應(yīng)商鎖定，沒有月費(fèi)，沒有"功能即將下線"的郵件。

為什么AI更懂Markdown

AI編程代理已經(jīng)理解Markdown。它的訓(xùn)練數(shù)據(jù)里有數(shù)百萬(wàn)份README文件、issue描述、文檔頁(yè)面。

你給代理一個(gè)Markdown任務(wù)文件，它讀標(biāo)題、理解驗(yàn)收標(biāo)準(zhǔn)、直接開干。

換成JSON呢？代理能解析，但格式對(duì)它來(lái)說(shuō)是陌生的。它要額外推理："這個(gè)字段是干什么的？嵌套數(shù)組怎么理解？"

Markdown的語(yǔ)義是顯式的。# 是標(biāo)題，- 是列表，## 是子標(biāo)題。AI和人類用同一套直覺。

有個(gè)細(xì)節(jié)很多人沒意識(shí)到：當(dāng)你用JSON時(shí)，經(jīng)常要在"機(jī)器可讀"和"人類可讀"之間做取舍。加注釋？JSON不支持。多行字符串？轉(zhuǎn)義地獄。Markdown沒有這種撕裂——它生來(lái)就是給人看的，機(jī)器恰好也能讀。

實(shí)戰(zhàn)中的3個(gè)反直覺發(fā)現(xiàn)

第一，版本控制更干凈。Git diff看Markdown的變更，你能一眼看出"改了哪條驗(yàn)收標(biāo)準(zhǔn)"。JSON的diff是一行被標(biāo)記為修改，實(shí)際要人工比對(duì)字段。

第二，LLM（大語(yǔ)言模型）的上下文利用率更高。代理讀Markdown時(shí)，token消耗更貼近有效信息密度。JSON的括號(hào)、引號(hào)、縮進(jìn)都是噪音。

第三，人機(jī)協(xié)作無(wú)縫切換。凌晨2點(diǎn)你爬起來(lái)看進(jìn)度，cat一個(gè).md文件就能看懂。JSON？你得找格式化工具，或者瞇眼數(shù)嵌套層級(jí)。

我試過(guò)讓代理自己寫任務(wù)文件。給JSON格式，它經(jīng)常漏掉引號(hào)或逗號(hào)，導(dǎo)致解析失敗。給Markdown模板，出錯(cuò)率驟降——因?yàn)楦袷饺蒎e(cuò)性更高，且視覺反饋即時(shí)。

有個(gè)產(chǎn)品經(jīng)理朋友問(wèn)我："這不就是回歸文本文件管理項(xiàng)目？倒退20年？"

我說(shuō)："20年前我們沒AI隊(duì)友。現(xiàn)在的問(wèn)題是，怎么讓碳基和硅基生物用同一種語(yǔ)言協(xié)作。Markdown是目前的最優(yōu)解，不是因?yàn)樗冗M(jìn)，是因?yàn)樗『每ㄔ趦蓚€(gè)世界的交集。"

他沉默了一會(huì)兒，回去把Notion里的SOP全導(dǎo)出成了.md。

你現(xiàn)在用JSON還是Markdown管AI任務(wù)？如果試過(guò)兩者，哪個(gè)讓你凌晨2點(diǎn)的調(diào)試更痛苦？