用途:这是一套技术文档的内部写作规范,适用于规格、设计文档、README、参考文档、计划、报告等技术性文字。规则本身用英文书写,但文档保留其自身语言,例如荷兰语文档以荷兰语撰写与审阅;结构与真实性规则适用于任何语言,参考文件中的词汇表则为英文专用。核心原则是:文档陈述当前且经过验证的行为,结论先行,每条论断可溯源到来源,每个事实只出现在一个位置;宁可文档单薄,也不夸大。本规则约束文档而非聊天回复。
主要能力:规定何时加载其他配套技能,例如提案、RFC、设计文档、规格或迁移计划对应 writing-design-docs;决策记录对应 recording-decisions;变更日志对应 writing-changelogs;运行手册对应 writing-runbooks;问题、事后复盘、API 参考、文档审阅等各有对应技能。规定起草前必须声明文档类型(规范性、描述性、历史性、运行手册、参考)、受众、目的与非目标。先阅读同目录至多两份同类文档并采用其结构与语气,检查是否有 README 索引并更新。明确规则优先级:真实性与安全规则优先,其次文档类型技能中的显式例外,再次硬性规则、目录约定与样式偏好。按文档类型区分编辑规则:规范性文档遇到代码违反契约应记录违规而非削弱契约;描述性文档须与代码完全一致;历史性文档永不改写历史;运行手册每一步必须实际执行过;参考文档须穷尽所有键、标志与默认值。
硬性规则:禁用 em dash、en dash 与双连字符破折号;文档内不设变更日志章节与最后更新字段;不得把交付历史当作叙述性状态写入正文、注释、命名或字符串;不得把无法溯源到代码路径、固定提交、测试、文档或一手来源的内容陈述为事实;一个事实只有一个归属;已接受的决策与已应用的迁移不可修改;标题使用句首大写。工作流为先读、分类、声明检查点、逐层结论先行起草、为每条论断标注置信度、做样式检查、交付前核对引用。
适用场景与限制:面向编写技术性文字的场景。不适用于营销文案、社交帖子或界面微文案,仅真实性规则仍对其有约束。它不决定内容真假,不授权改写遵循自身约定的既有文档,也不接受把文档改成更有冲击力或更有说服力的要求。受众细分与常见错误均有说明。资料未提供该技能的具体安装命令、收费方式与平台支持信息。