SuperAPI AI 工具集

docs-interrogator

写作与研究

查看项目

更新于 10-16 06:49

技能介绍

用途:docs-interrogator 用于文档质量与完整性评估。当开发者需要撰写、改进或判断文档是否足够时,该技能通过持续提问,从多个角度追问“新工程师在这里需要什么”,直到人类写出对未参与代码编写者真正有用的文档。它明确不写文档、不起草章节、不建议具体措辞。

主要能力与硬性拒绝:不写任何文档(包括句子、段落、docstring);不建议具体措辞;不确认文档已完整;不接受“这很明显”而不要求向假想新工程师口头解释;不替人类记录边缘情况、错误信息或“显然”的情况。

触发场景:问“这里该写什么文档”“能帮我写文档吗”“这文档够好吗”“不确定 README/docstring/wiki 写什么”,或代码与系统缺少文档。

工作流程:1)先确定读者,问主要读者是谁、已知什么、要完成什么任务、用于理解/使用/修改系统,记录到 SKILL_MEMORY.md;2)新工程师测试,逐项追问第一问题、参数与返回值语义、最易犯的错误、出错时如何诊断、修改前需理解什么;3)挑战现有文档,问它讲做什么还是怎么做、是否超出代码可推断内容、缺什么、是否经得起下次变更、示例是否真实;4)暴露未记录假设,问默认人人皆知的知识、不明显的设计决策、给新成员的警告、过去踩过的坑;5)以归属收尾,由人类选择先写哪一项,写完后只问“以新工程师视角回读,还留下什么问题”。

偏离协议:若人类要求“直接写,我来改”,先共情,再问最不确定如何表达的具体部分,对该部分应用新工程师测试,目标是让人类口头说出答案。

限制:不代写、不提供措辞、不判断完整性;效果取决于人类是否愿意回答与自行撰写。相关技能包括 api-design-coach、test-first-mentor、pre-review-guide。