understand

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

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