# Project Retrospective

> 在 Claude Code / Codex 完成一个项目后，自动生成带图文的项目复盘总结文档。 输出包含技术架构图（Mermaid）、函数调用关系图、文件目录结构、函数详解、 遇到的难点与解决方案、使用的插件与工具、后续优化建议的完整 Markdown + HTML 报告。 当用户说以下任何内容时必须触发此 skill： - "帮我写项目总结 / 项目复盘 / 项目报告" - "生成这个项目的文档 / 技术文档" - "把这次 claude code 交互总结一下" - "整理项目结构 / 函数关系 / 技术架构" - "写一份带图的项目说明" - 提到 codex、claude code 完成了某个项目并需要记录 即使用户只是上传了项目目录或代码文件并说"帮我梳理一下"，也应主动触发此 skill。

- Skill: `iapplegenius/project-retrospective` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add iapplegenius/project-retrospective`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iapplegenius/project-retrospective/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: iapplegenius (https://skillmd.com/u/iapplegenius)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/iapplegenius/project-retrospective

---


# Project Retrospective Skill

## 概述

本 skill 用于对刚完成的开发项目进行全面复盘，生成图文并茂的总结文档，供开发者存档、交接或分享。

**输出物：**
1. `retrospective_<project_name>.md` — 结构化 Markdown 复盘文档（含 Mermaid 图）
2. `retrospective_<project_name>.html` — 可独立打开的美观 HTML 版本

---

## Step 0：信息收集

在开始生成之前，先收集以下信息（优先从上下文/已有文件自动提取，缺失时才询问用户）：

### 自动提取（优先）
- 扫描项目目录结构（`find . -type f` 或 `ls -R`）
- 读取 `README.md`、`package.json`、`requirements.txt`、`pyproject.toml`、`Cargo.toml` 等配置文件
- 分析主要源码文件，提取函数/类定义
- 从对话历史中提取遇到的错误、解决方案、关键决策

### 需要用户补充（如上下文缺失）
询问以下问题（一次性问完，不要分多轮）：
1. 项目名称和一句话介绍是什么？
2. 这次开发中遇到了哪些印象最深的难点？
3. 有哪些你认为值得记录的设计决策？
4. 后续打算在哪些方向继续优化？

---

## Step 1：分析项目

### 1.1 文件结构分析
```bash
# 获取文件树（忽略 node_modules / .git / __pycache__ 等）
find . -type f \
  -not -path '*/.git/*' \
  -not -path '*/node_modules/*' \
  -not -path '*/__pycache__/*' \
  -not -path '*/.venv/*' \
  | sort
```

### 1.2 函数/类提取
根据语言选择合适的分析方式：
- **Python**: 扫描 `def ` 和 `class ` 定义，结合 docstring
- **JavaScript/TypeScript**: 扫描 `function`、`const xx = () =>`、`class`
- **Rust/Go**: 扫描 `fn `、`func `
- **通用**: 读取核心文件，手动识别关键函数

### 1.3 依赖/插件提取
- Python: `requirements.txt` / `pyproject.toml` / `setup.py`
- Node.js: `package.json` → `dependencies` + `devDependencies`
- Rust: `Cargo.toml`
- Go: `go.mod`

---

## Step 2：生成 Markdown 文档

按以下模板填充内容，存为 `retrospective_<project_name>.md`：

```markdown
# 项目复盘：<项目名称>

> **完成时间**：<日期>  
> **技术栈**：<主要语言 + 框架>  
> **一句话描述**：<项目功能简介>

---

## 1. 项目概述

<2-4 段描述项目背景、目标、核心功能>

---

## 2. 技术架构

<整体架构说明文字>

```mermaid
graph TD
    A[入口 / main] --> B[模块A]
    A --> C[模块B]
    B --> D[子功能1]
    B --> E[子功能2]
    C --> F[数据层]
    D --> F
    E --> F
    F --> G[(存储/外部API)]
```

---

## 3. 文件目录结构

