mcpField
P
project-architecture-report

project-architecture-report

github.com/gil-1开发0272 次安装10 周前更新
代码仓库

关于 project-architecture-report

用于分析代码库并生成独立 HTML 架构报告的 Skill，引导 Agent 梳理项目结构、运行流程、数据、依赖、风险及后续需求。

主要功能

  1. 01内置项目清单脚本
  2. 02分析架构与运行流程
  3. 03梳理数据模型和依赖
  4. 04生成包含指定章节的 HTML 报告
  5. 05报告验证清单

适用场景

  1. 01记录陌生代码库的架构
  2. 02追踪请求、任务或 CLI 流程
  3. 03识别代码库风险与缺口

安装

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

$npx skills add https://github.com/gil-1/skills --skill project-architecture-report

安装后在 Claude Code 中输入/project-architecture-report确认已加载。

附带文件agents/openai.yamlscripts/project-inventory.mjs

详细介绍

项目架构报告

分析项目并生成一份实用的 HTML 文件。报告应帮助读者快速了解项目包含哪些内容、如何运作、有哪些问题，以及代码库接下来可能需要什么。

快速开始

运行随附的清单脚本，然后将发现整理成独立的 HTML 报告：

node scripts/project-inventory.mjs --root /path/to/project --out .scratch/project-inventory.json

默认报告路径：.scratch/project-architecture-report.html。

工作流

  1. 确定范围和报告路径。如果未指定，请检查当前仓库并写入 .scratch/project-architecture-report.html。
  2. 阅读本地事实来源：AGENTS.md、CLAUDE.md、README.md、CONTEXT.md、ADR、清单文件、环境示例、CI、测试、部署配置、文档，以及工单/PRD 资料。
  3. 运行 project-inventory.mjs。如果可用，请补充项目原生映射：路由列表、数据库架构、OpenAPI/GraphQL 架构、迁移历史、包依赖图、测试依赖图、构建依赖图和生成的客户端。
  4. 在有帮助时，将宽泛的分析拆分为独立的子 Agent 问题：结构/依赖、运行时流程、数据/存储、UI/API 表面、测试/工具，以及风险/缺口检测。主 Agent 负责最终报告并解决冲突。
  5. 从入口追踪到状态和副作用：用户流程、请求流程、后台任务、CLI 命令、身份验证/会话路径、存储写入、外部 API 和错误路径。
  6. 识别依赖：运行时依赖、开发/构建依赖、内部包、生成代码、外部服务、浏览器/运行时假设、环境变量和隐藏的运维耦合。
  7. 梳理数据模型：持久化实体、内存状态、文件、缓存、队列、事件、架构、迁移、验证规则、所有权和生命周期。
  8. 编写 HTML，不使用外部依赖，除非用户允许。包括 CSS、目录、便于浏览的卡片/表格、纯路径形式的代码路径链接、内嵌 Mermaid 源码或简单 HTML/CSS 流程块形式的图表，以及下一步需求建议。
  9. 验证：报告文件存在、可在本地打开、不含失效的本地资源引用，并且包含下方指定的全部章节。

必需的 HTML 章节

  • 概览：项目用途、当前形态、可能的需求
  • 架构映射：包、应用、入口点、模块、所有权
  • 运行时流程：主要的用户/请求/任务/CLI 流程
  • 数据模型：实体、状态、持久化、架构、生命周期
  • 依赖：包依赖、外部服务、工具、环境变量
  • 代码清单：文件、符号、路由、测试、脚本、生成路径
  • 痛点：重复、浅层模块、遗留内容、缺失的测试、高风险耦合
  • 需求映射：保留/更改/删除、改进切片、待解答问题
  • 附录：运行的命令、生成的清单路径、假设、缺口

风格

简洁但完整。优先使用准确路径、表格和流程步骤，而不是叙述性文字。将不确定之处标记为 Needs evidence。

评论

支持 Markdown