AI Markdown

ai-md
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.60/5
使用13.3K

AI.MD v4 — 完整的 AI 原生转换系统

何时使用此技能

  • 当你的 CLAUDE.md 内容很长，但 AI 仍然忽略你的规则时
  • 当冗长的系统指令导致 Token 消耗过高时
  • 当你想优化任何 LLM 系统提示词以提高合规性时
  • 当你在不同的 AI 工具（Claude, Codex, Gemini, Grok）之间迁移规则时

什么是 AI.MD？

AI.MD 是一套方法论，旨在将人类编写的 CLAUDE.md（或任何 LLM 系统指令）转换为结构化标签格式。这种格式能让 AI 模型更可靠地执行指令，且占用更少的 Token。

我们证明的一个悖论： 用自然语言增加更多规则反而会降低合规性。
而将相同的规则转换为结构化格式，则能恢复并超越原有的合规水平。

code
人类散文 (6 条规则, 1 行)  → AI 执行 4 条
结构化标签 (6 条规则, 6 行) → AI 执行全部 6 条
内容相同，格式不同，结果迥异。

---

为什么有效：LLM 究竟如何处理指令

LLM 不是在“阅读”，而是在进行注意力分配（Attend）。理解这一点将改变一切。

机制 1：注意力分散 (Attention Splitting)

当多条规则共享同一行时，模型的注意力会平均分配到所有 Token 上。
每条规则只能获得一部分注意力权重，导致部分规则被遗漏。

当每条规则独占一行时，模型将其处理为一个独立的单元。
每条规则都能获得完整的注意力权重。

code
# 单行 = 注意力被 5 分 (部分规则权重接近于零)
EVIDENCE: no-fabricate no-guess | 禁用詞:應該是/可能是 → 先拿數據 | Read/Grep→行號 curl→數據 | "好像"/"覺得"→自己先跑test | guess=shame-wall

五行 = 每条规则获得完整注意力

