技术文档生成

何时使用

• 用户说"给这个项目写 README""补一下文档";
• 新模块没有使用说明;
• API 改了但文档没更新;
• 需要架构说明、部署文档、FAQ。

使用步骤

第 1 步:阅读真实代码

写文档前必须先读代码,禁止凭猜测写:

1. 项目结构与入口文件;
2. 依赖与配置(package.json、pyproject.toml、requirements.txt、环境变量);
3. 核心功能与调用链;
4. 已有文档和注释。

第 2 步:确定文档类型与结构

README(项目首页):

# 项目名

> 一句话定位

## 功能特性
## 快速开始(安装 → 配置 → 运行)
## 使用示例
## 配置说明
## 常见问题(FAQ)
## 目录结构
## License

API 文档:

## 接口名
- 方法:GET /api/users/:id
- 认证:需要 Bearer Token
- 参数:表格(id、类型、必填、说明)
- 响应:成功/失败示例
- 错误码:表格

架构说明:

## 模块划分与职责
## 数据流(请求如何流转)
## 关键设计决策与理由
## 部署与运维

第 3 步:验证每个示例

• 命令、代码示例必须实际运行验证,不验证的不写;
• 环境变量、端口、路径必须与真实项目一致;
• 截图类素材标注生成方式。

第 4 步:输出文档

• 默认中文;如项目面向海外,可同时提供英文版;
• 标题、关键词做 SEO 优化(如"Claude Code 技能安装""中文 Agent 技能库");
• 标注最后验证时间。
• 写完用 doc_checker.py 自查坏链接和结构问题(见下面的辅助脚本),再人工走查。

输入与输出

• 输入:代码库路径 + 文档类型;
• 输出:对应结构的中文技术文档。

示例

用户输入: "给这个仓库写个 README。"

快速开始节选(验证过):

## 快速开始

要求:Node.js 18+

1. 安装依赖:
   npm install
2. 配置环境变量:
   cp .env.example .env
3. 启动开发服务:
   npm run dev
4. 打开 http://localhost:3000

参考

README、快速开始、API 文档、架构文档的结构模板和质量自查清单见 references/DOC_TEMPLATES.md。

辅助脚本

scripts/doc_checker.py 检查文档的结构问题:相对链接指向的文件是否存在、代码围栏是否配对、有无占位符和空章节,可按 --require 指定必需章节:

# 检查 README,要求三个必需章节
python skills/tech-doc-writer/scripts/doc_checker.py README.md --require 快速开始 使用示例 License

脚本只做标记,结论需要人确认;示例能不能跑通由人验证。

注意事项

• 先读代码,再写文档;禁止编造不存在的参数或命令;
• 每个示例都要能跑通,标注"已验证";
• 文档用用户视角:先回答"怎么用",再讲"怎么实现";
• 常用错误与坑(如端口冲突、依赖版本)写进 FAQ;
• 变更代码后提醒用户文档同步更新。

不适用场景

• 用户没有提供代码,要求凭空写文档;
• 纯营销文案(用其他方式);
• 写学术论文或正式出版物。

验证方式

1. 触发:"写 README""补文档";
2. 跑脚本:python skills/tech-doc-writer/scripts/doc_checker.py <文档> --require <必需章节>,无"必须"级问题;
3. 检查:文档基于真实代码,所有命令示例可运行;
4. 走查:按快速开始步骤执行一遍,确认能复现。