使用 AI 编写
了解如何借助 Claude Code、Cursor 和 Codex 等 AI 工具编写和审阅文档，包括提示模式与常见 MDX 错误
这些策略适用于任何 AI 工具，包括 Claude Code、Cursor、Codex 和 Copilot。如需了解特定工具的设置，请参阅 Claude Code、Cursor 或 Codex。
MDX 为什么适合 AI
MDX 是 AI 工具最容易编写的格式之一：
- 语法熟悉：AI 模型训练于数百万个 Markdown 文件，几乎无需提示即可生成有效的 MDX。
- 组件结构化：
<Card>、<Steps>和<Tabs>的模式可预测，模型能很快学会。 - 纯文本：MDX 不包含 AI 工具需要解释的二进制格式、专有模式或构建产物。
编写更好的提示词
提示词通常是区分平庸 AI 文档与优质文档的关键。请明确说明你想要什么。
Write docs for the webhook feature.Document authentication.Create a getting started guide.这些提示只会产出泛泛而臃肿的内容，因为 AI 没有任何约束。
有效的提示词模式
| 模式 | 示例 |
|---|---|
| 指定读者 | "The reader is a backend developer who has never used our API" |
| 指定结构 | "Use Steps for the setup flow, then Tabs for language variants" |
| 设定长度限制 | "Keep the intro under 2 sentences" 或 "Each accordion answer should be 3-4 lines" |
| 指向源代码 | "Reference the implementation in /src/auth for accuracy" |
| 说明跳过什么 | "Don't explain what REST is. Skip the theory." |
| 提供示例页面 | "Match the tone and structure of /cn/quickstart" |
审核 AI 输出
AI 工具大多数时候能生成结构正确的 MDX。更隐蔽的问题在于语气、准确性和冗余。提交前请逐项检查以下清单。
语气检查
大声朗读输出内容。如果听起来像聊天机器人，请重写。注意以下几点：
- 填充性短语："It's important to note that"、"This allows you to"、"In order to"
- 模糊措辞："You might want to consider"、"It's generally recommended"
- 空洞的过渡："Now that we've covered X, let's move on to Y"
- 流行词："seamlessly"、"robust"、"leverage"、"streamline"
删掉这些内容。
准确性检查
AI 工具会自信地输出错误信息。请核实：
- 代码示例能否真正运行？复制粘贴并执行。
- 配置项是否真实？对照源代码检查。
- 组件名称是否正确？只使用确实存在的组件。
- 页面描述的是当前行为，而不是设想中的功能？
结构检查
- Frontmatter 同时包含
title和description - 开头段落位于任何标题之前
- 页面以
<Columns>包裹的 "What's Next?" 卡片结尾 - 新页面已添加到
docs.json导航中 - 没有虚构的组件；只使用组件参考中的组件
常见 AI 错误
AI 工具会生成 <CodeBlock>、<Alert>、<Section>、<Callout> 等 Jamdesk 中并不存在的组件。请只使用概览中列出的组件。
创建页面后未将其添加到 docs.json，是最常见的错误。页面存在，但不会出现在侧边栏中。请将每个新页面都添加到导航中。
AI 工具喜欢把每隔一段落都包进 <Note> 或 <Warning> 中。每页一两个提示框就足够了。
AI 生成的 200 行页面，通常只有约 100 行是实际内容。注意重复的解释、不必要的背景介绍，以及用不同措辞表达同一意思的段落。请大胆删减。
"This powerful feature allows you to..." 对读者毫无帮助。应直接说明它做什么："在事件触发时向你的端点发送 HTTP POST 请求。"
保持文档同步
编写文档是容易的部分。在代码变更时保持文档更新则更难。
发布一项功能后，向你的 AI 工具发出提示：
I just added [feature]. Update the docs to reflect this change.
Reference the implementation in /src/[file] for accuracy.页面骨架
请求 AI 创建新页面时，可将以下内容作为起始提示：
创建 Jamdesk 文档页面
上方卡片复制了完整的说明与骨架。若要在你自己的页面中添加同一组件，可使用以下源代码：
<Prompt title="Create a Jamdesk documentation page" actions={["cursor", "claude", "chatgpt"]}>
Create a Jamdesk documentation page using this structure. Replace each
placeholder with specific, accurate content for the feature I describe.
```mdx
---
title: Feature Name
description: One sentence summarizing what this page covers.
---
Opening paragraph: what problem this solves and who should read this.
## Quick Start
<Steps>
<Step title="First step">What to do.</Step>
<Step title="Second step">What to do next.</Step>
</Steps>
## How It Works
Explain the mechanics. Use code examples.
## What's Next?
<Columns cols={2}>
<Card title="Related Page" icon="arrow-right" href="/path">
Why the reader would go here next
</Card>
</Columns>
```
</Prompt>