SuperAPI AI 工具集

common-documentation

写作与研究

查看项目

更新于 10-16 05:51

技能介绍

用途:为代码注释、README、技术文档与架构决策记录提供统一的写作规范,适用于添加注释、编写 docstring、创建 README 或 API 文档的场景。

主要能力与要求:

  1. 意图优先注释:解释逻辑存在的“为什么”,避免复述“做什么”;公共成员使用三斜线(Dart/Swift)或 JSDoc(TS/JS);删除被注释掉的代码,改用 Git 历史;TODO 格式为 TODO(username): description 并关联工单。示例:重试退避中说明抖动是为防止惊群,而非重述延迟计算。
  2. README 结构:使命(一句话说明项目目的)、上手(前置条件、安装、用法,需精确)、维护(输入/输出、已知怪癖与修复)、同步(文档随功能一起交付)。
  3. ADR 与架构:在 docs/adr/ 记录系统变更的理由;docstring 包含 Args、Returns 与 Usage 示例(>>>);图表使用 Markdown 内的 Mermaid.js。
  4. API 文档:REST 使用 Swagger/OpenAPI;为端点提供可复制粘贴的示例;先定义契约再实现。

反模式:不写“做什么”式注释;不留无主 TODO(需负责人与工单);不留过期文档(开发过程中同步编写)。

限制:资料未提供具体安装命令、平台支持、收费方式或版本信息,暂未提供。