# Understand

> Use when 进入一个新项目或项目结构发生重大变化，需要生成/更新架构文档（docs/ARCHITECTURE.md）。触发场景：首次接入项目、重构后文档过时、新成员需要上下文、agent 需要理解项目全貌。

- Skill: `swustcyt/understand-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add swustcyt/understand-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swustcyt/understand-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: SWUSTcyt (https://skillmd.com/u/swustcyt)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/swustcyt/understand-2

---


# Understand：项目架构分析

## 概述

深度分析当前项目的架构、技术栈、Agent 配置及工具集成，生成中文架构文档。产出的 `docs/ARCHITECTURE.md` 是后续所有开发的上下文基础。

核心原则：只写代码里真实存在的东西，不推测、不美化。

## 何时使用

- 首次进入一个项目，需要快速建立全局理解
- 项目完成重大重构后，文档与代码不再一致
- 需要为新 agent 或新成员提供项目上下文
- 何时**不用**：小幅修改、只改一个函数时不需要重跑

## 流程

1. **信息搜集**
   - 浏览项目文件结构
   - 读取 `requirements.txt` / `config.py` / `package.json` 等确定依赖
   - 用 grep 搜索关键模式（agent、tool、middleware、config 等）
   - 读取入口文件（main.py / app.py 等）理解启动流程

2. **撰写报告**
   - 加载本 Skill 目录下的 `template.md` 作为大纲
   - 所有解释性文字用中文，保留专业术语为英文
   - 代码引用必须来自真实文件，标注文件路径和行号
   - 与实际代码不一致的地方标注为「待确认」

3. **交付存档**
   - 确保 `docs/` 目录存在
   - 将内容保存为 `docs/ARCHITECTURE.md`
   - 向用户简要汇报：列出 2 个最核心的架构亮点

## 产出

- `docs/ARCHITECTURE.md`：完整中文架构文档，含系统架构图、关键代码解析、数据流、配置说明

## 常见错误

- **写过时信息** → 每次必须重新读代码，不能沿用上次的文档内容
- **引用不存在的代码** → 每段代码引用都必须确认文件实际存在
- **只写结构不写逻辑** → 架构文档不是文件列表，要解释「为什么这样设计」

## 参考

- 架构分析大纲：[template.md](template.md)