SuperAPI AI 工具集

doc-standard

写作与研究

查看项目

更新于 10-16 17:29

技能介绍

doc-standard 是一个针对开发工程文档的 AI 技能,职责被限定在“粒度标准”这一个观察点上:它按照统一标准生成工程文档,并检查既有文档是否偏离该标准。

用途

该技能用于处理工程文档的粒度规范,关注 What/Why 与 How 的分离、可追溯性、可验证性、非功能需求不得后置等原则。它明确不处理文章校对、代码审查、设计决策记录和完成物评审,这些被委派给其他技能。当被要求处理未覆盖的文档类型时,技能会告知“配方未就绪”,不会强行生成。

主要能力

技能支持 19 个文档类型的生成与检查:

瀑布式(WF):data-design(基本设计=逻辑数据设计)、external-design(基本设计=外部设计)、architecture-design(基本设计=方式设计)、nonfunctional-design(基本设计=非功能设计)、operations-design(基本设计=运用/迁移设计)、detailed-design-data(详细设计=物理数据)、detailed-design-process(详细设计=处理详细)、srs(需求定义)、test-case-spec(测试用例规格)、test-plan(测试计划)、test-design-spec(测试设计规格)、test-procedure-spec(测试步骤规格)、test-strategy(测试策略)。

敏捷式(agile):user-story(用户故事)、acceptance-criteria(验收标准=Given-When-Then)、design-doc(设计共识文档)、adr(架构决策记录)、rfc(Request for Comments=决定前的提案)、pr-faq(PR-FAQ=Amazon Working Backwards、企划逆算)。

使用方式

使用方式分为两种模式。生成模式:先确定方法(WF / agile),再确定具体文档类型,然后读取对应的配方文件,结合原则层生成文档,生成后先运行一次机械检查,消除自身偏离后再输出。检查模式:先判定文档类型,然后分两层判定——机械判定运行三个 Python 脚本(check_headings.py 检查必需标题缺失,check_vocabulary.py 检查词汇,check_traceability.py 检查可追溯性表空单元格),质量判定则参照对应的评分细则文件。

随附资料库按需读取,不常驻加载,以避免上下文膨胀。原则层(granularity-axis.md)是唯一真相来源,配方、评分细则与本技能如有冲突,以原则层为准。

适用场景

适用于需要按工程阶段编写或审查文档粒度边界的场景,例如“写一份设计书”“检查这份文档的粒度”“需求定义的模板”等。对于测试策略、测试计划、测试设计规格、测试用例规格、测试步骤规格等形成了五级体系;基本设计形成了数据、外部、方式、非功能、运用/迁移五个细分。

限制

该技能只负责粒度边界,不处理文章校对、代码审查、设计判断记录、完成物评审。机械判定支持的类型为上述 19 个;其他类型的模式与词汇未定义,机械判定会变成 skipped。其中 user-story、design-doc、test-strategy、adr、rfc、pr-faq 的词汇表为空,返回的是 pass 而非 skipped。未覆盖的文档类型不会强行生成。