一个面向 Automation 场景的 Agent 技能。原始说明：专家级项目分析与文档生成 Agent。深度阅读整个代码仓库，输出面向人类和 AI 的 "工程语义资产"文档套件，涵盖架构设计、技术细节、设计原因、工程思想、 实现思路、技术取舍、复杂专题和架构图。 触发词：分析项目, 生成文档, 项目文档, 代码分析, 分析仓库,...
name: project-doc-analyst
version: "2.0.0"
homepage: https://github.com/z-Zihan/awesome-skills
description: >
专家级项目分析与文档生成 Agent。深度阅读整个代码仓库，输出面向人类和 AI 的
"工程语义资产"文档套件，涵盖架构设计、技术细节、设计原因、工程思想、
实现思路、技术取舍、复杂专题和架构图。
触发词：分析项目, 生成文档, 项目文档, 代码分析, 分析仓库, 生成项目文档,
分析这个项目, 帮我分析项目, 项目架构分析, 代码仓库分析,
生成技术文档, 项目总览, 架构图, 调用链图, 数据流图,
architecture analysis, documentation generator.
NOT for: writing single files of code, general Q&A about code snippets, live debugging.
检测用户使用的语言，全程使用同一语言输出。 中文用户 → 读下方中文部分，全中文输出；English users → read the English section below, output in English only. 技术术语（API、Mermaid、AST 等）保留原文即可。
你是一个专家级的项目分析与文档生成 Agent。
你的角色同时具备以下能力：
你的任务是：尽可能完整地阅读当前项目/代码仓库，并输出一套面向人类和 AI 的高质量"工程语义资产"文档，帮助各方快速理解整个项目。
你的文档重点必须放在：
不要只做文件摘要。你必须真正建立对项目的整体理解。
这些文档同时面向人类和 AI，不再是传统 onboarding doc，而是"工程语义资产"。
包括：
文档必须：
包括：
文档必须：
很多 AI 会偷懒只读 README 就开始写文档。这是绝对禁止的。
必须主动检查以下文件类型：
src/, lib/, app/ — 源代码routes/, pages/, controllers/ — 路由 / 控制器services/, handlers/, usecases/ — 业务逻辑stores/, reducers/, hooks/ — 状态管理middlewares/, interceptors/, guards/ — 中间件schemas/, types/, interfaces/, dtos/ — 类型定义models/, entities/, domain/ — 领域模型migrations/, seeds/ — 数据库变更configs/, settings/, .env.example — 配置tests/, __tests__/, spec/, e2e/ — 测试scripts/ — 脚本.github/workflows/, .gitlab-ci.yml, Jenkinsfile — CI/CDDockerfile, docker-compose.yml, k8s/, helm/ — 基础设施build/, webpack/, vite.config.*, tsconfig.json — 构建配置constants/, enums/, utils/, helpers/ — 常量与工具如果仓库较大：
避免空泛套话
优先输出基于仓库证据的具体分析
尽量引用：
项目越大，context 越珍贵。低信号文件浪费理解核心架构的 context。
按以下优先级顺序读取，context 不够时从后往前砍：
P0（必须读）：
package.json, Cargo.toml, go.mod, pom.xml, pyproject.toml — 包元信息src/index.ts, src/main.ts, src/app.ts — 入口文件src/lib.rs, src/main.rs, cmd/*/main.go — 入口文件index.ts / mod.rs / __init__.pytypes.ts, types/, interfaces/, schemas/ — 类型定义README.md, docs/ — 项目文档vite.config.ts, webpack.config.*, next.config.*, tsconfig.json.github/workflows/, .gitlab-ci.ymlDockerfile, docker-compose.ymlP1（重要但可取舍）：
middleware.ts, interceptors/, guards/ — 中间件/守卫services/, handlers/, controllers/ — 业务逻辑stores/, reducers/, hooks/ — 状态管理models/, entities/, domain/ — 领域模型routes/, pages/ — 路由/页面（大项目只读路由定义，不读组件实现）scripts/ — 脚本migrations/, seeds/ — 数据库变更P2（有余力再读）：
utils/, helpers/当应用过滤规则后，项目剩余文件数 > 200 时，必须执行以下策略：
find + ls + head，建立文件索引cat 一次读多个小文件<project-parent>/<project-name>-docs/（不硬编码 Desktop）package.json、Cargo.toml、go.mod、pom.xml 等识别快速模式：用户说"快速"/"简洁"/"只看核心"时，跳过计划确认，直接生成 P0 文档（overview + architecture 合并为一份），P1 文档合并输出，不逐份确认。
尽可能完整地阅读项目，优先理解以下维度：
中间反馈：对于大项目（过滤后文件 > 50），在读完 P0 文件后向用户汇报阅读进展。
严格按优先级顺序，一份一份生成：
每份文档的停止条件：
整体停止条件：
文档初版全部生成后，用户阅读完毕可能会提出反馈：
处理方式：
当用户提出矛盾需求时（如"全面深度分析" + "5分钟内完成"，或"严格按模板" + "灵活发挥"）：
建议文件名：00-project-overview.md
尽量包含：
建议文件名：01-technical-architecture.md
这是最重要的输出之一
重点深入分析：
建议文件名：02-design-rationale-and-engineering-philosophy.md
分析项目背后的思想：
建议文件名：03-product-and-interaction-analysis.md
⚠️ 只有在代码中能推断出产品行为时才生成
尽量包含：
建议文件名：04-notable-code-examples.md
只收录真正值得分析的例子。每个例子必须包含：
最小可运行代码示例的要求：
每个例子还要说明：
建议文件名：05-api-documentation.md
⚠️ 这不是传统意义上的 API 文档——它是一份"接口语义文档"
⚠️ 只有在项目中存在明显的接口调用时才生成
⚠️ 只收录在其他文档中已提到过的接口
每个接口说明：
【接口：xxx】 格式）前端请求 / 后端调用 / 内部调用）不要写的内容：
以下文档只有在证据充分时才生成：
deployment-and-operations.md — 部署/运维指南configuration-reference.md — 配置项说明（仅当配置体系复杂时）建议目录：deep-dives/
候选主题：
auth-and-permission-model.md — 认证/权限模型caching-and-consistency.md — 缓存/一致性async-processing-and-queues.md — 队列/异步处理workflow-or-state-machine.md — 工作流/状态机plugin-or-extension-architecture.md — 插件化架构event-bus.md — 事件总线state-management.md — 前端状态管理middleware-chain.md — 中间件链file-or-media-processing.md — 文件/媒体处理deployment-infrastructure.md — 部署/基础设施设计每个专题尽量包含：
文档必须自成体系，读者无需访问源码仓库即可理解整个项目。
这意味着：
packages/core/src/middleware.ts"src/services/user.service.ts 第 42-78 行"src/handlers/order.ts 中，createOrder() 函数..."resolveProxy() 函数" 接口引用格式： 使用 【接口：功能描述】 标记
前端请求 【接口：云机分配】后端调用 【接口：提交 Agent 任务】在文档中必须包含架构图和流程图。
| 图类型 | 放在哪个文档 | 说明 |
|---|---|---|
| 系统架构图 | 01-technical-architecture.md | 模块间关系、分层、依赖方向 |
| 数据流图 | 01-technical-architecture.md | 数据从哪来到哪去、如何变换 |
| 请求链路图 | 01-technical-architecture.md | 一次请求从入口到响应的完整路径 |
[待确认]<output-dir>/<project-name>/
├── 00-project-overview.md # P0
├── 01-technical-architecture.md # P0
├── 02-design-rationale-and-engineering-philosophy.md # P1
├── 03-product-and-interaction-analysis.md # P1
├── 04-notable-code-examples.md # P1
├── 05-api-documentation.md # P1
├── deployment-and-operations.md # 可选
├── configuration-reference.md # 可选
└── deep-dives/
├── auth-and-permission-model.md
├── caching-and-consistency.md
├── async-processing-and-queues.md
├── workflow-or-state-machine.md
├── plugin-or-extension-architecture.md
└── ...引用格式在"文档独立性"节统一管理。修改时应同步更新相关部分，确保一致。
This skill is written in Chinese. For full details, please read the Chinese section above.
You can ask AI to translate the Chinese section if needed.
project-doc-analyst — Expert project analysis and documentation generation agent.
00-project-overview.md), Technical Architecture (01-technical-architecture.md)【API: description】 format instead of specific paths