EVIDENCE:
  core: no-fabricate | no-guess | unsure=say-so
  banned: 應該是/可能是/感覺是/推測 → 先拿數據
  proof: all-claims-need(data/line#/source) | Read/Grep→行號 | curl→數據
  hear-doubt: "好像"/"覺得" → self-test(curl/benchmark) → 禁反問user
  violation: guess → shame-wall

机制 2：零推理标签 (Zero-Inference Labels)

自然语言迫使模型从上下文中推断（Infer）含义。
标签则声明（Declare）含义。无需推断 = 没有误解。

code
# AI 必须推断：(防搞混) 修饰什么？例外适用于什么？
GATE-1: 收到任務→先用一句話複述(防搞混)(長對話中每個新任務都重新觸發) | 例外: signals命中「處理一下」=直接執行

AI 直接读取标签：触发条件→动作→例外。零歧义。

GATE-1 複述:
  trigger: new-task
  action: first-sentence="你要我做的是___"
  persist: 長對話中每個新任務都重新觸發
  exception: signal=處理一下 → skip
  yields-to: GATE-3

核心洞察：像 trigger: action: exception: 这样的标签在所有语言中都通用。
模型不需要解析中文/日文/英文的语法来理解结构。
标签是人类与 AI 之间的通用语言。

机制 3：语义锚定 (Semantic Anchoring)

带标签的子项创建了可匹配的标签（Matchable Tags）。当用户的输入包含某个关键词时，
模型会将其直接匹配到相应的标签上——就像哈希表查询，而不是全文搜索。

code
# 埋没：AI 扫描整个句子，可能会错过关联
加新功能→第一句問schema | 新增API/endpoint=必確認health-check.py覆蓋

锚定：标签 "new-api:" 直接匹配用户说的 "加个 API"

MOAT:
  new-feature: 第一句問schema/契約/關聯
  new-api: 必確認health-check.py覆蓋(GATE-5)

真实证明： 这一特定技术修复了一个在所有模型中连续失败 5 次的测试用例。
abel new-api: 让 Codex T5 在首次尝试时就从 ❌ 变为 ✅。

---

转换流程：当你给我一份 CLAUDE.md 时发生了什么

以下是我将自然语言指令转换为 AI.MD 格式时所采用的精确思维模型。

第一阶段：理解 (UNDERSTAND) —— 像编译器一样阅读，而非像人类一样

我阅读 CLAUDE.md 的方式就像在构建一个状态机，而不是在阅读一份文档。

对于每一句话，我都会询问：
1. 这是一个 触发器 (TRIGGER) 吗？（什么输入会激活此行为？）
2. 这是一个 动作 (ACTION) 吗？（AI 应该做什么？）
3. 这是一个 约束 (CONSTRAINT) 吗？（AI 不应该做什么？）
4. 这是 元数据 (METADATA) 吗？（优先级、时机、持久性、例外情况？）
5. 这是 人类解释 (HUMAN EXPLANATION) 吗？（规则存在的原因 —— 应当删除）

分析示例：

code
输入："收到任務→先用一句話複述(防搞混)(長對話中每個新任務都重新觸發) | 例外: signals命中「處理一下」=直接執行"

分解：
  ├─ TRIGGER:    "收到任務" → new-task
  ├─ ACTION:     "先用一句話複述" → first-sentence="你要我做的是___"
  ├─ DELETE:     "(防搞混)" → 人类动机，AI 不需要这个
  ├─ METADATA:   "(長對話中每個新任務都重新觸發)" → persist: every-new-task
  └─ EXCEPTION:  "例外: signals命中「處理一下」=直接執行" → exception: signal=處理一下 → skip

第二阶段：分解 (DECOMPOSE) —— 将每个 | 和 () 拆分为原子规则

导致指令执行失败的首要原因是复合规则。
一行包含 3 条由 | 分隔的规则，在 AI 看来就像是 1 条指令。
它需要被拆分为 3 条独立的指令。

拆分测试： 如果你可以在句子的两个部分之间加入“并且 (AND)”，
那么它们就是独立的规则，必须分行书写。

code
# 输入：一句话隐藏了 4 条规则
禁用詞:應該是/可能是→先拿數據 | "好像"/"覺得"→自己先跑test(不是問user)→有數據才能決定

分析：我发现了 4 条隐藏规则

规则 1: 禁用某些词汇 → 改用数据
规则 2: 听到质疑词汇 → 运行自测
规则 3: 不要向用户询问数据 → 自己查找
规则 4: 偏好主张 → 在接受前需要 A/B 对比

输出：4 条原子规则

banned: 應該是/可能是/感覺是/推測 → 先拿數據
hear-doubt: "好像"/"覺得" → self-test(curl/benchmark)
self-serve: 禁反問user(自己查)
compare: "覺得A比B好" → A/B實測先行

第三阶段：标记 (LABEL) —— 分配功能标签

每条原子规则都会获得一个声明其功能的标签。
我使用一套包含约 12 种标签类型的标准词汇表：

| 标签 | 声明内容 | 使用场景 |
|-------|-----------------|-------------|
| trigger: | 激活此规则的输入 | 每个门控/规则都需要一个 |
| action: | AI 必须执行的操作 | 核心行为 |
| exception: | 何时不需要执行 | 覆盖情况 |
| not-triggered: | 明确的负面示例 | 防止过度触发 |
| format: | 输出格式约束 | 位置、结构要求 |
| priority: | 覆盖关系 | 规则冲突时 |
| yields-to: | 哪个门控优先 | 门控间的优先级 |
| persist: | 跨轮对话的持久性 | 在对话流中持续生效的规则 |
| timing: | 在工作流中的时机 | 前/后/期间的约束 |
| violation: | 违反后的后果 | 问责机制 |
| banned: | 禁止的词汇/动作 | 硬性禁区列表 |
| policy: | 决策启发式 | 需要判断时 |

标签选择技巧： 我会选择一个即使是另一个 AI 模型（而非被指令的模型）在仅看到标签的情况下也能理解该规则功能的标签。
如果 trigger: 能在不阅读其他内容的情况下清晰地告诉你“这是激活规则的条件”，那么它就是正确的标签。

第四阶段：结构化 (STRUCTURE) —— 构建架构

我将规则组织成一个层级结构：

code
<gates>    = 硬停止（在执行任何操作前必须检查）
action) <rules> = 行为准则（如何行动） <rhythm> = 工作流模式（何时执行何事） <conn> = 连接字符串（事实——绝不压缩） <ref> = 按需引用（仅在需要时加载） <learn> = 演进规则（系统如何改进）
code
为什么顺序至关重要：
Gate（门控）必须排在最前，因为在执行任何操作前必须先检查它们。
模型按从上到下的顺序处理指令。优先级 = 位置。

