用途:创建与维护各类文档产物及其结构,包括 docstring、行内注释、API 参考、README、ADR、变更日志和架构文档。本技能负责规定每个产物必须包含什么内容;文字风格与 Diátaxis 模式框架参见 loom-technical-writing,图示参见 loom-diagramming,OpenAPI 等 API 规范文件参见 loom-api-documentation。
主要能力:按受众和 Diátaxis 模式选择文档类型,并按必需结构填充内容,且同一文档不混用模式。README 采用 how-to + reference,需含一句话定位、安装、快速开始和外部链接;教程含有序步骤、可保证成功的路径和预期输出;how-to 指南含目标式标题、前置条件、编号步骤和验证;API 参考覆盖每个公开符号的参数、返回、错误及至少一个示例;ADR 含背景、决策、后果、备选方案和状态;变更日志按版本分组、标注日期和破坏性变更;docstring 含用途、参数、返回、异常/panic 和示例;行内注释只解释 WHY,不重述代码。
使用方式:任何任务第一步先确定受众(开发者/最终用户/运维/贡献者),再阅读代码使文档符合真实行为,绝不凭假设编写。文档化契约而非实现;公开符号要有文档,私有符号仅在不易理解时补充。TODO/FIXME 必须引用跟踪 issue。"}