SuperAPI AI 工具集

sota-docs-workflow

办公与效率

查看项目

更新于 10-16 00:06

技能介绍

用途:为代码之外的交付物提供专家级规则,包括文档(结构、参考文档、时效性、runbook)与协作流程(PR、评审、提交、发布)。规则以命令式表述,附理由与正反例,每个规则文件末尾带审计清单;通过索引按需加载相关文件。ADR 见 sota-architecture,API 契约设计见 sota-api-design,标签签名与 CI 供应链见 sota-devsecops,本技能仅引用不重复。

主要能力:BUILD 模式下,写文档前先分类,每篇文档只属于一种 Diátaxis 模式(tutorial/how-to/reference/explanation)并据此命名;文档与代码同仓、经 PR 评审、CI 链接检查、示例可执行。README 写清 what/why/5 分钟快速上手/真实状态。runbook 与告警关联且命令精确。参考文档由 OpenAPI/docstring/rustdoc/godoc 生成,警告即错误;changelog 从第一天起采用 Keep a Changelog 格式。流程默认小型单一用途 PR、trunk-based 短分支、原子提交、≤72 字符祈使式标题主题。

AUDIT 模式:界定审计范围(文档树、生成参考、changelog、迁移指南、近期 PR、git 历史与标签),审计实际行为而非书面政策,抽样执行快速上手、runbook 命令,阅读 docstring、近期 PR 与提交。按严重度分级(Critical/High/Medium/Low)给出发现,格式包含位置、规则条目、问题、影响与修复,且每条发现需引用抽样证据。

使用方式与限制:仅通过规则索引按任务加载相关文件(如 rules/01-documentation-architecture.md 等)。资料未提供具体安装命令、收费、平台支持信息。适用于维护代码仓库文档与协作流程的团队;不适合期待自动生成完整文档或替代人工评审的场景。