mcpField
S
specsfy-documentator

specsfy-documentator

github.com/promovaweb开发87440 次安装1 周前更新
代码仓库

关于 specsfy-documentator

specsfy-documentator 是 Specsfy 框架中的系统文档技能，面向维护项目技术文档的团队。它依据本地代码和元数据生成文档及软件包清单，并通过检查模式核对文档是否与当前状态一致。

主要功能

  1. 01生成系统架构与组件文档
  2. 02整理应用、数据库和流程图
  3. 03记录测试、前端与集成信息
  4. 04构建 npm 与 Composer 软件包清单
  5. 05检查生成文档与项目状态

适用场景

  1. 01为现有代码库建立技术文档
  2. 02盘点项目依赖及其本地元数据
  3. 03验证文档是否反映当前代码

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/promovaweb/specsfy --skill specsfy-documentator

安装后在 Claude Code 中输入/specsfy-documentator确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
documentation-standard.md
scripts/
build_documentation.mjs

详细介绍

记录系统文档

必须完成的准备工作

执行此技能前，必须先在项目根目录加载 $specsfy-setup。自动交接时，请在此步骤前重新加载。复用对话中已确认的根目录；如果 setup 指出有待处理事项，则不要继续。

交互模式

交互模式：sem perguntas。 此技能不提问。对于可执行来源无法证实的所有数据，均记录为未识别。

  1. 阅读本地说明、PROJECT.md、.specsfy/STACK.md、 .specsfy/RULES.md、.specsfy/DATABASE.md、清单文件、锁文件、 已安装的元数据和现有代码。

  2. 在更改已发布的文档结构前，阅读文档规范。

  3. 构建全部文档和 .specsfy/PACKAGES.md，即使触发此技能时没有近期的 spec 或实现也要如此：

    node scripts/build_documentation.mjs --project <raiz>

  4. 检查生成的文件，仅手动修正代码无法支持的推断。不要编造决策、关系或集成。

  5. 执行 --check，以证明文档反映了当前状态：

    node scripts/build_documentation.mjs --project <raiz> --check

  6. 保留 specsfy:documentator 代码块之外的人工编写内容，包括 .specsfy/PACKAGES.md 中的内容。将该代码块视为可根据本地来源重建的投影。

  7. 在任务证据中记录命令、结果和已更新的文件。

必须覆盖的内容

在 docs/ 中维护：

  • 门户和阅读指南；
  • 架构、组件和 Mermaid UML；
  • 应用清单和现有实现；
  • 数据库和使用 erDiagram 描述的实体；
  • 使用 flowchart 和 sequenceDiagram 描述的流程；
  • 测试指南和摘要；
  • 前端、视图、React 和 Tailwind；
  • 原生、框架、集成和第三方库及软件包，并附上版本、来源和 GitHub 参考链接；
  • 集成和配置变量，不含敏感值；
  • 明确的决策及其来源。

在 .specsfy/PACKAGES.md 中维护：

  • 项目清单文件和锁文件中找到的所有 npm 和 Composer 软件包，包括本地记录的传递依赖；
  • 每个软件包的包管理器、作用域、名称、版本、简要用途和来源；
  • 如果锁文件或已安装的软件包中存在声明的描述，则予以记录；
  • 当本地元数据无法证实用途时，明确发出警告。

对于 Laravel，映射路由、控制器、模型、服务、作业、策略、Blade、迁移以及 Pest/PHPUnit。对于 Node、Next.js、React 或 Astro，映射页面、API 路由、组件、模块、脚本以及 Vitest/Jest/Node Test。

限制

  • 不得复制密钥、.env 中的值、生产数据或完整代码。
  • 不得将启发式推断表述为已确认的决策。
  • 不得替换 spec、PROJECT.md 或 .specsfy/ 中由人工维护的文件。PACKAGES.md 是此技能在该目录中唯一会重建的投影，且会保留生成代码块之外的内容。
  • 构建过程不得要求联网。如果本地未声明某个软件包的 GitHub 仓库，且该仓库也不为人所知，则应发布明确标注的 GitHub 搜索链接，而不是编造 URL。

评论

支持 Markdown