尧图网页设计 
ruflo SPARC docs-writer 模式实战在 Claude Code / claude-flow 中落地规范化的 Markdown 技术文档写作【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflorufloclaude-flow是一个部署智能多智能体 swarm、协调自主工作流的 agent meta-harness而 SPARCSpecification、Planning、Architecture、Review、Code是其内置的一套包含多个专业化模式的开发方法论。docs-writer正是这套体系中专司文档产出的模式它把“写文档”从自由发挥变成一套有边界、有工具约束、可被编排器orchestrator委派、且能与持久化记忆打通的标准化能力。读完本文你将掌握如何在 ruflo 项目中通过 MCP 工具、npx CLI 或本地安装三种方式启动 docs-writer 模式理解其角色约束、文件安全边界与记忆集成方式并借助仓库源码佐证其在 SPARC 全流程中的真实定位与调用关系。一、docs-writer 在 ruflo SPARC 体系中的定位在仓库根目录的.claude/commands/sparc/sparc-modes.md中SPARC 被明确描述为Specification, Planning, Architecture, Review, Code五步方法论并围绕它提供了多组专业化模式核心编排orchestrator、swarm-coordinator、workflow-manager、batch-executor、开发coder、architect、reviewer、tdd、分析研究researcher、analyzer、optimizer以及创意支持类designer、innovator、documenter、debugger、tester、memory-manager。docs-writer 与上述模式是平行关系但定位更聚焦它专门负责usage用法、integration集成、setup安装配置、configuration配置四类 Markdown 文档的撰写。它与 documenter 模式的分工可以理解为documenter 强调“带批量文件操作的文档化”而 docs-writer 强调“单点、模块化、可被编排委派的文档写作子任务”。更有说服力的调用证据来自 SPARC orchestrator 的定义文件.claude/commands/sparc/sparc.md其中明确将docs-writer列入 orchestrator 通过new_task可委派的子任务清单与spec-pseudocode、architect、code、tdd、debug、security-review等模式并列。也就是说在一个完整的 SPARC 交付流水线如“认证系统编排”中docs-writer 通常作为收尾阶段的文档化环节被调度而不是独立于流程之外的写手。配套地仓库.claude/commands/sparc/sparc-modes.md还给出了模式级 swarm 协同示例如mcp__claude-flow__swarm_init初始化 hierarchical 拓扑、spawn专门 agent、swarm_monitor监控执行docs-writer 同样可以在这些 swarm 拓扑中作为一个被 spawn 的 worker 参与大规模文档任务。二、角色定义与自定义指令文档写手的“行为契约”docs-writer 模式的核心定义位于.claude/commands/sparc/docs-writer.md其 frontmatter 声明name: sparc-docs-writerdescription: Documentation Writer - You write concise, clear, and modular Markdown documentation that explains usage, integration, setup, and configuration2.1 角色定义Role DefinitionYou write concise, clear, and modular Markdown documentation that explains usage, integration, setup, and configuration.这一句话定义了 docs-writer 的输出品味标准conciseness简洁、clarity清晰、modularity模块化而取材范围被严格限定在 usage / integration / setup / configuration 四类技术文档而非泛泛的营销文案或散文。2.2 自定义指令四条硬性约束自定义指令Custom Instructions给出了可执行的行为规则原文逐条如下每条都对应一种可被校验的输出保障Only work in .md files.——工作范围锁定 Markdown这是与其他代码类模式最本质的区别Use sections, examples, and headings.——输出必须结构化分节、给示例、用标题层级组织Keep each file under 500 lines.——单文件行数红线500 行防止文档膨胀为不可维护的巨块Do not leak env values.——禁止泄露环境变量值属于安全红线与技术文档写作直接相关Summarize what you wrote usingattempt_completion.——任务收尾必须通过attempt_completion汇报保证子任务在 Agent 编排中有明确的完成信号Delegate large guides withnew_task.——遇到大型指南时要用new_task拆分为子任务委派而非在一个回合内硬写到底。这组约束与该项目 agent 体系的设计理念一致每一份文档任务都要求模块化、可测试、有完成态。从仓库.claude/commands/sparc/sparc.md末尾的 Validate 清单✅ Files 500 lines、✅ No hard-coded env vars、✅ Modular, testable outputs、✅ All subtasks end with attempt_completion可以看到docs-writer 的约束并不是孤例而是整个 SPARC 交付链共享的质量闸门。2.3 可用工具Available Tools该模式被刻意限制了工具面只有两个read文件读取与查看用于先理解待文档化的源码或现有文档edit仅允许编辑 Markdown 文件匹配规则\.md$这是防止文档模式误改代码文件的护栏。这种“只能读、只能写 .md”的窄工具面从实现上保证了 docs-writer 即使被并行 spawn 进 swarm也不会触碰源代码文件符合最小权限原则。三、三种激活方式从 MCP 到裸终端docs-writer 的激活方式与 SPARC 家族保持一致原文提供了三种途径优先级从高到低排列。3.1 Option 1MCP 工具Claude Code 中首选mcp__claude-flow__sparc_mode { mode: docs-writer, task_description: create API documentation, options: { namespace: docs-writer, non_interactive: false } }参数说明mode固定为docs-writerMCP 服务器据此路由到对应模式的系统提示词与工具白名单task_description任务描述例如create API documentation是驱动整轮文档产出的输入options.namespace命名空间通常设为与模式同名docs-writer用于让记忆与模式上下文相互隔离options.non_interactive交互开关false表示允许在关键节点与用户确认适合需要澄清需求的文档任务批量/无人值守场景可置true。3.2 Option 2npx CLIMCP 不可用时的回退# Use when running from terminal or MCP tools unavailable npx claude-flow sparc run docs-writer create API documentation # For alpha features npx claude-flowalpha sparc run docs-writer create API documentation # With namespace npx claude-flow sparc run docs-writer your task --namespace docs-writer # Non-interactive mode npx claude-flow sparc run docs-writer your task --non-interactive要点拆解sparc run mode task是 SPARC 模式的统一 CLI 入口docs-writer 只是mode的一个取值希望使用 alpha 通道时切换到npx claude-flowalpha--namespace docs-writer使该次运行的模式状态/记忆写入独立命名空间避免与其他模式coder、architect 等的状态串扰--non-interactive适合 CI、脚本或 swarm 批量文档生成场景杜绝终端等待输入导致的挂起。3.3 Option 3本地安装# If claude-flow is installed locally ./claude-flow sparc run docs-writer create API documentation适用于已在仓库本地安装 claude-flow而非依赖 npx 远程解析的部署形态从终端直接以项目内二进制执行命令语义与 Option 2 完全一致。三种方式的适用取舍可概括为交互式 Claude Code 会话首选 MCP能获得完整工具上下文纯终端/脚本场景用 npx离线或内网环境用本地安装。四、记忆集成让文档决策可沉淀、可检索docs-writer 通过记忆集成把“这次文档怎么写的”沉淀为可供后续检索的上下文从而让多次文档任务形成经验累积而非每次从零开始。4.1 使用 MCP 工具首选// Store mode-specific context mcp__claude-flow__memory_usage { action: store, key: docs-writer_context, value: important decisions, namespace: docs-writer } // Query previous work mcp__claude-flow__memory_search { pattern: docs-writer, namespace: docs-writer, limit: 5 }这里体现了两个关键设计写入memory_usage的action: store以docs-writer_context为 key 保存“重要决策”例如某 API 文档的约定、术语口径并显式指定namespace: docs-writer让 docs-writer 的记忆与其模式上下文绑定查询memory_search以pattern: docs-writer在相同 namespace 中检索历史limit: 5控制召回条数便于开工前快速回顾此前同类文档任务的关键结论。4.2 使用 npx CLI回退方案# Store mode-specific context npx claude-flow memory store docs-writer_context important decisions --namespace docs-writer # Query previous work npx claude-flow memory query docs-writer --limit 5需要说明的是仓库实际实现的 memory 命令参数形态存在演进。从.claude/commands/memory/memory-usage.md看管理型用法为npx claude-flow memory usage --action store|retrieve|list|clear --key key --value data而从 CLI 源码 memory 命令实现 及其帮助文案claude-flow memory store -k key --value data、claude-flow memory search -q query看store/search 子命令同样支持-k/--namespace等参数。因此实际使用时建议以当前安装版本claude-flow memory --help的输出为准docs-writer 场景核心只需理解三件事写记忆store、查记忆search/query、限定命名空间--namespace。搜索型查询还可以参考.claude/commands/memory/memory-search.md的--query/--pattern/--limit三个参数语义其中--pattern正是上文 MCP 示例中pattern字段的 CLI 对应物。五、与周边角色的协作关系一组对照避免误用仓库中存在多个易混淆的“文档角色”将它们对照清楚有助于在正确场景调度正确的模式角色/文件定位适用场景佐证路径docs-writerSPARC 模式专注 usage/integration/setup/configuration 四类 Markdown 的模块化撰写受 500 行/单文件约束SPARC 流程中 orchestrator 委派的文档子任务需要 read edit(.md) 白名单.claude/commands/sparc/docs-writer.mddocumenterSPARC 模式文档化 批量文件操作大批量文档生成、跨引用管理、示例与图表生成.claude/commands/sparc/documenter.mdruflo-docs 插件 docs-writer agent项目级文档专家JSDoc→API 文档、README/架构文档维护、漂移检测drift detection长期维护型文档任务含 doc drift 检测与 neural learning 训练plugins/ruflo-docs/agents/docs-writer.mdorchestrator将大目标拆解并按 SPARC 委派子任务作为 docs-writer 的调度入口通过new_task派单.claude/commands/sparc/sparc.md其中尤其值得注意的是 ruflo-docs 插件中的 docs-writer agent它把职责延伸到了漂移检测对比源码 export 与已文档化 API标记“代码变了但文档没变”的无文档 export并支持用hooks post-task --success true --train-neural true将成功模式回灌训练。这可以视为 docs-writer 在“单次任务模式”之外的“长期驻留岗位”形态两者共享同一写作价值观只是作用域与生命周期不同。六、实战编排模板一条可复制的 docs-writer 工作链综合前文一个以 docs-writer 收尾的典型 SPARC 文档工作链CLI 形态可以这样组织# 1. 先检索历史文档决策避免重复约定 npx claude-flow memory search -q api documentation conventions --namespace docs-writer # 2. 用 read 理解待文档化模块的公开 APIdocs-writer 的可用工具之一 # 在 Claude Code 会话内由模式调用 read 完成 # 3. 调用 docs-writer 产出模块化 Markdown npx claude-flow sparc run docs-writer create API documentation for module X --namespace docs-writer # 4. 将本次关键约定回写记忆供后续文档任务复用 npx claude-flow memory store docs-writer_context module X naming conventions --namespace docs-writer在这条链路里docs-writer 的每条自定义指令都落在实处read 保障“先理解再下笔”edit 的\.md$白名单保障“绝不污染源码”500 行上限保障文档可维护--namespace保障多模式记忆隔离而attempt_completion/new_task保障其在 orchestrator 编排下可被可靠地驱动与收敛。这也正是 docs-writer 作为一个“被编排的文档子任务模式”与手写 Markdown 之间的根本差异所在。延伸阅读模式全景与 swarm 协同.claude/commands/sparc/sparc-modes.md编排器委派 docs-writer 的证据.claude/commands/sparc/sparc.md批量文档模式对照.claude/commands/sparc/documenter.md记忆管理的完整参数表.claude/commands/memory/memory-usage.md、.claude/commands/memory/memory-search.md插件级长期文档 agent含漂移检测plugins/ruflo-docs/agents/docs-writer.md【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ruflo SPARC docs-writer 模式实战：在 Claude Code / claude-flow 中落地规范化的 Markdown 技术文档写作
ruflo SPARC docs-writer 模式实战在 Claude Code / claude-flow 中落地规范化的 Markdown 技术文档写作【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflorufloclaude-flow是一个部署智能多智能体 swarm、协调自主工作流的 agent meta-harness而 SPARCSpecification、Planning、Architecture、Review、Code是其内置的一套包含多个专业化模式的开发方法论。docs-writer正是这套体系中专司文档产出的模式它把“写文档”从自由发挥变成一套有边界、有工具约束、可被编排器orchestrator委派、且能与持久化记忆打通的标准化能力。读完本文你将掌握如何在 ruflo 项目中通过 MCP 工具、npx CLI 或本地安装三种方式启动 docs-writer 模式理解其角色约束、文件安全边界与记忆集成方式并借助仓库源码佐证其在 SPARC 全流程中的真实定位与调用关系。一、docs-writer 在 ruflo SPARC 体系中的定位在仓库根目录的.claude/commands/sparc/sparc-modes.md中SPARC 被明确描述为Specification, Planning, Architecture, Review, Code五步方法论并围绕它提供了多组专业化模式核心编排orchestrator、swarm-coordinator、workflow-manager、batch-executor、开发coder、architect、reviewer、tdd、分析研究researcher、analyzer、optimizer以及创意支持类designer、innovator、documenter、debugger、tester、memory-manager。docs-writer 与上述模式是平行关系但定位更聚焦它专门负责usage用法、integration集成、setup安装配置、configuration配置四类 Markdown 文档的撰写。它与 documenter 模式的分工可以理解为documenter 强调“带批量文件操作的文档化”而 docs-writer 强调“单点、模块化、可被编排委派的文档写作子任务”。更有说服力的调用证据来自 SPARC orchestrator 的定义文件.claude/commands/sparc/sparc.md其中明确将docs-writer列入 orchestrator 通过new_task可委派的子任务清单与spec-pseudocode、architect、code、tdd、debug、security-review等模式并列。也就是说在一个完整的 SPARC 交付流水线如“认证系统编排”中docs-writer 通常作为收尾阶段的文档化环节被调度而不是独立于流程之外的写手。配套地仓库.claude/commands/sparc/sparc-modes.md还给出了模式级 swarm 协同示例如mcp__claude-flow__swarm_init初始化 hierarchical 拓扑、spawn专门 agent、swarm_monitor监控执行docs-writer 同样可以在这些 swarm 拓扑中作为一个被 spawn 的 worker 参与大规模文档任务。二、角色定义与自定义指令文档写手的“行为契约”docs-writer 模式的核心定义位于.claude/commands/sparc/docs-writer.md其 frontmatter 声明name: sparc-docs-writerdescription: Documentation Writer - You write concise, clear, and modular Markdown documentation that explains usage, integration, setup, and configuration2.1 角色定义Role DefinitionYou write concise, clear, and modular Markdown documentation that explains usage, integration, setup, and configuration.这一句话定义了 docs-writer 的输出品味标准conciseness简洁、clarity清晰、modularity模块化而取材范围被严格限定在 usage / integration / setup / configuration 四类技术文档而非泛泛的营销文案或散文。2.2 自定义指令四条硬性约束自定义指令Custom Instructions给出了可执行的行为规则原文逐条如下每条都对应一种可被校验的输出保障Only work in .md files.——工作范围锁定 Markdown这是与其他代码类模式最本质的区别Use sections, examples, and headings.——输出必须结构化分节、给示例、用标题层级组织Keep each file under 500 lines.——单文件行数红线500 行防止文档膨胀为不可维护的巨块Do not leak env values.——禁止泄露环境变量值属于安全红线与技术文档写作直接相关Summarize what you wrote usingattempt_completion.——任务收尾必须通过attempt_completion汇报保证子任务在 Agent 编排中有明确的完成信号Delegate large guides withnew_task.——遇到大型指南时要用new_task拆分为子任务委派而非在一个回合内硬写到底。这组约束与该项目 agent 体系的设计理念一致每一份文档任务都要求模块化、可测试、有完成态。从仓库.claude/commands/sparc/sparc.md末尾的 Validate 清单✅ Files 500 lines、✅ No hard-coded env vars、✅ Modular, testable outputs、✅ All subtasks end with attempt_completion可以看到docs-writer 的约束并不是孤例而是整个 SPARC 交付链共享的质量闸门。2.3 可用工具Available Tools该模式被刻意限制了工具面只有两个read文件读取与查看用于先理解待文档化的源码或现有文档edit仅允许编辑 Markdown 文件匹配规则\.md$这是防止文档模式误改代码文件的护栏。这种“只能读、只能写 .md”的窄工具面从实现上保证了 docs-writer 即使被并行 spawn 进 swarm也不会触碰源代码文件符合最小权限原则。三、三种激活方式从 MCP 到裸终端docs-writer 的激活方式与 SPARC 家族保持一致原文提供了三种途径优先级从高到低排列。3.1 Option 1MCP 工具Claude Code 中首选mcp__claude-flow__sparc_mode { mode: docs-writer, task_description: create API documentation, options: { namespace: docs-writer, non_interactive: false } }参数说明mode固定为docs-writerMCP 服务器据此路由到对应模式的系统提示词与工具白名单task_description任务描述例如create API documentation是驱动整轮文档产出的输入options.namespace命名空间通常设为与模式同名docs-writer用于让记忆与模式上下文相互隔离options.non_interactive交互开关false表示允许在关键节点与用户确认适合需要澄清需求的文档任务批量/无人值守场景可置true。3.2 Option 2npx CLIMCP 不可用时的回退# Use when running from terminal or MCP tools unavailable npx claude-flow sparc run docs-writer create API documentation # For alpha features npx claude-flowalpha sparc run docs-writer create API documentation # With namespace npx claude-flow sparc run docs-writer your task --namespace docs-writer # Non-interactive mode npx claude-flow sparc run docs-writer your task --non-interactive要点拆解sparc run mode task是 SPARC 模式的统一 CLI 入口docs-writer 只是mode的一个取值希望使用 alpha 通道时切换到npx claude-flowalpha--namespace docs-writer使该次运行的模式状态/记忆写入独立命名空间避免与其他模式coder、architect 等的状态串扰--non-interactive适合 CI、脚本或 swarm 批量文档生成场景杜绝终端等待输入导致的挂起。3.3 Option 3本地安装# If claude-flow is installed locally ./claude-flow sparc run docs-writer create API documentation适用于已在仓库本地安装 claude-flow而非依赖 npx 远程解析的部署形态从终端直接以项目内二进制执行命令语义与 Option 2 完全一致。三种方式的适用取舍可概括为交互式 Claude Code 会话首选 MCP能获得完整工具上下文纯终端/脚本场景用 npx离线或内网环境用本地安装。四、记忆集成让文档决策可沉淀、可检索docs-writer 通过记忆集成把“这次文档怎么写的”沉淀为可供后续检索的上下文从而让多次文档任务形成经验累积而非每次从零开始。4.1 使用 MCP 工具首选// Store mode-specific context mcp__claude-flow__memory_usage { action: store, key: docs-writer_context, value: important decisions, namespace: docs-writer } // Query previous work mcp__claude-flow__memory_search { pattern: docs-writer, namespace: docs-writer, limit: 5 }这里体现了两个关键设计写入memory_usage的action: store以docs-writer_context为 key 保存“重要决策”例如某 API 文档的约定、术语口径并显式指定namespace: docs-writer让 docs-writer 的记忆与其模式上下文绑定查询memory_search以pattern: docs-writer在相同 namespace 中检索历史limit: 5控制召回条数便于开工前快速回顾此前同类文档任务的关键结论。4.2 使用 npx CLI回退方案# Store mode-specific context npx claude-flow memory store docs-writer_context important decisions --namespace docs-writer # Query previous work npx claude-flow memory query docs-writer --limit 5需要说明的是仓库实际实现的 memory 命令参数形态存在演进。从.claude/commands/memory/memory-usage.md看管理型用法为npx claude-flow memory usage --action store|retrieve|list|clear --key key --value data而从 CLI 源码 memory 命令实现 及其帮助文案claude-flow memory store -k key --value data、claude-flow memory search -q query看store/search 子命令同样支持-k/--namespace等参数。因此实际使用时建议以当前安装版本claude-flow memory --help的输出为准docs-writer 场景核心只需理解三件事写记忆store、查记忆search/query、限定命名空间--namespace。搜索型查询还可以参考.claude/commands/memory/memory-search.md的--query/--pattern/--limit三个参数语义其中--pattern正是上文 MCP 示例中pattern字段的 CLI 对应物。五、与周边角色的协作关系一组对照避免误用仓库中存在多个易混淆的“文档角色”将它们对照清楚有助于在正确场景调度正确的模式角色/文件定位适用场景佐证路径docs-writerSPARC 模式专注 usage/integration/setup/configuration 四类 Markdown 的模块化撰写受 500 行/单文件约束SPARC 流程中 orchestrator 委派的文档子任务需要 read edit(.md) 白名单.claude/commands/sparc/docs-writer.mddocumenterSPARC 模式文档化 批量文件操作大批量文档生成、跨引用管理、示例与图表生成.claude/commands/sparc/documenter.mdruflo-docs 插件 docs-writer agent项目级文档专家JSDoc→API 文档、README/架构文档维护、漂移检测drift detection长期维护型文档任务含 doc drift 检测与 neural learning 训练plugins/ruflo-docs/agents/docs-writer.mdorchestrator将大目标拆解并按 SPARC 委派子任务作为 docs-writer 的调度入口通过new_task派单.claude/commands/sparc/sparc.md其中尤其值得注意的是 ruflo-docs 插件中的 docs-writer agent它把职责延伸到了漂移检测对比源码 export 与已文档化 API标记“代码变了但文档没变”的无文档 export并支持用hooks post-task --success true --train-neural true将成功模式回灌训练。这可以视为 docs-writer 在“单次任务模式”之外的“长期驻留岗位”形态两者共享同一写作价值观只是作用域与生命周期不同。六、实战编排模板一条可复制的 docs-writer 工作链综合前文一个以 docs-writer 收尾的典型 SPARC 文档工作链CLI 形态可以这样组织# 1. 先检索历史文档决策避免重复约定 npx claude-flow memory search -q api documentation conventions --namespace docs-writer # 2. 用 read 理解待文档化模块的公开 APIdocs-writer 的可用工具之一 # 在 Claude Code 会话内由模式调用 read 完成 # 3. 调用 docs-writer 产出模块化 Markdown npx claude-flow sparc run docs-writer create API documentation for module X --namespace docs-writer # 4. 将本次关键约定回写记忆供后续文档任务复用 npx claude-flow memory store docs-writer_context module X naming conventions --namespace docs-writer在这条链路里docs-writer 的每条自定义指令都落在实处read 保障“先理解再下笔”edit 的\.md$白名单保障“绝不污染源码”500 行上限保障文档可维护--namespace保障多模式记忆隔离而attempt_completion/new_task保障其在 orchestrator 编排下可被可靠地驱动与收敛。这也正是 docs-writer 作为一个“被编排的文档子任务模式”与手写 Markdown 之间的根本差异所在。延伸阅读模式全景与 swarm 协同.claude/commands/sparc/sparc-modes.md编排器委派 docs-writer 的证据.claude/commands/sparc/sparc.md批量文档模式对照.claude/commands/sparc/documenter.md记忆管理的完整参数表.claude/commands/memory/memory-usage.md、.claude/commands/memory/memory-search.md插件级长期文档 agent含漂移检测plugins/ruflo-docs/agents/docs-writer.md【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考