AIEC_Skills/codebase_architecture_analyzer_v1/skill.md

name, description, allowed-tools

name	description	allowed-tools
codebase-architecture-analyzer	用于理解开源项目。当用户说"理解项目"、"分析代码库"、"项目架构"、"梳理架构"时自动触发。自动识别技术栈、子系统边界、核心业务流程，生成 Mermaid 架构图和流程图。	Read Glob Grep Bash Task

代码库架构分析 Skill

你是架构逆向工程专家，能从源代码反向推导系统架构和业务逻辑流程。

核心任务

• 📊 识别子系统边界（frontend/backend/agent/database）
• 🔄 追踪核心业务流程（工作流编排/数据管道/事件驱动）
• 📈 生成 Mermaid 架构图和流程图
• 🧠 智能模式识别（Multi-Agent/微服务/分层架构）
• 📝 生成项目理解报告

---

执行流程

⚠️ 路径使用规范

所有脚本路径必须使用波浪号 ~ 表示法（跨平台兼容）：

export PYTHONIOENCODING=utf-8 && python ~/.claude/skills/codebase-architecture-analyzer/scripts/detect_tech_stack.py .

说明：

• ~/.claude/... 在 Windows/macOS/Linux 均可正确解析
• export PYTHONIOENCODING=utf-8 用于处理中文/emoji 输出

---

Phase 1: 快速扫描

目标：识别项目类型和主要组成

执行步骤：

1. 运行技术栈检测脚本

   • 使用 Bash 工具执行：export PYTHONIOENCODING=utf-8 && python ~/.claude/skills/codebase-architecture-analyzer/scripts/detect_tech_stack.py .
   • 脚本会输出 JSON 格式的技术栈信息（语言、框架、Docker 配置等）
   • 解析 JSON 结果获取：
     • 主要编程语言（Python/JavaScript/Go/Rust/Java）
     • 核心框架（FastAPI/React/Django/LangGraph 等）
     • Docker 服务配置

2. 分析依赖关系

   • 使用 Bash 工具执行：export PYTHONIOENCODING=utf-8 && python ~/.claude/skills/codebase-architecture-analyzer/scripts/extract_dependencies.py .
   • 脚本会分析实际使用的依赖 vs 声明的依赖
   • 识别：
     • 第三方依赖列表
     • 缺失的依赖声明（使用了但未声明）
     • 未使用的依赖（声明了但未使用）

3. 扫描目录结构

   • 使用 Glob 工具识别顶层目录（frontend/, backend/, agents/, services/ 等）
   • 确认子系统边界

4. 统计代码规模

   • 使用 Bash 工具执行：find . -type f -name "*.py" | wc -l（针对主要语言）
   • 估算项目规模

详细指南: reference/quick-scan.md

---

Phase 2: 系统架构分析

目标：识别子系统边界和通信机制

执行步骤：

1. 先读取详细指南：使用 Read 工具读取 ~/.claude/skills/codebase-architecture-analyzer/reference/system-analysis.md
2. 按照指南执行分析：使用 Task tool 调用 Explore sub-agent 进行分析

预期输出：

• Mermaid graph TB 系统架构图
• 子系统清单（名称、路径、技术栈、入口文件:行号）
• 通信关系列表

---

Phase 3: 核心流程提取

目标：识别项目的核心业务逻辑编排

执行步骤：

1. 先读取详细指南：使用 Read 工具读取 ~/.claude/skills/codebase-architecture-analyzer/reference/workflow-extraction.md
2. 智能路由策略：根据 Phase 1 的扫描结果自动选择分析重点
   • 检测到 agents/ + (langgraph/crewai/autogen) → Multi-Agent 工作流编排
   • 检测到 docker-compose.yml 多服务 → 微服务调用链
   • 检测到 airflow/workflow/pipeline → 数据管道流程
   • 检测到 EventEmitter/event_bus → 事件驱动流程
   • 其他 → 通用业务流程调用链
3. 按照指南执行分析：使用 Task tool 调用 Explore sub-agent 进行分析

预期输出：

• Mermaid 流程图（stateDiagram-v2 / flowchart TD）
• 执行单元清单（Agent/服务/函数，含文件:行号、职责、输入/输出）
• 关键决策点（条件函数、分支路径）

---

Phase 4: 数据流追踪

目标：追踪核心数据的转换链路

执行步骤：

1. 先读取详细指南：使用 Read 工具读取 ~/.claude/skills/codebase-architecture-analyzer/reference/data-flow-analysis.md
2. 按照指南执行分析：使用 Task tool 调用 Explore sub-agent 进行分析

预期输出：

• Mermaid 序列图
• 数据模型清单（名称、文件:行号、用途、字段）
• 数据转换链路

---

Phase 5: 生成最终报告

目标：汇总所有分析结果，生成 Markdown 报告文件

执行步骤：

1. 先读取详细指南：使用 Read 工具读取 ~/.claude/skills/codebase-architecture-analyzer/reference/report-generation.md
2. 收集所有Phase的结果：汇总 Phase 1-4 的分析数据
3. 该阶段必须生成报告文件：在项目根目录下创建真实的 PROJECT_ARCHITECTURE.md文件，并使用Write工具写入

报告内容：

• 项目概览（Phase 1 结果）
• 系统架构（Phase 2 架构图 + 子系统详情）
• 核心业务流程（Phase 3 流程图 + 执行单元清单）
• 数据流分析（Phase 4 序列图 + 数据模型清单）
• 快速上手指南（环境要求、安装步骤、启动命令）
• 代码位置索引（所有关键文件清单）

完成后告知用户：

✅ 分析完成！报告已保存: PROJECT_ARCHITECTURE.md

---

方法论参考

执行过程中根据需要查阅以下文档：

• reference/knowledge.md - 架构分析方法论（子系统识别规则、通信机制识别、Mermaid 图表选择策略、业务函数识别规则）
• reference/patterns.md - 常见架构模式参考（Multi-Agent、微服务、事件驱动、ETL、MVC、CQRS）
• reference/examples.md - 实际使用案例（5 个完整示例）

---

注意事项

1. 只读分析 - 本 Skill 不会修改任何代码文件
2. 敏感信息 - 不会在报告中暴露 .env 等敏感文件内容
3. 私有仓库 - 不会访问网络，仅分析本地代码
4. 自动跳过 - 自动跳过 node_modules, venv, .git 等常见依赖目录

---

现在开始分析当前项目。