分组技巧： 属于同一领域的规则应作为子项归类在一个标题下。

扁平化（差）：7 条无关规则，模型将其视为同等权重


1. 禁止猜测
2. 编辑前备份
3. 输出使用表格
4. 部署后检查健康状态
5. 不要说“應該是”
6. 报告前测试
7. 所有主张都需要证明

分组化（好）：3 个领域，模型能理解层级结构

EVIDENCE (证据): ← 领域：真实性 core: no-guess (禁止猜测) banned: 應該是 (禁用词) proof: all-claims-need-data (所有主张需数据支持)

SCOPE (范围): ← 领域：安全性
pre-change: backup (变更前备份)
pre-run: check-health (运行前检查健康状态)

OUTPUT (输出): ← 领域：格式
format: tables+numbers (表格+数字)

code
### 第 5 阶段：RESOLVE —— 处理冲突与边缘情况


这是最关键且最不直观的阶段。自然语言指令通常包含隐藏冲突，人类凭直觉可以解决，但 AI 不行。


技巧：冲突检测矩阵


我会检查每对 Gate/规则是否存在冲突：

GATE-1 (複述: 重复任务) vs GATE-3 (保護檔: 先备份)
→ 冲突：如果用户说“编辑 .env”，AI 应该先重复任务，还是先备份？
→ 解决：优先级：GATE-3 > GATE-1（安全高于礼貌）
让步：GATE-3 (在 GATE-1 中明确标注)

GATE-4 (報結論: 引用证据) vs bug-close (記錄根因: 写入根因)
→ 冲突：bug-close 要求陈述根因，但 GATE-4 禁止下绝对结论
→ 解决：时机：GATE-4 是结论前的刹车；bug-close 是验证后的记录
当 bug 已验证时，不触发 GATE-4

EVIDENCE (no-guess) vs 用户说“處理一下” (直接执行)
→ 冲突：AI 应该验证假设还是立即执行？
→ 解决：信号 “處理一下” = 用户已决定，跳过确认

code
技巧：非触发列表 (Not-Triggered Lists)


对于任何可能过度触发的规则，我会添加明确的负面示例：

GATE-4 報結論:
触发条件: 最终归因 / 根因判定 / 不可逆建议
非触发条件: 中间进度数字 | 纯指标查询 | 工具原始输出 | 已知事实 | 转述文件
code
这一发现源于 Gemini 2.5 Pro 在处理像“成功率怎么样？”这种简单的数字查询时不断触发 GATE-4。添加 非触发条件: 纯指标查询 后立即解决了该问题。


第 6 阶段：TEST —— 多模型验证（不可或缺）


这不是可选步骤。 每次转换必须经过 2 个以上不同 LLM 模型的验证。


原因在于：在 Claude 上运行完美的格式可能会让 GPT 感到困惑，反之亦然。AI.MD 的核心目标就是实现跨模型通用。


我们制定的测试协议：


1. 编写 8 个模拟真实用户行为的测试输入（而非教科书示例）
2. 包含两条规则冲突的“陷阱”问题
3. 包含不应触发规则的“负面”测试
4. 不要暗示正在测试哪条规则（AI 不应预知）
5. 独立运行每个模型
6. 为每个答案评分：✅ 完全符合，⚠️ 部分符合，❌ 缺失
7. 如果任何模型的得分在转换后下降 $\rightarrow$ 回滚该特定更改


我们使用的 8 题模板：

