Back to Details

file-analysis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

File Analysis

文件分析

When To Use

适用场景

  • Before architecture reviews to understand module boundaries and file organization.
  • When exploring unfamiliar codebases to map structure before making changes.
  • As input to scope estimation for refactoring or migration work.
  • 架构审查前，用于了解模块边界和文件组织结构。
  • 探索陌生代码库时，在进行修改前梳理结构。
  • 作为重构或迁移工作范围估算的输入依据。

When NOT To Use

不适用场景

  • General code exploration - use the Explore agent
  • Searching for specific patterns - use Grep directly
  • 通用代码探索——请使用Explore Agent
  • 搜索特定模式——请直接使用Grep

Required TodoWrite Items

必备TodoWrite任务项

  1. file-analysis:root-identified
  2. file-analysis:structure-mapped
  3. file-analysis:patterns-detected
  4. file-analysis:hotspots-noted
Mark each item as complete as you finish the corresponding step.
  1. file-analysis:root-identified
  2. file-analysis:structure-mapped
  3. file-analysis:patterns-detected
  4. file-analysis:hotspots-noted
完成对应步骤后，标记每个任务项为已完成。

Step 1: Identify Root (
file-analysis:root-identified
)

步骤1：确定根目录（
file-analysis:root-identified
）

  • Confirm the analysis root directory with 
    pwd
    .
  • Note any monorepo boundaries, workspace roots, or subproject paths.
  • Capture the project type (language, framework) from manifest files (
    package.json
    , 
    Cargo.toml
    , 
    pyproject.toml
    , etc.).
  • 使用
    pwd
    命令确认分析的根目录。
  • 记录任何单体仓库边界、工作区根目录或子项目路径。
  • 从清单文件（
    package.json
    、
    Cargo.toml
    、
    pyproject.toml
    等）中识别项目类型（语言、框架）。

Step 2: Map Structure (
file-analysis:structure-mapped
)

步骤2：梳理结构（
file-analysis:structure-mapped
）

  • Run 
    tree -L 2 -d
    or 
    find . -type d -maxdepth 2
    to capture the top-level directory layout.
  • Identify standard directories: 
    src/
    , 
    lib/
    , 
    tests/
    , 
    docs/
    , 
    scripts/
    , 
    configs/
    .
  • Note any non-standard organization patterns that may affect downstream analysis.
  • 运行
    tree -L 2 -d
    或
    find . -type d -maxdepth 2
    命令捕获顶级目录布局。
  • 识别标准目录：
    src/
    、
    lib/
    、
    tests/
    、
    docs/
    、
    scripts/
    、
    configs/
    。
  • 记录任何可能影响后续分析的非标准组织模式。

Step 3: Detect Patterns (
file-analysis:patterns-detected
)

步骤3：检测模式（
file-analysis:patterns-detected
）

  • Use 
    find . -name "*.ext" | wc -l
    to count files by extension.
  • Identify dominant languages and their file distributions.
  • Note configuration files, generated files, and vendored dependencies.
  • Run 
    wc -l $(find . -name "*.py" -o -name "*.rs" | head -20)
    to sample file sizes.
  • 使用
    find . -name "*.ext" | wc -l
    命令按文件扩展名统计文件数量。
  • 识别主导语言及其文件分布情况。
  • 记录配置文件、生成文件和第三方依赖文件。
  • 运行
    wc -l $(find . -name "*.py" -o -name "*.rs" | head -20)
    命令抽样查看文件大小。

Step 4: Note Hotspots (
file-analysis:hotspots-noted
)

步骤4：标记热点（
file-analysis:hotspots-noted
）

  • Identify large files (potential "god objects"): 
    find . -type f -exec wc -l {} + | sort -rn | head -10
    .
  • Flag deeply nested directories that may indicate complexity.
  • Note files with unusual naming conventions or placement.
  • 识别大文件（潜在的“上帝对象”）：
    find . -type f -exec wc -l {} + | sort -rn | head -10
    。
  • 标记可能表明复杂度高的深层嵌套目录。
  • 记录具有不寻常命名规范或放置位置的文件。

Exit Criteria

退出标准

  • TodoWrite
    items are completed with concrete observations.
  • Downstream workflows (architecture review, refactoring) have structural context.
  • File counts, directory layout, and hotspots are documented for reference.
  • TodoWrite任务项已完成并记录具体观察结果。
  • 后续工作流（架构审查、重构）已获取结构上下文。
  • 文件数量、目录布局和热点已记录归档，以供参考。

Troubleshooting

故障排除

Common Issues

常见问题

Command not found Ensure all dependencies are installed and in PATH
Permission errors Check file permissions and run with appropriate privileges
Unexpected behavior Enable verbose logging with 
--verbose
flag
命令未找到 确保所有依赖项已安装并在PATH环境变量中
权限错误 检查文件权限并使用适当权限运行命令
异常行为 使用
--verbose
标志启用详细日志