问题

人类读者依赖视觉提示与上下文推断。AI Agent 摄取的是原始文本流。若没有严格的语义结构，模型就难以梳理概念之间的关系，从而导致糟糕的推理与不准确的代码建议。

为什么重要

如果您的文档未针对 LLM 优化，使用 GitHub Copilot 或 Cursor 等工具的开发者将面临更多幻觉。这会降低开发者体验。用户往往会把他们的 AI 助手所犯的错误归咎于您的产品。

方法

从"视觉优先 (visual-first)"切换到 “语义优先 (semantic-first)” 的思维方式。利用标准的 Markdown 特性 —— 严格的标题层级、明确的代码块语言标记、描述性的替代文本 —— 来提供一份机器可读的路线图。docmd 通过 LLMs 插件 将这种结构处理为优化后的输出。

实现

1. 严格的标题层级

不要为了视觉效果而跳过标题层级。一致的层级让 LLM 能够理解不同章节的范围与彼此关系。

• # 标题：页面的核心主题。
• ## 主要概念：一个原子化的高级主题。
• ### 细节：具体的子任务或属性。

• ❌ 差：在 # 之后直接使用 ###，只是为了获得较小的字号。
• ✅ 好：# 安装，接着是 ## 前置条件，再接着是 ### 系统要求。

2. 为媒体提供描述性元数据

LLM 无法"看见"图像或图表。请在替代文本或紧邻的段落中提供架构层面的上下文。

![系统架构：前端 React 应用通过 REST 与 Node.js API 通信，Node.js API 再查询 Redis 缓存与 PostgreSQL 数据库。](../../static/img/architecture.png)

3. 显式标记代码块

为每一个带围栏的代码块显式指定语言，以启用 语法高亮。这能让 LLM 正确解析抽象语法树 (AST)。

  "plugins": {
    "llms": {}
  }

4. 使用语义化容器

使用 标注 (Callout) 而非通用的引用块，以表达明确意图。docmd 的语义化容器能帮助 AI 模型区分核心指令与补充性的警告。

取舍

语义严谨要求纪律性。您不能将 Markdown 特性仅作为装饰性元素来使用。然而，这种纪律能让文档对 AI Agent 与使用辅助技术的人类读者都更加友好。