T1: 简单任务（GATE-1 是否触发？）
T2: 尝试写入数据库（GATE-2 是否拦截？）
T3: 编辑受保护文件（GATE-3 是否在 GATE-1 之前触发？）
T4: 根因分析...
code
ause 分析（GATE-4 是否要求全部 4 个问题？）
T5：新增 Business API（AI 是否提及 health-check.py？）
T6：用户说“好像 X 比 Y 好”（AI 是执行对比还是直接接受？）
T7：用户说“处理一下”（AI 是否跳过 GATE-1 确认？）
T8：简单的指标查询（GATE-4 是否不触发？）

---

实战测试中发现的特殊技巧

技巧 1：双语标签策略

标签使用英文，输出字符串使用用户语言。
英文标签更短，且被所有模型更普遍地理解。
但 AI 实际生成的文本必须保持为用户语言。

code
action: first-sentence="你要我做的是___"    ← AI 输出中文
format: must-be-line-1                      ← 英文结构约束
banned: 應該是/可能是                        ← 禁用词保持原语言

生效原因： 英文标签词汇（trigger, action, exception）直接映射到每个模型训练数据中的概念。而中文语法标签（触发条件, 执行动作, 例外情况）在不同模型间的标准化程度较低。

技巧 2：状态机闸门 (State Machine Gates)

不要将规则视为扁平列表，而应将其建模为状态机：

  • 每个闸门（gate）有一个 trigger（输入状态）

  • 每个闸门有一个 action（转换）

  • 闸门具有 priority（当多个匹配时，哪个先触发）

  • 闸门具有 yields-to（明确的冲突解决机制）

这为 AI 提供了清晰的执行模型：

code
输入到达 → 先检查 GATE-3（最高优先级） → 检查 GATE-1 → 检查 GATE-2 → ...

而不是：

code
输入到达 → 阅读所有规则 → 尝试判断适用哪一条 → 可能会遗漏

技巧 3：使用 XML 标签定义语义边界

使用 <gates>, <rules>, <rhythm>, <conn> 作为章节分隔符，可以创建硬边界，防止规则渗漏（即模型混淆某条规则属于哪个章节）。

xml
<gates label="硬性闸门 | 优先级: gates>rules>rhythm | 缺一项=STOP">
...此处为闸门内容...
</gates>

<rules>
...此处为规则内容...
</rules>

起始标签上的 label 属性充当章节级指令：“这些是硬性闸门，这是它们的优先级，缺失则停止”。

技巧 4：交叉引用而非重复

当同一个概念出现在多条规则中时，不要重复描述，而应使用交叉引用标签。

code
# 错误做法：health-check 在 3 处被提及
GATE-5: ...检查 health-check.py...
MOAT: ...必须检查 health-check.py...
SCOPE: ...验证 health-check.py 是否存在...

正确做法：单一事实来源 + 交叉引用

GATE-5 验收:
  checks:
    新增API → 確認health-check.py覆蓋

MOAT:
  new-api: 必確認health-check.py覆蓋(GATE-5)    ← 交叉引用，而非重复

技巧 5：“只写‘做什么’，不写‘为什么’”原则

删除所有为了解释规则存在原因而编写的文本。AI 需要的是“做什么”（WHAT），而不是“为什么”（WHY）。

code
# 删除这些面向人类的解释：
(防搞混)                     → 动机
(不是大爆破,是每次顺手一点)    → 比喻
(想清楚100倍后才做现在的)     → 背景故事
(因为用户是非工程师)          → 理由

仅保留可执行的指令：

action: first-sentence="你要我做的是___"
refactor: 同区块连续第3次修改 → 提取

每删除一条解释都能节省 token，并消除可能干扰模型执行实际操作的噪音。

---

两阶段工作流

第一阶段：预览 (PREVIEW) —— 测量，不触碰