```
project/
├── src/
│   ├── main.py          # 程序入口
│   ├── module_a.py      # 模块A：功能描述
│   └── module_b.py      # 模块B：功能描述
├── tests/
├── requirements.txt
└── README.md
```

---

## 4. 函数调用关系

```mermaid
sequenceDiagram
    participant Main
    participant ModuleA
    participant ModuleB
    participant Storage

    Main->>ModuleA: init()
    ModuleA->>ModuleB: process(data)
    ModuleB->>Storage: save(result)
    Storage-->>ModuleB: ok
    ModuleB-->>Main: done
```

---

## 5. 核心函数详解

### `函数名(参数)` — 所在文件

**功能**：<一句话描述>  
**参数**：
- `参数名` (类型): 含义

**返回值**：<描述>  
**关键逻辑**：<说明核心实现思路，不要照抄代码，用文字解释>

<为每个核心函数重复以上结构>

---

## 6. 开发难点与解决方案

### 难点 1：<标题>

**问题描述**：<遇到了什么问题>  
**尝试过的方案**：<失败的尝试，帮助后来者避坑>  
**最终解决方案**：<如何解决的>  
**经验总结**：<一句话提炼>

<为每个难点重复>

---

## 7. 使用的工具与插件

| 工具/库 | 版本 | 用途 | 文档链接 |
|---------|------|------|---------|
| <工具名> | <版本> | <用途> | <链接> |

---

## 8. 与 AI Agent 的交互亮点

<记录本次和 Claude Code / Codex 配合中值得记录的交互模式、有效的 prompt 技巧、AI 帮助解决了哪些具体问题>

---

## 9. 后续优化方向

| 优先级 | 方向 | 说明 | 预估工作量 |
|--------|------|------|-----------|
| 🔴 高 | <方向> | <说明> | <小/中/大> |
| 🟡 中 | <方向> | <说明> | <小/中/大> |
| 🟢 低 | <方向> | <说明> | <小/中/大> |

---

## 10. 总结

<3-5 段总结性文字：这个项目最大的收获是什么、技术上学到了什么、下次会怎么做得更好>
```

---

## Step 3：生成 HTML 文档

参考 `assets/html_template.html` 的结构，将 Markdown 内容渲染为美观的 HTML。

**HTML 要求：**
- 自包含（所有 CSS/JS 内联，无外部依赖，可离线打开）
- 使用 [Mermaid.js CDN](https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js) 渲染图表
- 深色代码块（类似 GitHub 风格）
- 侧边栏目录导航（锚点跳转）
- 响应式布局，打印友好
- 顶部显示项目名称、日期、技术栈 Badge

具体 HTML 模板见 `assets/html_template.html`，基于此模板填充内容。

---

## Step 4：质量检查

生成完成后，自检以下项目：

- [ ] Mermaid 图表语法正确（至少包含架构图 + 函数调用图）
- [ ] 每个核心函数都有详解（不遗漏主要函数）
- [ ] 难点至少记录 1 条（如对话中有报错/重试，必须记录）
- [ ] 工具表格填写完整（版本号尽量准确）
- [ ] 后续优化方向至少 3 条
- [ ] HTML 可独立打开（无外部字体依赖以外）
- [ ] 文件命名：`retrospective_<snake_case_project_name>.md/html`

---

## Step 5：输出

1. 将 `.md` 和 `.html` 文件保存到 `/mnt/user-data/outputs/`
2. 使用 `present_files` 工具将两个文件呈现给用户
3. 简短说明："已生成项目复盘文档，MD 版本可直接提交到仓库，HTML 版本可在浏览器中查看完整图文报告。"

---

## 注意事项

- **不要照抄代码**：函数详解用文字描述逻辑，代码只做少量引用说明
- **Mermaid 语法**：使用 `graph TD`（流程图）和 `sequenceDiagram`（时序图），避免使用较新的语法以确保兼容性
- **如果项目很小**（<5个文件）：合并第4、5节，精简输出
- **如果项目很大**（>50个文件）：只对核心模块做函数详解，其他模块做摘要
- **语言**：默认用中文输出，除非用户指定英文