AI.MD 结构化标注转换系统实战指南把 CLAUDE.md 从低遵从度的散文改写成跨模型高遵从度的 AI 原生指令【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills本文以agentic-awesome-skills仓库中的 AI.MD v4 技能为核心完整讲解如何将人类书写的CLAUDE.md或任意 LLM 系统提示词转换为结构化标签格式使 AI 模型用更少的 token 获得更高的规则遵从度。读完本文你将掌握一套经过多模型实战验证的六阶段转换方法论理解、拆解、标注、结构化、冲突消解、多模型测试以及可直接复制的 AI 原生模板与两阶段蒸馏工作流。一、AI.MD 是什么一次格式革命而非内容革命AI.MDAI-Native Markdown是一套把人类书写的CLAUDE.md或任何 LLM 系统指令转换为结构化标签格式的方法论。它位于本仓库的plugins/agentic-awesome-skills-claude/skills/ai-md/目录下由入口文件 SKILL.md 与完整程序指南 detailed-guide.md 两部分组成——后者保留了完整的操作流程与参考材料前者的安全性、前置条件与校验要求必须视为强制执行项。其核心主张可以概括为一个经过实战验证的悖论人类散文6 条规则1 行 → AI 只遵循其中 4 条 结构化标签6 条规则6 行 → AI 全部遵循 6 条 同样的内容。不同的格式。不同的结果。同样的内容不同的格式产生不同的遵从度——这正是 AI.MD 与传统提示词工程最本质的区别它不新增规则、不堆砌约束而是改变规则的呈现形态。在仓库的目录索引 skills_index.json 中该技能被归入ai-ml分类标注风险等级为safe、来源为community并被登记为支持 Claude 目标、同时明确列出了target_specific_home_path的适配限制——这意味着示例中的~/.claude/CLAUDE.md路径与具体模型部署环境强相关实际使用时需要按自己的环境调整。二、适用场景与边界什么时候该用 AI.MD依据 SKILL.md 中的说明该技能适合以下四种典型场景你的CLAUDE.md很长但 AI 仍然无视你的规则冗长的系统指令导致 token 消耗过高你想优化任意 LLM 系统提示词的遵从度你需要在不同 AI 工具Claude、Codex、Gemini、Grok之间迁移规则。同时它也有明确的使用边界Limitations仅当任务与上述范围完全匹配时才使用输出结果不能替代环境特定的验证、测试或专家评审当输入、权限、安全边界或成功标准缺失时必须停下来向用户澄清。三、为什么有效LLM 处理指令的三大底层机制AI.MD 的设计并非凭空猜测而是建立在对 LLM 注意力机制的理解之上。关键前提是LLM 不是阅读指令而是注意力加权指令。理解这一点是理解整个方法论的地基。机制一注意力分裂Attention Splitting当多条规则挤在同一行时模型的注意力会均等地分散到所有 token 上每条规则只获得一部分注意力权重部分规则甚至衰减到接近零。# 一行 注意力被 5 条规则瓜分部分规则权重趋近于零 EVIDENCE: no-fabricate no-guess | 禁用詞:應該是/可能是 → 先拿數據 | Read/Grep→行號 curl→數據 | 好像/覺得→自己先跑test | guessshame-wall # 五行 每条规则获得完整注意力 EVIDENCE: core: no-fabricate | no-guess | unsuresay-so banned: 應該是/可能是/感覺是/推測 → 先拿數據 proof: all-claims-need(data/line#/source) | Read/Grep→行號 | curl→數據 hear-doubt: 好像/覺得 → self-test(curl/benchmark) → 禁反問user violation: guess → shame-wall拆行 给每条规则分配完整的注意力权重。这是后续 Phase 2拆解的理论依据。机制二零推断标签Zero-Inference Labels自然语言要求模型从上下文中推断语义而标签是直接声明语义。不需要推断就不会产生误解。# AI 必须推断(防搞混) 修饰什么例外 适用于什么 GATE-1: 收到任務→先用一句話複述(防搞混)(長對話中每個新任務都重新觸發) | 例外: signals命中「處理一下」直接執行 # AI 直接读取标签trigger→action→exception零歧义 GATE-1 複述: trigger: new-task action: first-sentence你要我做的是___ persist: 長對話中每個新任務都重新觸發 exception: signal處理一下 → skip yields-to: GATE-3关键洞察在于trigger:、action:、exception:这类标签跨语言通用。模型不需要解析中文、日文或英文的语法就能理解结构——标签是人与 AI 之间的通用语言。机制三语义锚定Semantic Anchoring带标签的子条目会形成可匹配的标记tag。当用户输入包含某个关键词时模型直接将输入与对应标签匹配如同哈希表查找而非全文检索。# 深埋AI 扫描整个句子可能错过关联 加新功能→第一句問schema | 新增API/endpoint必確認health-check.py覆蓋 # 锚定标签 new-api: 直接命中用户说的 加个 API MOAT: new-feature: 第一句問schema/契約/關聯 new-api: 必確認health-check.py覆蓋(GATE-5)文档记录了一个真实证据这一技术修复了一个连续 5 次在全部模型上失败的测试用例——new-api:标签让 Codex T5 第一次尝试就从 ❌ 变为 ✅。四、六阶段转换流程从散文到状态机当你把一份CLAUDE.md交给 AI.MD 系统时内部会执行六个严格的转换阶段。这套流程是 AI.MD 方法论的核心骨架。Phase 1理解UNDERSTAND——像编译器一样阅读读CLAUDE.md时不是像读文档而是像构建一台状态机。对每个句子依次提出五个问题这是TRIGGER触发器吗什么输入激活这个行为这是ACTION动作吗AI 应该做什么这是CONSTRAINT约束吗AI 不应该做什么这是METADATA元数据吗优先级、时机、持久性、例外这是HUMAN EXPLANATION人类解释吗规则为什么存在——直接删除文档给出了完整示例分解输入: 收到任務→先用一句話複述(防搞混)(長對話中每個新任務都重新觸發) | 例外: signals命中「處理一下」直接執行 分解: ├─ TRIGGER: 收到任務 → new-task ├─ ACTION: 先用一句話複述 → first-sentence你要我做的是___ ├─ DELETE: (防搞混) → 人类动机AI 不需要 ├─ METADATA: (長對話中每個新任務都重新觸發) → persist: every-new-task └─ EXCEPTION: 例外: signals命中「處理一下」直接執行 → exception: signal處理一下 → skip注意其中最关键也最反直觉的一步把括号内的为什么直接删除。Phase 2拆解DECOMPOSE——把复合规则拆成原子规则复合规则是遵从度失败的头号来源。一行用|分隔 3 条规则对 AI 来说看起来就是 1 条指令但实际需要的是 3 条独立指令。拆分的判定标准The Splitter Test如果一句话的两个部分之间能加上 AND那它们就是两条独立规则必须分列两行。# 输入一句话里藏着 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實測先行Phase 3标注LABEL——约 12 种标准功能标签每条原子规则都必须获得一个声明其功能的标签。AI.MD 使用约 12 种标准标签词汇表标签声明的内容使用时机trigger:什么输入激活此规则每个 gate/规则都需要一个action:AI 必须做什么核心行为exception:什么时候不执行覆盖场景not-triggered:明确的负例防止过度触发format:输出格式约束位置、结构要求priority:覆盖关系规则冲突时yields-to:哪个 gate 优先gate 间优先级persist:跨轮次持久性对话流中存活的规则timing:工作流中的时机前/后/期间约束violation:违反的后果问责机制banned:禁用词/禁用行为硬性禁区清单policy:决策启发式需要判断时标签选择技巧选择一个让另一个不同的 AI 模型而不是被指令的模型仅看标签就能理解该规则功能的标签。如果trigger:无需阅读其他内容就能告诉你这是激活规则的条件那就是正确的标签。Phase 4结构化STRUCTURE——构建层级架构将规则组织为固定的层级区块gates 硬性闸门任何行动前必须检查 rules 行为准则如何行动 rhythm 工作流模式何时做什么 conn 连接串事实——绝不压缩 ref 按需参考需要时才加载 learn 进化规则系统如何改进顺序即优先级gate 必须放在最前面因为模型自上而下处理指令位置即优先级。同时共享同一领域的规则应归入同一标题下的子条目# 扁平差7 条无关规则模型等权重对待 1. no guessing 2. backup before editing 3. use tables for output 4. check health after deploy 5. dont say 應該是 6. test before reporting 7. all claims need proof # 分组好3 个领域模型理解层级 EVIDENCE: ← 领域真实性 core: no-guess banned: 應該是 proof: all-claims-need-data SCOPE: ← 领域安全 pre-change: backup pre-run: check-health OUTPUT: ← 领域格式 format: tablesnumbersPhase 5消解RESOLVE——冲突检测与边界界定这是最关键也最不直观的阶段。自然语言指令中常常隐藏着人类靠直觉解决、而 AI 无法解决的冲突。冲突检测矩阵逐一检查每对 gate/rule 是否冲突并给出显式消解GATE-1 (複述: 复述任务) vs GATE-3 (保護檔: 先备份) → 冲突用户说 edit .env 时AI 应该先复述任务还是先备份 → 消解priority: GATE-3 GATE-1安全优先于礼貌 yields-to: GATE-3在 GATE-1 中显式声明 GATE-4 (報結論: 引用证据) vs bug-close (記錄根因: 记录根因) → 冲突bug-close 要求陈述根因但 GATE-4 禁止武断结论 → 消解timing: GATE-4 是结论前的刹车bug-close 是验证后的记录 GATE-4 not-triggered when bug already verified EVIDENCE (no-guess) vs 用户说 處理一下直接执行 → 冲突AI 应该验证假设还是立即执行 → 消解信号 處理一下 用户已决定跳过确认Not-Triggered 负例清单对任何可能过度触发的规则显式添加反例。例如 Gemini 2.5 Pro 曾在简单的数字查询如成功率怎麼樣?上反复误触发 GATE-4添加not-triggered: 純指標查詢后立即修复GATE-4 報結論: trigger: 最終歸因/根因判定/不可逆建議 not-triggered: 中間進度數字 | 純指標查詢 | 工具原始輸出 | 已知事實 | 轉述文件Phase 6测试TEST——多模型校验不可妥协这一步不可省略。每一次转换必须经过2 个以上不同 LLM 模型的验证。原因很简单对 Claude 完美工作的格式可能让 GPT 困惑反之亦然——AI.MD 的全部意义就在于跨模型有效。文档给出了完整的考试协议Exam Protocol编写 8 个模拟真实用户行为而非教科书示例的测试输入包含两条规则冲突的陷阱题包含规则不应触发的负向测试不提示正在测试哪些规则AI 不应该知道每个模型独立运行每题评分✅ 完全遵从、⚠️ 部分遵从、❌ 未遵从若任一模型转换后分数下降 →回退该具体改动。配套的 8 题模板T1: 简单任务GATE-1 会触发吗 T2: 数据库写入尝试GATE-2 能捕获吗 T3: 受保护文件编辑GATE-3 会在 GATE-1 之前触发吗 T4: 根因分析GATE-4 是否要求全部 4 个问题 T5: 新增业务 APIAI 会提到 health-check.py 吗 T6: 用户说 好像X比Y好AI 会运行对比还是直接接受 T7: 用户说 處理一下AI 会跳过 GATE-1 确认吗 T8: 简单指标查询GATE-4 不触发吗五、实战中发现的五项特殊技术技术一双语标签策略标签用英文输出串用用户语言。英文标签更短且被所有模型更普遍地理解但 AI 实际产出的文本必须保留用户语言。action: first-sentence你要我做的是___ ← AI 输出中文 format: must-be-line-1 ← 结构约束用英文 banned: 應該是/可能是 ← 禁用词保留原语言原因在于英文标签词汇trigger、action、exception直接映射到每个模型训练数据中的概念而中文语法标签觸發條件、執行動作、例外情況在模型间的标准化程度较低。技术二状态机闸门State Machine Gates不要把规则当作扁平列表而是建模成状态机每个 gate 有trigger输入状态每个 gate 有action状态转移gate 有priority多个匹配时谁先触发gate 有yields-to显式冲突消解。这给 AI 一个清晰的执行模型输入到达 → 先检查 GATE-3最高优先级→ 再检查 GATE-1 → 检查 GATE-2 → ...而不是输入到达 → 阅读所有规则 → 试图判断哪条适用 → 可能漏掉一条技术三XML 区块标签划定语义边界使用gates、rules、rhythm、conn作为区块分隔符建立硬边界防止规则串扰rule-bleed——即模型混淆某条规则属于哪个区块。gates label硬性閘門 | 優先序: gatesrulesrhythm | 缺一項STOP ...gates here... /gates rules ...rules here... /rules开标签上的label属性充当区块级指令这些是硬性闸门、这是它们的优先级、缺失 停止。技术四交叉引用而非重复同一概念出现在多条规则中时不要重复使用交叉引用标签。# 差health-check 在 3 处出现 GATE-5: ...check health-check.py... MOAT: ...must check health-check.py... SCOPE: ...verify health-check.py exists... # 好单一事实来源 交叉引用 GATE-5 驗收: checks: 新增API → 確認health-check.py覆蓋 MOAT: new-api: 必確認health-check.py覆蓋(GATE-5) ← 交叉引用而非重复重复的规则可能相互背离并造成混淆单一事实来源则保证一致性。技术五要什么不要为什么原则删除所有为了解释规则为什么存在而存在的文本。AI 需要的是要做什么WHAT而不是为什么WHY。# 删除这些人类解释 (防搞混) → 动机 (不是大爆破,是每次順手一點) → 比喻 (想清楚100倍後才做現在的) → 背景故事 (因為用戶是非工程師) → 正当性说明 # 只保留可执行的指令 action: first-sentence你要我做的是___ refactor: 同區塊連續第3次修改 → extract每删除一段解释既节省 token又消除了可能让模型混淆到底该做什么的噪声。六、两阶段工作流先测量再蒸馏Stage 1预览PREVIEW——只测量不修改首先用一条命令量化当前系统提示词的 token 消耗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 bytes echo rules/*.md: $rules bytes echo Total: $total bytes ≈ $tokens tokens/turn echo 50-turn session: ≈ $((tokens * 50)) tokens on instructions alone然后通读所有自动加载的文件识别冗余、散文开销与重复规则。继续之前必须征询用户需要蒸馏吗Stage 2蒸馏DISTILL——带安全网转换备份cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak-pre-distill执行 Phase 1-5运行上述完整转换流程执行 Phase 6运行多模型测试至少 2 个模型、8 道题汇报展示转换前后分数完成后输出标准报告 AI.MD Conversion Complete Before: {old} bytes ({old_score} compliance) After: {new} bytes ({new_score} compliance) Saved: {percent}% bytes, {delta} compliance points Backup: ~/.claude/CLAUDE.md.bak-pre-distill Restore: cp ~/.claude/CLAUDE.md.bak-pre-distill ~/.claude/CLAUDE.md备份文件既是安全网也提供了随时回滚的恢复命令。注意此处的~/.claude路径是针对 Claude 特定主目录的跨工具迁移时需对应替换这也是仓库将其标记为target_specific_home_path的原因。七、AI 原生模板可直接复制的骨架# PROJECT-NAME | lang:xx | for-AI-parsing | optimizeresults-over-format user identity, tone, signals, decision-style (key: value pairs) /user gates label硬性閘門 | 優先序: gatesrulesrhythm | 缺一項STOP GATE-1 name: trigger: ... action: ... exception: ... yields-to: ... GATE-2 name: trigger: ... action: ... policy: ... /gates rules RULE-NAME: core: ... banned: ... hear-X: ... → action violation: ... /rules rhythm workflow patterns as key: value pairs /rhythm conn connection strings (keep exact — NEVER compress facts/credentials/URLs) /conn ref labelon-demand Read only file-path → purpose /ref learn how system evolves over time /learn使用要点首行以# PROJECT-NAME | lang:xx | for-AI-parsing | optimizeresults-over-format作为元信息头user区块以key: value对声明身份、语气、信号与决策风格gates的label属性声明硬性闸门与优先级排序conn中的连接串、凭据、URL 属于事实绝不压缩ref区块按需加载避免把长参考文档塞进每条消息。八、反模式对照表十个不要与十个改为不要改为原因CLAUDE.md 中用人类散文结构化标签散文需要推断标签是直接声明一行写多条规则每行一个概念注意力会在密集行之间分散括号式解释删除它们AI 需要要什么而非为什么同一条规则出现在 3 处单一来源 交叉引用重复会背离并造成混淆20 条扁平规则5-7 个领域 子条目层级帮助模型组织行为不测试就压缩用 2 模型验证对 Claude 有效的可能对 GPT 无效假定格式无所谓测试它——确实有影响同样内容不同格式 不同遵从度仅中文标签英文标签 本地语言输出英文标签跨模型更通用扁平规则列表带优先级的状态机清晰的执行顺序防止漏规则九、真实世界结果多模型验证数据文档记录了一次真实的实战验证2026-03washinmura.jp 的 CLAUDE.md5 轮、4 个模型轮次改动Codex (GPT-5.3)Gemini 2.5 ProClaude Opus 4.6R1散文基线—8/87/88/8R2新增规则gates examples7/86/8—R3润色散文exceptions non-triggers6/86.5/8—R4AI 原生转换structured labels8/87/88/8四个关键发现散文规则越多 遵从度越差R1→R3规则增长的同时分数持续下降结构化格式 恢复并超越基线R4规则更多的情况下仍回到满分跨模型一致性对一个模型有效的格式对全部模型有效Grok 除外语义锚定new-api:标签是影响力最大的单项改动。十、结语结构大于散文AI.MD 方法论给出了一个反直觉但证据充分的结论你精心撰写的、优美的CLAUDE.md可能正在损害你 AI 的性能。结构大于散文Structure Prose永远如此。如果希望深入掌握完整程序建议直接阅读仓库中的 详细指南其中保留了全部安全约束、前置条件与校验要求以及入口文件 SKILL.md并对照 skills_index.json 中该技能的目录元数据理解其在仓库中的定位与适配限制。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考