proj-mini

proj-mini — 小型项目理解与分析 Skill

触发条件

当用户需要理解一个项目的整体结构和功能细节时激活：

• "帮我理解这个项目"
• "分析一下这个项目的架构"
• "这个项目是干什么的？"
• "帮我理清这个代码库的结构"
• "explain this project"
• "help me understand this codebase"

或者用户直接指定项目路径时激活。

---

核心流程

1. 项目全景扫描 ── 了解项目基本信息和整体结构
          ↓
2. 功能模块分析 ── 逐模块解读，识别职责和边界
          ↓
3. 数据流追踪   ── 追踪关键数据在模块间的流转
          ↓
4. 知识整合输出 ── 产出结构化的项目理解报告

---

步骤说明

1. 项目全景扫描

在开始详细分析前，先全面了解项目的基本情况。

1a. 识别项目根目录

• 如果用户指定了路径，以该路径为准
• 如果用户没有指定，尝试推断当前上下文中的项目目录（默认使用当前工作目录）

1b. 扫描顶层结构

查看项目根目录的文件和目录分布：

ls -la                              # 顶层文件和目录
find . -maxdepth 2 -type d | sort   # 二级目录结构

1c. 检测项目元信息

根据项目中的配置文件识别项目的性质：

检测内容	方法	产出信息
项目描述	README.md / CLAUDE.md	项目定位、功能概述
依赖声明	package.json / Cargo.toml / pyproject.toml / go.mod / Gemfile	技术栈、框架、外部依赖
构建配置	Makefile / Dockerfile / .github/workflows	构建方式
入口文件	src/main.py / bin/ / cmd/ / main.go / index.js	启动入口
测试框架	tests/ / spec/ / tests/	测试策略
代码量	find . -name '*.py' | xargs wc -l 等	项目规模

1d. 输出全景扫描结果

## 项目全景

| 字段 | 内容 |
|------|------|
| 项目名称 | [名称] |
| 项目定位 | [从 README/代码推断的描述] |
| 技术栈 | [编程语言、框架、关键依赖] |
| 项目规模 | [约 XX 行代码] |
| 入口文件 | [文件路径] |
| 测试工具 | [使用的测试框架] |
| 目录结构 | [观察到的顶层目录分布] |

---

2. 功能模块分析

将项目拆解为功能模块，逐个分析。

2a. 识别模块边界

根据目录结构、命名空间、包边界来划分模块。例如：

项目名称/
├── src/
│   ├── parser/        → 解析模块
│   ├── transformer/   → 转换模块
│   ├── output/        → 输出模块
│   └── utils/         → 工具模块
├── tests/
│   ├── test_parser/   → 解析模块测试
│   └── test_output/   → 输出模块测试

常见的模块类型包括但不限于：

• 核心逻辑 — 项目核心功能的实现
• CLI/接口层 — 用户交互入口
• 数据处理 — 数据解析、转换、验证
• 存储层 — 数据持久化
• 工具/辅助 — 公用工具函数
• 配置管理 — 项目配置处理
• 插件/扩展 — 可扩展接口

2b. 逐个模块分析

对每个模块，查看其关键文件和核心逻辑：

# 查看模块内的文件结构
find src/parser -type f | sort

# 查看核心文件的内容
cat src/parser/main.py

分析要点：

• 模块的职责和功能是什么？
• 模块提供了哪些对外接口/API？
• 模块内部的关键类和函数有哪些？
• 模块是否依赖其他模块？

2c. 输出模块分析

每个模块的输出格式：

### 模块：[模块名]

**职责**: [一句话描述]

**关键文件**:
- `path/to/file.py` — 核心逻辑，实现了 [X] 功能
- `path/to/types.py` — 类型定义

**对外接口**:
- `function_a()` — 做 X
- `ClassB.method()` — 做 Y

**依赖**: [依赖的其他模块/外部库]

**被依赖**: [哪些模块依赖本模块]

---

3. 数据流追踪

追踪关键数据在模块之间的流转路径。

3a. 识别核心数据模型

找出项目中的核心数据结构：

# 搜索类定义、类型定义、接口定义
grep -rn "class " src/ --include="*.py" | head -20
grep -rn "type " src/ --include="*.go" | head -20
grep -rn "interface " src/ --include="*.ts" | head -20

3b. 追踪数据流向

对每个核心数据模型，回答：

1. 数据从哪里来？ — 用户输入、文件读取、网络请求、数据库查询？
2. 经过哪些处理？ — 验证、转换、过滤、聚合？
3. 最终到哪里去？ — 文件输出、API 返回、数据库写入、展示给用户？

3c. 输出数据流

## 数据流

### 核心数据模型

- **[模型名]** — 用于 [用途]
  - 例：[数据样例]

### 主流程

用户输入 → [模块A] → [模块B] → [模块C] → 输出结果 ↓ [模块D]（辅助处理）

### 详细路径

1. **输入阶段**: 用户提供 [X]，经 [模块] 解析为 [数据结构]
2. **处理阶段**: [数据结构] 经过 [模块] 的 [处理函数]，转换为 [中间结果]
3. **输出阶段**: [中间结果] 通过 [模块] 输出为 [最终格式]

---

4. 知识整合输出

将 2、3 步的分析结果整合为一份结构清晰的项目理解报告。

输出格式

## 项目理解报告：[项目名称]

---

### 项目概述

[2-3 句话概括项目：做什么、用什么做、给谁用]

### 技术栈

| 类别 | 技术选型 |
|------|---------|
| 语言 | |
| 运行时 | |
| 框架/库 | |
| 基础设施 | |

### 项目规模

| 指标 | 数值 |
|------|------|
| 总代码行数 | |
| 源文件数 | |
| 模块数 | |
| 测试覆盖率 | （仅当有工具可测时） |

### 目录结构

[精简后的项目目录树，排除 node_modules、.git、pycache 等]

### 功能模块

[来自步骤 2 的模块分析输出]

### 数据流

[来自步骤 3 的数据流分析输出]

### 核心功能详解

对项目中最重要的 1-3 个功能做深入说明：

#### 功能 1：[功能名]

**实现路径**: [关键文件的调用链]
**关键代码片段**: [截取能说明核心逻辑的代码]
**设计要点**: [做了什么设计决策、为什么]

#### 功能 2：...

### 入口说明

如果项目有 CLI/API/UI 等入口：

运行方式

[核心命令和参数]

典型用法

[示例命令]

### 要点与建议

- 项目中值得注意的设计模式或约定
- 可能存在改进空间的地方（可选，AI 的判断）
- 理解该项目需要特别留意的部分

---

通用指令

搜索策略

分析过程中，使用以下策略高效定位信息：

1. 先目录后文件 — 先看目录结构了解全貌，再深入关键文件
2. 抓大放小 — 优先分析核心模块，辅助模块概要说明即可
3. 按重要度递减 — 入口文件 → 核心逻辑 → 数据处理 → 工具函数
4. 主动发现而非被动等待 — 不必等用户指定看什么，AI 自己决定分析路径

代码阅读原则

• 只看必要代码 — 不要输出完整文件内容
• API/接口看签名，实现细节看关键逻辑
• 配置文件和样板代码可以概要说明，不用逐行解读

不确定处理的策略

如果遇到以下情况：

• 检测到多种语言 — 分别说明各语言在项目的角色
• 项目过大 — 只分析核心模块，标注"因文件较多，以下仅分析核心模块"
• 未找到明显模块边界 — 按文件功能分组，标注"推测的模块划分"
• 依赖无法解析 — 列出检测到的依赖声明，但不做无效推断

所有不确定性要明确标注，不要假装确定。