什么时候使用
-
创建新的技术指南文档
-
编辑现有文档使其符合写作规范
-
审校文档格式和结构
执行流程
-
Step 1: 严格遵循基本要求、文档结构要求、内容结构以及示例要求
-
Step 2: 完成初稿后进行自我审校
-
Step 2.1: 通过 web fetch 最新的相关信息验证内容准确性和时效性
-
Step 2.2: 检查内容是否遵循写作规范
-
Step 2.3: 检查内容逻辑是否清晰，是否易于理解
-
Step 3: 根据审校建议修改内容，然后执行 Step 2 重新审校，直到审校问题修复
-
Step 4: 执行格式化脚本：npm run format
基本要求
-
使用简体中文编写
-
代码示例简洁，聚焦核心概念
-
使用清晰的标题和子标题组织内容
-
包含实际应用场景的实用示例
文档结构
标题命名
使用「主题 + 完全指南/使用指南」格式：
Git Hooks 完全指南
TypeScript 使用指南
章节编号
层级 格式 示例
一级章节 数字编号
1. 概述
二级章节 点号分隔
1.1 什么是 XX
三级章节 点号分隔
1.1.1 详细说明
结尾部分
-
总结章节：回顾核心要点，可包含速查表
-
参考资源章节：提供官方文档和相关资源链接
不使用的元素
-
不使用目录
-
不使用章节分隔线（--- ）
内容格式
表格
大量使用 markdown 表格进行对比说明、参数说明、速查总结。
图解
-
简单图解：优先使用 ASCII 艺术（Git 分支图、流程图）
-
复杂图形：使用 Mermaid 语法（类图、时序图、流程图）
代码块
// ✅ 好的实践：简洁、有中文注释
function greet(name) {
return Hello, ${name};
}
// ❌ 坏的实践：冗长、无注释
要点：
-
标注语言类型（bash, json, javascript 等）
-
如果需要支持 json 注释，使用 jsonc
-
只包含必要的关键代码
-
使用中文注释说明关键步骤
-
使用 // ✅ 和 // ❌ 标记好/坏实践
嵌套代码块
当需要在文档中展示包含代码块的 Markdown 示例时，外层使用 4 个反引号，内层使用 3 个反引号：
## 示例标题
```bash
python scripts/example.py
```
注意：嵌套代码块的开头和结尾反引号数量必须一致，否则会导致渲染错误。
提示信息
使用引用块格式：
注意：重要警告或注意事项
提示：有用的建议
说明：补充说明信息
对比说明
使用 ✅ 和 ❌ 标记好/坏实践，可在正文或代码注释中使用。
FAQ（可选，QA可以加深技术理解）
Q1: 问题内容？
解答段落或代码示例...
问题聚焦于技术实现、常见错误排查、配置疑难等技术内容（和当前的技术主题相关联）。
速查表
在总结章节提供表格形式的快速参考。
示例规范
-
提供完整可运行的代码示例
-
包含多个实际应用场景（场景1、场景2...）
-
代码示例中使用中文注释说明关键步骤
-
复杂操作提供分步骤说明（1. 2. 3.）