协调3个以上AI编程代理（agent）时，你会本能地选JSON定义任务。结构清晰、机器友好、毫无歧义。我坚持了整整7天，第8天全删了。
问题不在解析。问题在于"解析之外的一切"。
JSON的隐形税：每次查看都要交
这是典型的JSON任务定义：
{"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..."]}
机器读这个毫无压力。但当你监督AI团队、需要快速扫一眼进展时，每次交互都要借助工具。你不能直接"看"懂它。
同样的任务换成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前置元数据承载结构化数据（ID、状态、负责人），正文是自由格式的Markdown——人类和AI都能原生阅读。
忘掉Jira：一个目录就是看板
不需要数据库，不需要API，不需要特殊工具。
看板就是一个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
想看进行中的任务？一行命令：
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
标准Unix命令操作标准文件。没有供应商锁定，没有月费，没有"功能即将下线"的邮件。
为什么AI更懂Markdown
AI编程代理已经理解Markdown。它的训练数据里有数百万份README文件、issue描述、文档页面。
你给代理一个Markdown任务文件，它读标题、理解验收标准、直接开干。
换成JSON呢？代理能解析，但格式对它来说是陌生的。它要额外推理："这个字段是干什么的？嵌套数组怎么理解？"
Markdown的语义是显式的。# 是标题，- 是列表，## 是子标题。AI和人类用同一套直觉。
有个细节很多人没意识到：当你用JSON时，经常要在"机器可读"和"人类可读"之间做取舍。加注释？JSON不支持。多行字符串？转义地狱。Markdown没有这种撕裂——它生来就是给人看的，机器恰好也能读。
实战中的3个反直觉发现
第一，版本控制更干净。Git diff看Markdown的变更，你能一眼看出"改了哪条验收标准"。JSON的diff是一行被标记为修改，实际要人工比对字段。
第二，LLM（大语言模型）的上下文利用率更高。代理读Markdown时，token消耗更贴近有效信息密度。JSON的括号、引号、缩进都是噪音。
第三，人机协作无缝切换。凌晨2点你爬起来看进度，cat一个.md文件就能看懂。JSON？你得找格式化工具，或者眯眼数嵌套层级。
我试过让代理自己写任务文件。给JSON格式，它经常漏掉引号或逗号，导致解析失败。给Markdown模板，出错率骤降——因为格式容错性更高，且视觉反馈即时。
有个产品经理朋友问我："这不就是回归文本文件管理项目？倒退20年？"
我说："20年前我们没AI队友。现在的问题是，怎么让碳基和硅基生物用同一种语言协作。Markdown是目前的最优解，不是因为它先进，是因为它恰好卡在两个世界的交集。"
他沉默了一会儿，回去把Notion里的SOP全导出成了.md。
你现在用JSON还是Markdown管AI任务？如果试过两者，哪个让你凌晨2点的调试更痛苦？
热门跟贴