文件结构分析

技能文档

---
name: file-structure-analysis
title: 文件结构分析
description: 为架构评审、重构与迁移工作流提供代码库结构上下文。当用户需要在架构评审前了解文件组织与模块边界、探索陌生代码库并梳理目录结构、估算重构或迁移的工作量范围时使用。支持识别项目类型与根目录、映射目录布局、统计语言与文件分布、标记大文件与深层嵌套等热点。触发词：文件结构分析、目录结构、代码库结构、架构评审准备、重构范围评估、项目结构梳理。
category: 开发工具
---

# 文件结构分析

为下游的评审与重构工作流提供结构性上下文，输出文件组织、语言分布与热点文件的结构画像。

## 适用与不适用

适用：

- 架构评审前了解模块边界与文件组织
- 探索陌生代码库，在改动前映射整体结构
- 为重构或迁移工作估算范围

不适用：

- 一般性的代码探索（直接使用通用探索方式即可）
- 查找特定代码模式（应直接使用文本搜索工具）

## 技能工作流

### 步骤1：确定分析根目录

- 用 `pwd` 确认分析根目录。
- 记录 monorepo 边界、工作区根或子项目路径。
- 从清单文件（`package.json`、`Cargo.toml`、`pyproject.toml` 等）识别项目类型（语言、框架）。

### 步骤2：映射目录结构

- 运行 `tree -L 2 -d` 或 `find . -type d -maxdepth 2` 获取顶层目录布局。
- 识别标准目录：`src/`、`lib/`、`tests/`、`docs/`、`scripts/`、`configs/`。
- 记录可能影响下游分析的非标准组织方式。

### 步骤3：检测语言与文件分布

- 用 `find . -name "*.ext" | wc -l` 按扩展名统计文件数量。
- 识别主导语言及其文件分布。
- 记录配置文件、生成文件与第三方依赖目录。
- 用 `wc -l $(find . -name "*.py" -o -name "*.rs" | head -20)` 抽样文件大小。

### 步骤4：标记热点

- 识别超大文件（潜在"上帝对象"）：`find . -type f -exec wc -l {} + | sort -rn | head -10`。
- 标记可能意味着复杂度问题的深层嵌套目录。
- 记录命名或存放位置异常的文件。

### 步骤5：输出结构结论

- 汇总文件数量、目录布局与热点文件清单。
- 为下游工作流（架构评审、重构）提供可引用的结构上下文。

## 故障排查

- **命令不存在**：确认 `tree`/`find`/`wc` 等已在 PATH 中，缺失时改用等价命令组合。
- **权限错误**：检查文件与目录的读取权限。
- **结果异常**：缩小分析范围（指定子目录）后重试。

使用说明

# 文件结构分析

为架构评审、重构与迁移提供代码库结构上下文的轻量分析技能。

## 核心能力

- 识别项目类型、根目录与 monorepo 边界
- 映射目录布局，识别标准目录与非标准组织
- 统计语言与文件分布，抽样文件规模
- 标记超大文件、深层嵌套等重构热点

## 最简用法

```text
帮我梳理一下这个项目的目录结构，标记出最大的几个文件和可疑的复杂度热点。
```

```text
下周要做架构评审，先给我一份这个代码库的结构画像。
```

## 环境要求

- 类 Unix 环境（tree / find / wc 等基础命令）

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。