AI Agent生成Markdown文档时建议多用图表

背景

在利用 AI Agent 自动生成 Markdown 文档的过程中，一个普遍存在的痛点是：模型倾向于使用纯文本进行叙述，而缺乏主动使用图表的意愿。这种“重文字、轻视觉”的输出方式，在处理复杂业务流程、系统架构或项目进度时，往往导致文档的可读性大幅下降，增加了读者的认知负荷。

LINUX DO 社区的一位用户分享了一个针对性的 Prompt 策略，旨在纠正这一偏差。该策略的核心思想是“视觉优先”（Visual Documentation First），主张通过引入“代码即图表”（Diagram-as-Code）技术，将抽象的逻辑可视化，从而显著提升文档的叙事效率和用户体验。

核心内容

该 Prompt 策略的核心原则是“展示而非仅仅告知”（Show, don't just tell），旨在通过可视化的手段降低读者的认知负担。具体实施建议包含以下四个维度：

1. 图表优于文本 当解释流程、架构或依赖关系所需的文字描述超过三段时，应优先选择绘制图表。这一规则强制 AI 在面临复杂逻辑时，从线性文本转向结构化视觉表达。

2. 选择合适的工具 根据图表的类型和复杂度，推荐选用不同的“代码即图表”工具：

   • Mermaid：作为默认选项，适用于流程图、时序图以及简单的状态机。
   • D2：适用于高层级的系统架构设计和现代化的网络拓扑结构。
   • PlantUML：适用于严格的 UML 图表以及 C4 模型。
   • Dot：适用于密集的依赖树或代码级别的调用图。

3. 渐进式披露（Progressive Disclosure） 在展示复杂系统时，应遵循“先宏观、后微观”的原则。如果单个图表变得过于庞大且杂乱（即所谓的“蜘蛛网”效应），应当将其拆分为一个高层级的总览图加上若干个针对性的子图，以保持信息的清晰度和可读性。

4. 锚定现实（Anchor to Reality） 图表中的抽象概念必须与实际代码或数据实体建立映射。例如，在图表周围或直接标注具体的代码文件路径（如 src/router.ts）或数据库表名（如 users），从而将视觉模型与实际的代码工件紧密关联，增强文档的工程实用性。

关键要点

• 认知减负：纯文本在描述复杂逻辑时效率低下，图表能显著降低读者的理解门槛。
• 工具匹配：没有万能图表工具，需根据场景（流程、架构、UML、依赖）精准选择 Mermaid、D2、PlantUML 或 Dot。
• 结构优化：避免单图过载，采用“总-分”结构进行渐进式信息展示。
• 虚实结合：图表不能脱离代码现实，必须标注具体的代码文件或数据表，确保文档的可追溯性和落地性。

意义与影响

这一 Prompt 策略对 AI 辅助技术写作具有显著的指导意义：

1. 提升技术文档质量：通过强制引入可视化元素，解决了 AI 生成文档“枯燥、难懂”的固有缺陷，使技术文档更符合人类阅读习惯。
2. 标准化图表生成：明确了不同场景下的图表工具选择标准，有助于团队在 AI 辅助开发中建立统一的文档规范。
3. 增强文档的工程价值：强调图表与代码实体的映射，使得生成的文档不仅是“说明”，更是可执行的、与代码库紧密关联的“资产”，提升了文档在长期维护中的实用性。