用途
Superior Docs 面向需要长期维护的项目文档场景。其核心主张是:文档应让未来的维护者在不依赖聊天记录的情况下,恢复项目当前形态、重要决策和安全操作流程。文档被定位为“证据的维护视图”,而不是第二个编造真相的来源。
主要能力
该技能提供多种工作模式:
- 引导(Bootstrap):在尚无文档系统时建立一套有用的 docs/ 体系。
- 记录(Record):把已验证的实现、修复、重构、配置变更或功能成果写入实现时间线。
- 同步(Synchronize):在项目发生已验证变更后,更新受影响的文档。
- 重建(Reconstruct):依据仓库证据推导架构演进、发布或维护历史。
- 交接(Handoff):在较大工作结束时,记录当前实现、边界、风险与后续工作。
默认情况下,对代码、配置、模式、API 行为、安全控制、构建行为或用户可见功能完成实质性变更后,会创建或更新实现记录,除非用户明确要求不写文档。
使用方式
技能要求先建立证据:检查相关代码路径、配置、测试、脚本、部署文件、既有文档和仓库说明;涉及历史顺序或发布时使用 Git 历史。在归因变更前,应先检查仓库状态与本次任务的实际差异,在脏工作区中保留无关的用户改动。
技能将陈述分类为:当前事实(由当前仓库或运行时证据证明)、已接受决策(记录在权威决策源或用户明确确认)、历史事实(由提交、标签、发布、迁移或带日期的工件支持)、计划工作(已明确提出但尚未实现)、未知(未解决并如实说明)。不得把提交信息、过期文档、未使用文件或看似合理的架构未经佐证就当作当前事实。
文档组织上,每个文档聚焦一个持久主题并给予稳定路径;开头写明目的、范围和最后验证的修订或日期;链接到权威代码、配置、命令、决策与相关文档;记录归属和边界,而非易过时的完整文件清单;仅在校验过仓库来源或安全执行后才写确切命令;区分当前状态、历史与未来工作;映射、决策、接口或命令优先用简洁表格,理由与约束用散文;易变契约应指明权威来源,避免手工复制生成的模式、命令输出或配置清单。
适用场景
适用于需要建立或维护仓库级文档的软件项目,尤其是需要记录实现时间线、同步架构与决策文档、从 Git 历史重建演进过程,或在任务结束时进行文档交接的团队。
限制
资料未提供具体的命令、配置文件格式或安装步骤,暂未提供。技能本身对文档内容有严格约束:不创建空目录、占位指南或每个想象子系统一个文件;较小的、保持准确的链接文档集优于无人可信的庞大目录树;历史重建时不得倾倒每个提交、不得把提交顺序当作因果关系、不得因某分支曾包含相关代码就声称功能已发布;文档与工作代码冲突时应先验证代码路径是否活跃、检查是否有已接受的待处理迁移或例外,获授权后更新过期文档,未解决的冲突应如实报告而非选择偏好版本。生成文档前还需审查差异,避免泄露密钥、凭据、私有基础设施细节、个人数据或复制的日志。