mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
384ee2150b
* docs: fill gaps in recently updated pages * docs: translate gap-fill edits to es, fr, zh * Apply suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
204 lines
7.6 KiB
Plaintext
204 lines
7.6 KiB
Plaintext
---
|
||
title: "使用 Claude Code 编写文档"
|
||
sidebarTitle: "Claude Code"
|
||
description: "通过 CLAUDE.md 项目说明配置 Claude Code，按照你的风格指南撰写、审阅和更新你的 Mintlify 文档。"
|
||
keywords: ["Claude Code", "CLAUDE.md", "AI 文档", "Anthropic", "Claude"]
|
||
---
|
||
|
||
Claude Code 是一款具备智能体能力的命令行工具，能帮助你维护文档。它可以撰写新内容、评审现有页面，并保持文档实时更新。
|
||
|
||
你可以在项目中添加 `CLAUDE.md` 文件，并持续迭代完善，用以训练 Claude Code 理解你的文档规范与工作流程。
|
||
|
||
<div id="getting-started">
|
||
## 快速开始
|
||
</div>
|
||
|
||
**前提条件：**
|
||
|
||
* 有效的 Claude 订阅（Pro、Max 或 API 访问权限）
|
||
|
||
**设置：**
|
||
|
||
1. 安装 Claude Code：
|
||
|
||
```bash
|
||
npm install -g @anthropic-ai/claude-code
|
||
```
|
||
|
||
2. 进入您的文档目录。
|
||
3. （可选）将下面的 `CLAUDE.md` 文件添加到您的项目中。
|
||
4. 运行 `claude` 启动。
|
||
|
||
要确认你的设置是否正常，可向 Claude Code 提问，例如 `Summarize the standards from CLAUDE.md and list the Mintlify components you can use`。正常运行的会话会引用你的 `CLAUDE.md`，并从已加载的 skill 中引用 Mintlify 组件（例如 `Card`、`Steps` 或 `Accordion`）。
|
||
|
||
<div id="claudemd-template">
|
||
## CLAUDE.md 的模板
|
||
</div>
|
||
|
||
在文档目录根目录保存一个 `CLAUDE.md` 文件，帮助 Claude Code 理解你的项目。该文件会基于你的文档标准、偏好和工作流程对 Claude Code 进行训练。更多信息请参阅 Anthropic 文档中的[管理 Claude 的记忆](https://docs.anthropic.com/en/docs/claude-code/memory)。
|
||
|
||
复制此示例模板，或根据你的文档规范进行调整：
|
||
|
||
```mdx
|
||
# Mintlify 文档
|
||
|
||
## 工作关系
|
||
- 你可以对想法提出质疑——这有助于产出更好的文档。在这样做时，请引用资料来源并说明你的理由
|
||
- 务必要求澄清，而不是自行假设
|
||
- 绝不撒谎、猜测或编造任何内容
|
||
|
||
## 项目背景
|
||
- 格式：带有 YAML frontmatter 的 MDX 文件
|
||
- 配置：用于导航、主题、设置的 docs.json
|
||
- 组件：Mintlify 组件
|
||
|
||
## 内容策略
|
||
- 记录恰到好处的内容以确保用户成功——不多不少
|
||
- 优先考虑准确性和可用性
|
||
- 尽可能让内容保持长期有效
|
||
- 在添加任何新内容之前先搜索现有内容。除非出于战略考虑，否则避免重复
|
||
- 检查现有模式以保持一致性
|
||
- 从最小合理的更改开始
|
||
|
||
## docs.json
|
||
|
||
- 在构建 docs.json 文件和站点导航时，请参考 [docs.json 架构](https://mintlify.com/docs.json)
|
||
|
||
## 页面的 frontmatter 要求
|
||
- title：清晰、描述性的页面标题
|
||
- description：用于 SEO（搜索引擎优化）/导航的简洁摘要
|
||
|
||
## 写作规范
|
||
- 使用第二人称（"你"）
|
||
- 在程序性内容开始时列出前提条件
|
||
- 发布前测试所有代码示例
|
||
- 与现有页面的样式和格式保持一致
|
||
- 包含基础和高级用例
|
||
- 为所有代码块添加语言标签
|
||
- 为所有图像添加替代文本
|
||
- 内部链接使用相对路径
|
||
|
||
## Git 工作流程
|
||
- 提交时绝不使用 --no-verify
|
||
- 开始前询问如何处理未提交的更改
|
||
- 当没有明确的 branch 用于更改时创建新 branch
|
||
- 在开发过程中频繁提交
|
||
- 绝不跳过或禁用预提交钩子
|
||
|
||
## 禁止事项
|
||
- 在任何 MDX 文件上跳过 frontmatter
|
||
- 对内部链接使用绝对 URL
|
||
- 包含未经测试的代码示例
|
||
- 自行假设——务必要求澄清
|
||
```
|
||
|
||
|
||
<div id="sample-prompts">
|
||
## 示例提示
|
||
</div>
|
||
|
||
完成 Claude Code 的设置后，试试以下提示，了解它如何协助处理常见的文档任务。你可以直接复制粘贴这些示例，或根据具体需求进行调整。
|
||
|
||
<div id="convert-notes-to-polished-docs">
|
||
### 将笔记转化为完善文档
|
||
</div>
|
||
|
||
把粗略草稿转为包含组件和 frontmatter 的规范 Markdown 页面。
|
||
|
||
**示例提示：**
|
||
|
||
```text wrap
|
||
将此文本转换为格式正确的 MDX 页面：[在此处粘贴您的文本]
|
||
```
|
||
|
||
|
||
<div id="review-docs-for-consistency">
|
||
### 审阅文档的一致性
|
||
</div>
|
||
|
||
获取关于改进样式、格式和组件使用的建议。
|
||
|
||
**示例提示：**
|
||
|
||
```text wrap
|
||
检查 docs/ 中的文件，并针对一致性和清晰度提出改进建议
|
||
```
|
||
|
||
|
||
<div id="update-docs-when-features-change">
|
||
### 功能变更时更新文档
|
||
</div>
|
||
|
||
在产品迭代中保持文档及时更新。
|
||
|
||
**示例：**
|
||
|
||
```text wrap
|
||
我们的 API 现在需要版本参数。请更新文档，在所有示例中包含 version=2024-01
|
||
```
|
||
|
||
|
||
<div id="generate-comprehensive-code-examples">
|
||
### 生成完善的代码示例
|
||
</div>
|
||
|
||
创建包含错误处理的多语言示例。
|
||
|
||
**示例提示：**
|
||
|
||
```text wrap
|
||
为 [你的 API 端点] 创建包含错误处理的 JavaScript、Python 和 cURL 代码示例
|
||
```
|
||
|
||
|
||
<div id="extend-claude-code">
|
||
## 扩展 Claude Code
|
||
</div>
|
||
|
||
除了手动向 Claude Code 提示外，你还可以将其集成到现有的工作流程中。
|
||
|
||
<div id="automate-with-github-actions">
|
||
### 使用 GitHub Actions 进行自动化
|
||
</div>
|
||
|
||
在代码变更时自动运行 Claude Code，保持文档同步更新。你可以在拉取请求 (PR；亦称“合并请求”/Merge Request) 上触发文档审阅，或在 API 发生变化时自动更新示例。
|
||
|
||
<div id="multi-instance-workflows">
|
||
### 多实例工作流
|
||
</div>
|
||
|
||
针对不同任务使用独立的 Claude Code 会话——一个用于撰写新内容，另一个用于审阅与质量保证。这样有助于保持一致性，并发现单一会话可能遗漏的问题。
|
||
|
||
<div id="team-collaboration">
|
||
### 团队协作
|
||
</div>
|
||
|
||
将优化后的 `CLAUDE.md` 文件与团队共享，确保所有贡献者遵循一致的文档标准。团队通常会形成项目特定的提示与工作流程，并将其纳入文档实践中。
|
||
|
||
<div id="custom-commands">
|
||
### 自定义命令
|
||
</div>
|
||
|
||
在 `.claude/commands/` 中创建可复用的斜杠命令，用于你所在项目或团队常见的文档任务。
|
||
|
||
<div id="frequently-asked-questions">
|
||
## 常见问题
|
||
</div>
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="使用 Claude Code 与 Mintlify 是否需要 CLAUDE.md 文件？">
|
||
不需要，但它能显著提升输出质量。如果没有 CLAUDE.md，Claude Code 会基于通用上下文工作，可能无法遵循你的特定风格指南、组件偏好或术语规范。CLAUDE.md 文件可以训练 Claude Code 了解你的项目标准，这样你就不需要在每次提示中重复说明。
|
||
</Accordion>
|
||
|
||
<Accordion title="Claude Code 与 Cursor 或 Devin Desktop 在文档编写方面有什么区别？">
|
||
Claude Code 是一款命令行工具，专为在整个代码仓库范围内执行智能体式、多步骤任务而设计。它非常适合审查所有页面是否缺少替代文本、在每个代码示例中更新参数名称，或检查一组文件的一致性等任务。Cursor 和 Devin Desktop 是基于 IDE 的工具，更适合通过内联建议编辑单个文件。两种方式都可以——正确的选择取决于你的工作是逐个文件还是跨整个仓库。
|
||
</Accordion>
|
||
|
||
<Accordion title="我能否使用 Claude Code 从代码自动生成文档？">
|
||
可以。Claude Code 可以读取你的源代码并生成对应的文档。将其指向一个 API 端点、配置文件或一组函数，让它按照你的 CLAUDE.md 标准生成匹配的文档。请审核和完善输出——自动生成在你将 Claude Code 视为初稿作者而非最终发布者时效果最佳。
|
||
</Accordion>
|
||
|
||
<Accordion title="如何与团队共享我的 CLAUDE.md 配置？">
|
||
将 CLAUDE.md 文件提交到你的文档仓库中。任何克隆该仓库并运行 Claude Code 的人都会自动使用你的项目配置。这使得文档标准在所有贡献者之间保持一致，无需每个人单独设置自己的上下文。
|
||
</Accordion>
|
||
</AccordionGroup> |