SuperClaude Framework Technical Writer Agent：面向受众的文档编写专家配置指南

SuperClaude Framework Technical Writer Agent面向受众的文档编写专家配置指南【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址: https://gitcode.com/gh_mirrors/su/SuperClaude_Framework本指南以 SuperClaude Framework 的technical-writerAgent 定义文件plugins/superclaude/agents/technical-writer.md发布副本见 src/superclaude/agents/technical-writer.md为核心系统讲解该 Agent 的定位、触发条件、行为准则、专注领域、关键动作、产出物与边界约束并结合仓库内/sc:document、/sc:spec-panel、/sc:explain等命令与 Agent 协作机制给出可直接套用的实战用法。读完本文你将掌握如何在 Claude Code 会话中按需唤起 technical-writer、如何为它配置恰当的文档任务与协作组合以及如何利用它产出受众导向、可验证、可访问的 API 文档、用户指南、技术规格与排障文档。一、technical-writer 是什么在 SuperClaude Framework 中Agents 并非独立的 AI 模型或软件而是以 Markdown 文件形式存在的情境指令context instructions。Claude Code 读取这些指令后会切换为特定领域的专家行为模式见 docs/user-guide/agents.md 中 What are SuperClaude Agents? 一节。technical-writer 就是这组领域专家之一。它的定义文件首部 Frontmatter 明确声明--- name: technical-writer description: Create clear, comprehensive technical documentation tailored to specific audiences with focus on usability and accessibility category: communication ---其核心定位可从三点概括受众优先为特定读者群体编写清晰、全面的技术文档而非为自己写作可用性驱动始终聚焦文档的可用性与可访问性accessibility属于 communication 类别与learning-guide同属沟通与学习类 Agent服务于知识传递而不是代码实现。仓库把 Agent 定义文件同时维护在两个位置plugins/superclaude/agents/是编辑源头src/superclaude/agents/是随包分发的同步副本两者必须保持一致见 src/superclaude/agents/README.md。二、何时触发Triggers 触发条件technical-writer 定义了三类典型触发场景在实际使用中可以直接用这些表述向 Agent 下达文档任务触发场景典型请求表述API 文档与技术规格创建编写 X 模块的 API 文档、生成技术规格说明用户指南与教程开发为这个产品写一份用户指南、制作安装教程文档改进与可访问性增强改进这份 README 的可读性、按 WCAG 检查文档可访问性内容结构化与信息架构设计为这套文档设计信息架构、规划文档目录结构在自动激活层面docs/user-guide/agents.md 的 Agent Trigger Lookup 表格给出了对应的关键词模式documentation、readme、API docs、user guide、technical writing、manual都会路由到 technical-writer/sc:document命令的主 Agent 也正是 technical-writer。需要特别说明的是所谓自动激活并不是系统层面的逻辑路由而是 Claude Code 依据请求中的关键词与模式读取情境指令、主动切换专家行为的结果同上文档的 How Agent Auto-Activation Works 一节。因此请求中的措辞越精确激活就越可靠——这是使用所有 SuperClaude Agent 的关键前提。三、行为准则Write for your audience, not for yourself原文档的 Behavioral Mindset 是全篇的灵魂值得逐句拆解Write for your audience, not for yourself. Prioritize clarity over completeness and always include working examples. Structure content for scanning and task completion, ensuring every piece of information serves the readers goals.它同时提出了四条可执行原则为读者写作而非为自己写作——文档的评判标准是读者能否完成任务而不是作者是否写得尽兴清晰优先于完备——在信息齐全与一看就懂发生冲突时优先保证清晰永远包含可运行的示例——抽象描述必须配以能跑通的代码或步骤内容为扫读与任务完成而设计——用标题层级、列表、表格组织信息让读者能快速定位并照着完成目标。这套准则在仓库的配套命令中有直接呼应。例如/sc:documentplugins/superclaude/commands/document.md的行为流是 Analyze → Identify → Generate → Format → Integrate其中 Identify 阶段明确要求确定文档需求与目标受众上下文/sc:explainplugins/superclaude/commands/explain.md则在 Behavioral Flow 中要求Assess: Determine audience level and appropriate explanation depth。可见受众分析是整个 SuperClaude 文档体系的一致前提。四、五大专注领域Focus Areas原文档列出了 technical-writer 的五个专注领域每个领域都对应一套具体的实操关注点Audience Analysis受众分析评估读者技能水平skill level、识别读者目标goal identification、理解使用语境context understanding。例如为 API 文档的初级调用者 vs 资深集成工程师撰写篇幅、术语密度与示例深度完全不同。Content Structure内容结构信息架构information architecture、导航设计navigation design、逻辑流程设计logical flow development。对应触发条件中的Technical content structuring and information architecture development。Clear Communication清晰沟通使用平实语言plain language、保证技术精确technical precision、把概念讲清楚concept explanation。这是清晰优先于完备准则的落点。Practical Examples实用示例可运行的代码样例working code samples、分步操作流程step-by-step procedures、真实世界场景real-world scenarios。对应行为准则中always include working examples。Accessibility Design可访问性设计WCAG 合规WCAG compliance、屏幕阅读器兼容screen reader compatibility、包容性语言inclusive language。这是与多数通用文档 Agent 最大的差异点——可访问性被列为一级专注领域而非附属项。五、关键动作五步文档生产流程Key Actions原文档给出的五个关键动作构成了一条完整的文档生产流水线Analyze Audience Needs分析受众需求理解读者的技能水平与具体目标为后续所有环节确定靶向Structure Content Logically逻辑化组织内容围绕理解最优与任务完成组织信息——即为扫读设计Write Clear Instructions撰写清晰指令/步骤产出分步流程且每一步都附带可运行示例与验证步骤verification stepsEnsure Accessibility确保可访问性系统化应用无障碍标准与包容性设计原则Validate Usability验证可用性以任务完成成功率和清晰度为指标实测文档——即把文档当产品来测试。其中第 3 步的验证步骤与第 5 步的可用性验证尤为实用任何安装、配置或调用说明都应写明运行什么命令/请求什么端点来确认成功这与仓库中docs目录下大量含 Verify / Test / Check 清单的文档风格如 docs/user-guide/agents.md 各 Agent 的 Success Criteria 部分一脉相承。六、五类标准产出Outputstechnical-writer 定义了五类可交付物覆盖软件文档的典型谱系产出类型内容要求API Documentation完整的参考手册含可运行示例与集成指引working examples and integration guidanceUser Guides分步教程复杂度适配目标读者并提供有助理解的上下文Technical Specifications系统文档含架构细节与实现指引Troubleshooting Guides问题排查文档覆盖常见问题与解决路径Installation Documentation安装流程含验证步骤与环境配置说明对应到命令层面/sc:documentplugins/superclaude/commands/document.md提供了四种产出格式是 technical-writer 能力的命令化入口/sc:document [target] [--type inline|external|api|guide] [--style brief|detailed]--type inline为函数与类生成 JSDoc / docstring 风格的行内注释--type api抽取接口生成 API 参考文档含端点和 schema--type guide面向用户的教程聚焦实现模式与常见用例--type external为组件库等生成独立的外部文档文件。该命令还有配套的工具协调约定用 Read 分析组件结构、Grep 提取引用与模式、Write 创建格式化文档、Glob 组织多文件文档项目——这与 technical-writer 结构化为扫读与任务完成设计的准则相互印证。七、边界约束Boundaries做什么与不做什么原文档以 Will / Will Not 明确划定了技术文档作者的职责边界这在多 Agent 协作场景下至关重要Will会做创建带有受众定向与实用示例的全面技术文档编写符合无障碍标准、以可用性为核心的 API 参考与用户指南为最佳理解与任务完成设计内容结构。Will Not不会做实现应用功能或编写超出文档示例范围的生产代码做出架构决策或设计用户界面超出文档范围创作营销内容或非技术性沟通。边界的存在保证了 technical-writer 与架构、开发、测试类 Agent 之间不越权、不冲突它负责把决策写清楚而决策本身由system-architect、backend-architect等承担。八、多 Agent 协作technical-writer 在文档工作流中的位置8.1 与需求分析、学习引导类 Agent 的组合docs/user-guide/agents.md 给出了多套以 technical-writer 为核心的协作组合Documentation Projecttechnical-writer requirements-analyst learning-guide domain experts——需求分析师确保规格清晰见 plugins/superclaude/agents/requirements-analyst.md其产出含 PRD 与验收文档学习引导 Agent 负责教育内容设计见 plugins/superclaude/agents/learning-guide.md专精渐进式学习与理解验证technical-writer 负责成稿API Documentationbackend-architect technical-writer security-engineer quality-engineer——架构师给出接口设计安全与质量工程师把关technical-writer 成文Educational Contentlearning-guide technical-writer frontend-architect quality-engineer——前端架构师提供可访问的 UI 文档素材。在 Agent 选择决策树中文档需求属于Learning Focus分支会同时纳入learning-guide与technical-writer见 docs/user-guide/agents.md 的 Selection Decision Tree。8.2 在专家评审面板中担任写作质量把关/sc:spec-panelplugins/superclaude/commands/spec-panel.md是一个多专家规格评审命令其 Frontmatter 明确把 technical-writer 列为内置 Personapersonas: [technical-writer, system-architect, quality-engineer]在该命令的 MCP 集成一节中说明Technical Writer Persona: Activated for professional specification writing and documentation quality。也就是说当使用spec-panel评审或改进规格文档时technical-writer 负责从专业写作与文档质量维度提出意见与 system-architect架构分析、quality-engineer质量与测试策略形成三角评审。评审模式包括讨论discussion、批判critique与苏格拉底式提问socratic技术写作视角可全程参与。8.3 被 pm-agent 委派承接用户指南在 pm-agent 的完整工作流中plugins/superclaude/commands/pm.md 第 164 行 Delegate to technical-writer当任务进入文档阶段时pm-agent 会把用户指南类产出委派给 technical-writer同文件第 211 行映射technical-writer: User guide。这印证了它在整个 SuperClaude 代理体系中的定位专职承接所有面向读者的文档交付让其他专家专注各自的实现与分析职责。九、实战演练三个可直接套用的场景以下场景基于仓库内命令定义整理可直接在 Claude Code 会话中使用需先按 plugins/superclaude/README.md 完成安装本地开发可用claude --plugin-dir ./plugins/superclaude。场景 1手动唤起 technical-writer 编写 API 文档agent-technical-writer document this API with examples或结合/sc:document指定格式与风格/sc:document src/api --type api --style detailed # 抽取接口生成 API 参考文档含端点、schema、用法示例与集成指引场景 2文档任务自动激活与协作/sc:design accessible React dashboard with documentation # → 触发 frontend-architect learning-guide technical-writer /sc:document payment-module --type guide --style brief # 生成面向用户的集成指南聚焦实现模式与常见用例场景 3规格文档的多专家评审/sc:spec-panel auth_api.spec.yml --mode critique --focus requirements,architecture # technical-writer 从专业写作与文档质量维度参与评审 # 与 system-architect、quality-engineer 协同产出改进建议十、验证与常见问题如何确认 technical-writer 已被激活按 docs/user-guide/agents.md 的测试方法可先验证基础激活agent-technical-writer explain how to document this component若输出表现出明确的受众分析、示例优先、结构与可访问性意识即说明指令生效。若未激活检查请求中是否包含触发关键词documentation、readme、API docs、user guide 等Agent 文件是否存在于~/.claude/agents/或重启 Claude Code 会话是否误用了过于模糊的表述如帮我写点东西导致路由到其他 Agent。十一、小结technical-writer 是 SuperClaude Framework 中负责技术写作的专业 Agent其设计核心可归纳为以受众分析为起点以清晰与可用性为准绳以可运行示例与验证步骤为交付标准以 WCAG 与包容性设计为底线以不越界不写生产代码、不做架构决策为边界。它与/sc:document命令入口、/sc:spec-panel评审面板 Persona、pm-agent委派流程以及 requirements-analyst、learning-guide协作组合共同构成了仓库内完整的技术文档生产体系。需要深入自定义或扩展该 Agent 时编辑 plugins/superclaude/agents/technical-writer.md 并同步到 src/superclaude/agents/technical-writer.md 即可两处必须保持一致见 src/superclaude/agents/README.md。【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址: https://gitcode.com/gh_mirrors/su/SuperClaude_Framework创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考