bash
echo "=== Current Token Burn ==="
claude_md=$(wc -c < ~/.claude/CLAUDE.md 2>/dev/null || echo 0)
rules=$(cat ~/.claude/rules/*.md 2>/dev/null | wc -c || echo 0)
total=$((claude_md + rules))
tokens=$((total / 4))
echo "CLAUDE.md:     $claude_md by
tes"
echo "rules/*.md:    $rules bytes"
echo "Total:         $total bytes ≈ $tokens tokens/turn"
echo "50-turn session: ≈ $((tokens * 50)) tokens on instructions alone"

然后：读取所有自动加载的文件。识别冗余、散文式冗余（prose overhead）和重复规则。

在继续之前询问用户：“是否需要精简 (distill)？”

第二阶段：DISTILL —— 带安全网的转换

1. 备份：cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak-pre-distill
2. 阶段 1-5：运行上述完整的转换流程
3. 阶段 6：运行多模型测试（至少 2 个模型，8 个问题）
4. 报告：显示转换前后的得分

code
=== AI.MD 转换完成 ===

之前：{old} bytes ({old_score} 合规度)
之后：{new} bytes ({new_score} 合规度)
节省：{percent}% bytes, 合规度提升 {delta} 分


备份：~/.claude/CLAUDE.md.bak-pre-distill
还原：cp ~/.claude/CLAUDE.md.bak-pre-distill ~/.claude/CLAUDE.md

---

AI 原生模板

xml
# 项目名称 | 语言:xx | 供 AI 解析 | 优化目标=结果优先于格式

<user>
身份, 语气, 信号, 决策风格 (键: 值 对)
</user>


<gates label="硬性闸门 | 优先级: gates>rules>rhythm | 缺一项=停止">


GATE-1 名称:
  触发条件: ...
  执行动作: ...
  异常情况: ...
  让位于: ...


GATE-2 名称:
  触发条件: ...
  执行动作: ...
  策略: ...


</gates>


<rules>


规则名称:
  核心: ...
  禁用: ...
  听到 X: ... → 执行动作
  违规处理: ...


</rules>


<rhythm>
工作流模式 (键: 值 对)
</rhythm>


<conn>
连接字符串 (保持原样 —— 绝不要压缩事实/凭据/URL)
</conn>


<ref label="按需只读">
文件路径 → 用途
</ref>


<learn>
系统如何随时间演进
</learn>

---

反模式 (Anti-Patterns)

| 不要 | 建议做法 | 原因 |
|-------|------------|-----|
| 在 CLAUDE.md 中使用人类散文 | 使用结构化标签 | 散文需要推理；标签则直接明了 |
| 一行写多条规则 | 一行一个概念 | 密集行会导致注意力分散 |
| 使用括号解释 | 直接删除 | AI 需要的是“做什么”而非“为什么” |
| 同一条规则出现 3 次 | 单一来源 + 交叉引用 | 重复内容可能会产生分歧并导致混淆 |
| 20 条以上的扁平规则 | 5-7 个领域及其子项 | 层级结构有助于模型组织行为 |
| 未经测试直接压缩 | 使用 2 个以上模型验证 | 对 Claude 有效的方案在 GPT 上可能会失效 |
| 认为格式不重要 | 进行测试 —— 格式很重要 | 相同内容，不同格式 = 不同合规度 |
| 仅使用中文标签 | 英文标签 + 原生语言输出 | 英文标签在不同模型间的通用性更强 |
| 扁平的规则列表 | 带优先级的状态机 | 清晰的执行顺序可防止遗漏规则 |

---

实际效果

2026-03 测试，washinmura.jp CLAUDE.md，5 轮，4 个模型：

| 轮次 | 变更 | Codex (GPT-5.3) | Gemini 2.5 Pro | Claude Opus 4.6 |
|-------|--------|-----------------|----------------|-----------------|
| R1 (基准散文) | — | 8/8 | 7/8 | 8/8 |
| R2 (增加规则) | +gates +examples | 7/8 | 6/8 | — |
| R3 (精炼散文) | +exceptions +non-triggers | 6/8 | 6.5/8 | — |
| R4 (AI 原生转换) | 结构化标签 | 8/8 | 7/8 | 8/8 |

核心发现：
1. 散文规则越多 = 合规度越差 (R1→R3：随着规则增加，得分下降)
2. 结构化格式 = 恢复并超越 (R4：尽管规则更多，但得分回升至最高)
3. 跨模型一致性：对一个模型有效的格式通常对所有模型都有效（Grok 除外）
4. 语义锚定：new-api: 标签的修复是影响最大的单一变更

残酷的事实：你那精美且精心编写的 CLAUDE.md
可能会损害你的 AI 性能。结构 > 散文。始终如此。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。