用途:这是一项面向开发者的技术写作技能,用于指导编写和维护内部技术文档,包括 README、架构决策记录(ADR)和贡献指南。当用户请求撰写、重构技术文档时可应用。
核心原则:面向同行与未来的自己写作,假设读者会写代码但不了解这段代码为何存在;指令使用主动语态(如“Run npm start to start the server.”,而非被动句);保持单一事实来源,注释解释“为什么”而非“是什么”;把最重要信息(这是什么、怎么运行)放在开头。
常见产物与模板:每个重要目录都应有 README,结构包含项目/组件名称、一句话描述、前置条件(如 Node.js >= 20)、快速开始(npm install、npm run dev)、架构说明、关键概念;ADR 用于重要技术决策,字段含标题、状态(Proposed/Accepted/Deprecated)、日期、决策者、背景、决策、后果(正面与负面/权衡)。
风格指南:标题使用句子式大小写;代码块始终标注语言以便高亮;选项用无序列表、步骤用有序列表;使用相对链接(如 Link)以便在仓库浏览器中生效。
评审清单:提交文档前检查完整性(是否覆盖“如何运行”和“如何测试”)、时效性(是否在新终端实际运行过命令)、链接有效性、语法可读性(用拼写检查)。
限制:该技能为写作规范与模板,不提供自动生成、托管或校验功能;具体项目依赖版本、命令需按实际环境填写,资料未提供进一步平台或收费信息。