Claude Code 文档重构实战用 /doc-refactor 斜杠命令系统化重组项目文档【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto本篇技术指南围绕 Claude Code 的/doc-refactor斜杠命令展开介绍如何依据项目类型库 / API / Web 应用 / CLI / 微服务系统化地重构文档结构。读者将掌握一套从项目分析—文档集中化—README 优化—组件文档—docs/ 分类—专题指南—Mermaid 图表的完整方法论并结合本仓库的源码级配套交叉引用校验、Mermaid 语法校验、i18n 目录、文档插件与模板落地到自己的开源项目中。/doc-refactor是什么/doc-refactor是 Claude Code 的自定义斜杠命令slash command其作用是重新组织refactor项目文档结构使其更清晰、更易检索、更适合 AI Agent 阅读。命令文件以 YAML frontmatter 声明元信息--- name: doc-refactor description: Restructure project documentation for clarity and accessibility ---在 Claude Code 中输入/doc-refactor后Claude 会按文档中的步骤引导你完成整个文档结构梳理。调用方式极简——命令文件位于 doc-refactor.md本仓库的 01-slash-commands/README.md 中把它与其他示例命令/optimize、/pr、/generate-api-docs、/commit、/push-all、/setup-ci-cd、/unit-test-expand并列列出属于可直接安装使用的开箱即用命令集。前置知识从斜杠命令到 Skills 的迁移在真正使用/doc-refactor前需要理解它目前的载体形态。仓库文档明确说明自定义斜杠命令已与 Agent Skills 合并。两种方式都会生成/command-name快捷方式方式存放位置状态Skills推荐.claude/skills/name/SKILL.md当前标准Legacy Commands.claude/commands/name.md仍可使用若同名 skill 与 command 同时存在skill 优先。迁移路径只是移动文件# 之前Command .claude/commands/doc-refactor.md # 之后Skill .claude/skills/doc-refactor/SKILL.mdSkills 相比 legacy 命令的额外能力包括目录结构打包脚本/模板/参考文件、Claude 可按需自动调用、通过context: fork在隔离子代理中执行、以及渐进式披露仅在需要时加载额外文件节省上下文。frontmatter 关键字段可参考 01-slash-commands/README.md 与 03-skills/README.md字段用途默认值name命令名成为/name目录名description简述帮助 Claude 判断何时使用首段正文argument-hint自动补全提示无allowed-tools免许可使用的工具继承disable-model-invocationtrue时仅用户可调用falseuser-invocablefalse时从/菜单隐藏truecontext设为fork在隔离子代理中运行无七步文档重构方法论/doc-refactor的正文将整个重构拆成 7 个可执行步骤每个步骤对应一个明确的文档工程目标1. 分析项目先定类型再定结构重构的起点不是写文档而是识别项目类型库library/ API / Web 应用 / CLI / 微服务同时明确架构形态与用户角色personas。不同项目类型的文档重心完全不同库LibraryAPI 参考、安装与使用示例、迁移指南是核心API 服务端点文档、认证方式、请求/响应示例占主导CLI 工具命令参考、参数表、退出码和交互式示例最关键微服务服务拓扑、契约contract、部署与可观测性文档优先。这一类型驱动的原则与仓库中doc-generatorskill 的思路一致——03-skills/doc-generator/SKILL.md 依据 API 类型输出 OpenAPI 规范、端点文档、SDK 示例、集成指南与认证指南而不是套用同一套模板。2. 集中管理文档统一收拢到docs/把散落在代码库各处的技术文档迁移到统一的docs/目录同时保留正确的交叉引用。集中化带来三个收益读者有唯一入口、搜索引擎与 Agent 可按固定路径发现内容、后续文档质量工具如链接校验只需扫描单个根目录。本仓库自身就是docs/ 集中化的例证根级 docs/ 下集中存放ROADMAP-20260401.md与TASKS-20260401.md同时在根级以01-slash-commands/到10-cli/十个编号目录组织分册指南每册内含自己的README.md作为章节入口目录级 README 与docs/形成总—分两级结构。3. 精简根 README.md把它做成入口页根目录README.md应当被精简为单一路径的入口页包含概览overview项目是什么、解决什么问题快速开始quickstart从克隆到第一次成功运行的若干步骤模块 / 组件摘要各模块一句话职责说明与链接许可证license与联系方式contacts。对照本仓库根 README.md它以 Master Claude Code in a Weekend 总起随后是 Table of Contents、问题陈述、学习方法、15 分钟快速上手克隆 → 复制命令 → 在 Claude Code 中输入/optimize并用一张大表给出各模块摘要——例如 Slash Commands15 minProject memory15 min每个条目链接到对应分册目录。这正是入口页而非文档全集的写法。4. 组件级文档为每个模块补 README在模块/包/服务层级添加各自的 README包含**配置setup与测试testing**说明让开发者无需阅读整库就能上手单个组件。本仓库第 03 分册把该思路贯彻到每个 skill03-skills/doc-generator/ —— SKILL.md generate-docs.py03-skills/refactor/ —— SKILL.md references/code-smells、refactoring-catalogscripts/analyze-complexity.py、detect-smells.pytemplates/refactoring-plan.md03-skills/code-review-specialist/ —— SKILL.md scripts templates。组件文档与核心代码同目录存放更新时代码与文档一起改避免了集中式文档库常见的滞后问题。5. 按主题组织docs/子目录docs/内部按主题划分命令给出的默认分类是架构Architecture、API Reference、数据库Database、设计Design、故障排查Troubleshooting、部署Deployment、贡献Contributing并明确根据项目需要调整——分类应服务于真实内容而不是机械照搬。围绕这一环节仓库提供了可直接落地的文档资产文档插件 07-plugins/documentation/README.md提供/generate-api-docs、/generate-readme、/sync-docs、/validate-docs四个命令以及api-documenter、code-commentator、example-generator三个子代理/sync-docs的流程检测代码变更 → 定位过期文档 → 更新受影响的文档 → 验证示例可用 → 更新版本号恰好覆盖重构后的长期维护期模板目录 07-plugins/documentation/templates/api-endpoint.mdREST 端点模板含 Path/Query 参数表、请求体、200/400/404 响应、cURL/JavaScript/Python 示例与限流说明、function-docs.md函数级文档、adr-template.md架构决策记录 ADR——正好用于Architecture分类。6. 按需创建四类专题指南命令将指南划分为四类要求按适用的选择而非全部生成指南受众与内容User Guide用户指南面向应用最终用户的操作文档API 文档端点endpoints、认证authentication、示例Development Guide开发指南环境搭建、测试、贡献流程Deployment Guide部署指南面向服务/应用的生产部署API 文档的生成可以交给配套的/generate-api-docs命令完成——generate-api-docs.md 给出了可复制的流程扫描/src/api/→ 提取函数签名与 JSDoc → 按端点/模块组织 → 生成带示例的 Markdown → 加入请求/响应 schema 与错误文档输出到docs/api.md。7. 所有图表统一使用 Mermaid第 7 步是一条硬性规范所有图表架构图、流程图、schema 图都用 Mermaid 编写。理由在于 Markdown 生态对 Mermaid 的原生支持——GitHub/GitCode 可直接渲染且图表文本化后利于 diff 审阅与 Agent 理解。本仓库用 Mermaid 的地方即是范本01-slash-commands/README.md 中同时给出命令架构的graph TD流程图与命令生命周期的sequenceDiagram时序图。值得注意的是Mermaid 不是写完就不管——仓库的 check_mermaid.py 脚本会扫描所有*.md文件中的 bash作为 Skill 安装推荐克隆本仓库后执行mkdir -p .claude/skills/doc-refactor cp 01-slash-commands/doc-refactor.md .claude/skills/doc-refactor/SKILL.md或作为 legacy command 安装mkdir -p .claude/commands cp 01-slash-commands/doc-refactor.md .claude/commands/个人级使用mkdir -p ~/.claude/commands cp 01-slash-commands/doc-refactor.md ~/.claude/commands/安装后在 Claude Code 中键入 /doc-refactor 即可启动重构会话。若要把本仓库其他文档工具一并带入可复制整套 [01-slash-commands](https://link.gitcode.com/i/e7f56830b438e3737a23ba3eb0818f88) 目录含 /pr、/setup-ci-cd 等或安装文档插件/plugin install documentation。 ## 最佳实践清单与故障排查 命令结尾强调文档要**简洁concise、易扫读scannable、与项目类型上下文一致contextual to project type**。可总结为以下 checklist - **以类型定结构**先回答这是什么项目、读者是谁再决定目录与模板 - **单一事实来源**技术文档集中到 docs/根 README 只做入口避免多处维护同一事实 - **文档紧跟代码**模块 README 与代码同目录模板统一由 templates/ 提供保证一致性 - **先可用再完善**四类指南按需生成不空转 - **图与校验皆自动化**一律 Mermaid并挂接 check_cross_references.py / check_mermaid.py 防止链接与图表腐化。 若执行命令后未生效按 [01-slash-commands/README.md](https://link.gitcode.com/i/4c27ceef1bf4b4053ccc04526b396877) 的排查路径处理确认文件位于 .claude/skills/name/SKILL.md 或 .claude/commands/name.md核对 frontmatter 的 name 字段重启 Claude Code 会话用 /help 查看已注册命令同名 skill/command 冲突时删除其一——**skill 永远优先**。 --- **文档定位**本指南聚焦 [uk/01-slash-commands/doc-refactor.md](https://link.gitcode.com/i/3f72f62c12890b6feaa986f1bdd7daf4) 中的 /doc-refactor 命令英文版见 [01-slash-commands/doc-refactor.md](https://link.gitcode.com/i/62ca5f507ffce2af4818fd6a84b1f715)中文版见 [zh/01-slash-commands/doc-refactor.md](https://link.gitcode.com/i/82d26eba59be970cc8211a377e30a499)。想深入了解相邻能力可继续阅读仓库的 [Skills 分册](https://link.gitcode.com/i/cd082ad8474f6a8df16afcf714b17126)、[Memory 分册](https://link.gitcode.com/i/37ee08dfd68b7c029eabacc6dbf8788e) 与 [Plugins 分册](https://link.gitcode.com/i/476aae31e891df8dc97c8cd803529ca3)。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Claude Code 文档重构实战用 /doc-refactor 斜杠命令系统化重组项目文档【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto本篇技术指南围绕 Claude Code 的/doc-refactor斜杠命令展开介绍如何依据项目类型库 / API / Web 应用 / CLI / 微服务系统化地重构文档结构。读者将掌握一套从项目分析—文档集中化—README 优化—组件文档—docs/ 分类—专题指南—Mermaid 图表的完整方法论并结合本仓库的源码级配套交叉引用校验、Mermaid 语法校验、i18n 目录、文档插件与模板落地到自己的开源项目中。/doc-refactor是什么/doc-refactor是 Claude Code 的自定义斜杠命令slash command其作用是重新组织refactor项目文档结构使其更清晰、更易检索、更适合 AI Agent 阅读。命令文件以 YAML frontmatter 声明元信息--- name: doc-refactor description: Restructure project documentation for clarity and accessibility ---在 Claude Code 中输入/doc-refactor后Claude 会按文档中的步骤引导你完成整个文档结构梳理。调用方式极简——命令文件位于 doc-refactor.md本仓库的 01-slash-commands/README.md 中把它与其他示例命令/optimize、/pr、/generate-api-docs、/commit、/push-all、/setup-ci-cd、/unit-test-expand并列列出属于可直接安装使用的开箱即用命令集。前置知识从斜杠命令到 Skills 的迁移在真正使用/doc-refactor前需要理解它目前的载体形态。仓库文档明确说明自定义斜杠命令已与 Agent Skills 合并。两种方式都会生成/command-name快捷方式方式存放位置状态Skills推荐.claude/skills/name/SKILL.md当前标准Legacy Commands.claude/commands/name.md仍可使用若同名 skill 与 command 同时存在skill 优先。迁移路径只是移动文件# 之前Command .claude/commands/doc-refactor.md # 之后Skill .claude/skills/doc-refactor/SKILL.mdSkills 相比 legacy 命令的额外能力包括目录结构打包脚本/模板/参考文件、Claude 可按需自动调用、通过context: fork在隔离子代理中执行、以及渐进式披露仅在需要时加载额外文件节省上下文。frontmatter 关键字段可参考 01-slash-commands/README.md 与 03-skills/README.md字段用途默认值name命令名成为/name目录名description简述帮助 Claude 判断何时使用首段正文argument-hint自动补全提示无allowed-tools免许可使用的工具继承disable-model-invocationtrue时仅用户可调用falseuser-invocablefalse时从/菜单隐藏truecontext设为fork在隔离子代理中运行无七步文档重构方法论/doc-refactor的正文将整个重构拆成 7 个可执行步骤每个步骤对应一个明确的文档工程目标1. 分析项目先定类型再定结构重构的起点不是写文档而是识别项目类型库library/ API / Web 应用 / CLI / 微服务同时明确架构形态与用户角色personas。不同项目类型的文档重心完全不同库LibraryAPI 参考、安装与使用示例、迁移指南是核心API 服务端点文档、认证方式、请求/响应示例占主导CLI 工具命令参考、参数表、退出码和交互式示例最关键微服务服务拓扑、契约contract、部署与可观测性文档优先。这一类型驱动的原则与仓库中doc-generatorskill 的思路一致——03-skills/doc-generator/SKILL.md 依据 API 类型输出 OpenAPI 规范、端点文档、SDK 示例、集成指南与认证指南而不是套用同一套模板。2. 集中管理文档统一收拢到docs/把散落在代码库各处的技术文档迁移到统一的docs/目录同时保留正确的交叉引用。集中化带来三个收益读者有唯一入口、搜索引擎与 Agent 可按固定路径发现内容、后续文档质量工具如链接校验只需扫描单个根目录。本仓库自身就是docs/ 集中化的例证根级 docs/ 下集中存放ROADMAP-20260401.md与TASKS-20260401.md同时在根级以01-slash-commands/到10-cli/十个编号目录组织分册指南每册内含自己的README.md作为章节入口目录级 README 与docs/形成总—分两级结构。3. 精简根 README.md把它做成入口页根目录README.md应当被精简为单一路径的入口页包含概览overview项目是什么、解决什么问题快速开始quickstart从克隆到第一次成功运行的若干步骤模块 / 组件摘要各模块一句话职责说明与链接许可证license与联系方式contacts。对照本仓库根 README.md它以 Master Claude Code in a Weekend 总起随后是 Table of Contents、问题陈述、学习方法、15 分钟快速上手克隆 → 复制命令 → 在 Claude Code 中输入/optimize并用一张大表给出各模块摘要——例如 Slash Commands15 minProject memory15 min每个条目链接到对应分册目录。这正是入口页而非文档全集的写法。4. 组件级文档为每个模块补 README在模块/包/服务层级添加各自的 README包含**配置setup与测试testing**说明让开发者无需阅读整库就能上手单个组件。本仓库第 03 分册把该思路贯彻到每个 skill03-skills/doc-generator/ —— SKILL.md generate-docs.py03-skills/refactor/ —— SKILL.md references/code-smells、refactoring-catalogscripts/analyze-complexity.py、detect-smells.pytemplates/refactoring-plan.md03-skills/code-review-specialist/ —— SKILL.md scripts templates。组件文档与核心代码同目录存放更新时代码与文档一起改避免了集中式文档库常见的滞后问题。5. 按主题组织docs/子目录docs/内部按主题划分命令给出的默认分类是架构Architecture、API Reference、数据库Database、设计Design、故障排查Troubleshooting、部署Deployment、贡献Contributing并明确根据项目需要调整——分类应服务于真实内容而不是机械照搬。围绕这一环节仓库提供了可直接落地的文档资产文档插件 07-plugins/documentation/README.md提供/generate-api-docs、/generate-readme、/sync-docs、/validate-docs四个命令以及api-documenter、code-commentator、example-generator三个子代理/sync-docs的流程检测代码变更 → 定位过期文档 → 更新受影响的文档 → 验证示例可用 → 更新版本号恰好覆盖重构后的长期维护期模板目录 07-plugins/documentation/templates/api-endpoint.mdREST 端点模板含 Path/Query 参数表、请求体、200/400/404 响应、cURL/JavaScript/Python 示例与限流说明、function-docs.md函数级文档、adr-template.md架构决策记录 ADR——正好用于Architecture分类。6. 按需创建四类专题指南命令将指南划分为四类要求按适用的选择而非全部生成指南受众与内容User Guide用户指南面向应用最终用户的操作文档API 文档端点endpoints、认证authentication、示例Development Guide开发指南环境搭建、测试、贡献流程Deployment Guide部署指南面向服务/应用的生产部署API 文档的生成可以交给配套的/generate-api-docs命令完成——generate-api-docs.md 给出了可复制的流程扫描/src/api/→ 提取函数签名与 JSDoc → 按端点/模块组织 → 生成带示例的 Markdown → 加入请求/响应 schema 与错误文档输出到docs/api.md。7. 所有图表统一使用 Mermaid第 7 步是一条硬性规范所有图表架构图、流程图、schema 图都用 Mermaid 编写。理由在于 Markdown 生态对 Mermaid 的原生支持——GitHub/GitCode 可直接渲染且图表文本化后利于 diff 审阅与 Agent 理解。本仓库用 Mermaid 的地方即是范本01-slash-commands/README.md 中同时给出命令架构的graph TD流程图与命令生命周期的sequenceDiagram时序图。值得注意的是Mermaid 不是写完就不管——仓库的 check_mermaid.py 脚本会扫描所有*.md文件中的 bash作为 Skill 安装推荐克隆本仓库后执行mkdir -p .claude/skills/doc-refactor cp 01-slash-commands/doc-refactor.md .claude/skills/doc-refactor/SKILL.md或作为 legacy command 安装mkdir -p .claude/commands cp 01-slash-commands/doc-refactor.md .claude/commands/个人级使用mkdir -p ~/.claude/commands cp 01-slash-commands/doc-refactor.md ~/.claude/commands/安装后在 Claude Code 中键入 /doc-refactor 即可启动重构会话。若要把本仓库其他文档工具一并带入可复制整套 [01-slash-commands](https://link.gitcode.com/i/e7f56830b438e3737a23ba3eb0818f88) 目录含 /pr、/setup-ci-cd 等或安装文档插件/plugin install documentation。 ## 最佳实践清单与故障排查 命令结尾强调文档要**简洁concise、易扫读scannable、与项目类型上下文一致contextual to project type**。可总结为以下 checklist - **以类型定结构**先回答这是什么项目、读者是谁再决定目录与模板 - **单一事实来源**技术文档集中到 docs/根 README 只做入口避免多处维护同一事实 - **文档紧跟代码**模块 README 与代码同目录模板统一由 templates/ 提供保证一致性 - **先可用再完善**四类指南按需生成不空转 - **图与校验皆自动化**一律 Mermaid并挂接 check_cross_references.py / check_mermaid.py 防止链接与图表腐化。 若执行命令后未生效按 [01-slash-commands/README.md](https://link.gitcode.com/i/4c27ceef1bf4b4053ccc04526b396877) 的排查路径处理确认文件位于 .claude/skills/name/SKILL.md 或 .claude/commands/name.md核对 frontmatter 的 name 字段重启 Claude Code 会话用 /help 查看已注册命令同名 skill/command 冲突时删除其一——**skill 永远优先**。 --- **文档定位**本指南聚焦 [uk/01-slash-commands/doc-refactor.md](https://link.gitcode.com/i/3f72f62c12890b6feaa986f1bdd7daf4) 中的 /doc-refactor 命令英文版见 [01-slash-commands/doc-refactor.md](https://link.gitcode.com/i/62ca5f507ffce2af4818fd6a84b1f715)中文版见 [zh/01-slash-commands/doc-refactor.md](https://link.gitcode.com/i/82d26eba59be970cc8211a377e30a499)。想深入了解相邻能力可继续阅读仓库的 [Skills 分册](https://link.gitcode.com/i/cd082ad8474f6a8df16afcf714b17126)、[Memory 分册](https://link.gitcode.com/i/37ee08dfd68b7c029eabacc6dbf8788e) 与 [Plugins 分册](https://link.gitcode.com/i/476aae31e891df8dc97c8cd803529ca3)。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
