SKILL.md

Skill 名称

项目快速理解与文档梳理 Skill

1. Skill 目标

当接手一个由 AI 或人工开发的项目时，本 Skill 用于帮助开发者快速理解项目全貌。

目标不是逐行解释所有代码，而是在较短时间内建立一份清晰的“项目地图”，让人能够快速知道：

• 这个项目是做什么的
• 当前实现了哪些功能
• 使用了哪些技术
• 项目如何启动和部署
• 数据库表结构是什么
• 核心业务流程在哪里
• 复杂逻辑如何运转
• 当前有哪些遗留问题、技术债和风险

最终输出一组标准化 Markdown 文档，帮助人类开发者、产品负责人或后续 AI Agent 快速接手项目。

2. 适用场景

本 Skill 适用于以下场景：

1. AI 生成了一批代码，但用户希望快速了解项目整体情况。
2. 用户接手一个陌生项目，需要快速梳理结构。
3. 项目代码越来越多，需要生成或更新项目说明文档。
4. Codex / Claude Code / Cursor 完成开发后，需要同步维护项目文档。
5. 项目准备交接，需要整理技术栈、功能清单、数据表、接口和遗留问题。
6. 用户不想逐行看代码，但希望掌握关键逻辑和风险点。

3. 核心原则

3.1 先建立项目地图，再深入代码

不要一开始就逐行阅读代码。

优先理解：

1. 项目目标
2. 技术栈
3. 目录结构
4. 数据表
5. API 接口
6. 核心业务流程
7. 遗留问题

3.2 文档要能帮助人快速接手

所有输出文档必须清晰、具体、可执行。

避免空泛描述，例如：

不推荐：

本项目使用现代化技术实现业务功能。

推荐：

本项目后端使用 Python FastAPI，数据库使用 SQLite，前端使用微信小程序原生框架，AI 能力通过 DashScope API 调用 Qwen 模型。

3.3 不要只描述代码文件，要解释业务意义

例如不要只写：

services/generation.py 负责生成逻辑。

应该写：

services/generation.py 负责 AI 生成任务的核心流程，包括创建任务、组装提示词、调用模型、保存生成结果、处理失败状态。

3.4 数据库结构优先级很高

数据库结构往往最能反映项目真实业务能力。

必须重点梳理：

• 有哪些表
• 每张表的用途
• 核心字段含义
• 表之间的关系
• 业务数据如何流转

3.5 必须记录不确定性

如果代码中没有明确实现，不要猜测为已完成。

应该明确标记：

状态：未发现完整实现 / 仅发现前端页面 / 仅发现接口定义 / 需要进一步确认

4. 输入要求

执行本 Skill 时，优先读取以下内容：

README.md
PROJECT_MAP.md
AGENTS.md
package.json
pyproject.toml
requirements.txt
go.mod
Cargo.toml
docker-compose.yml
Dockerfile
.env.example
src/
app/
backend/
frontend/
server/
models/
migrations/
routes/
api/
services/
controllers/
pages/

如果项目中已经存在文档，需要先阅读已有文档，再根据代码进行校验和补充。

5. 推荐阅读顺序

分析项目时，请按以下顺序进行：

1. README.md
2. PROJECT_MAP.md / AGENTS.md / docs 目录
3. package.json / pyproject.toml / go.mod / requirements.txt
4. docker-compose.yml / Dockerfile / .env.example
5. 项目目录结构
6. 数据库模型 / migrations / ORM models
7. API 路由定义
8. service / business / core 目录下的核心逻辑
9. 前端页面 / 组件 / 状态管理
10. 测试文件 / scripts / 部署脚本
11. TODO / FIXME / issue / error handling

6. 必须输出的文档

执行本 Skill 后，建议在项目中生成或更新以下文件：

README.md
PROJECT_MAP.md
AGENTS.md
docs/
  01_PROJECT_OVERVIEW.md
  02_TECH_STACK.md
  03_ARCHITECTURE.md
  04_DATABASE_SCHEMA.md
  05_API_SPEC.md
  06_CORE_LOGIC.md
  07_KNOWN_ISSUES.md
  08_CHANGELOG.md

如果项目较小，可以至少生成：

README.md
PROJECT_MAP.md
docs/DATABASE_SCHEMA.md
docs/CORE_LOGIC.md
docs/KNOWN_ISSUES.md

7. 文档一：README.md

目标

帮助开发者快速知道项目是什么、如何启动、如何配置。

必须包含

# 项目名称

## 1. 项目简介

简要说明项目用途、目标用户和核心价值。

## 2. 当前功能

- 功能 A
- 功能 B
- 功能 C

## 3. 技术栈

- 前端：
- 后端：
- 数据库：
- AI 能力：
- 文件存储：
- 部署方式：

## 4. 本地启动

### 4.1 安装依赖

```bash
# 示例
npm install
# 或
pip install -r requirements.txt

4.2 配置环境变量

cp .env.example .env

4.3 启动项目

# 示例
npm run dev
# 或
uvicorn main:app --reload
# 或
docker compose up -d

5. 重要目录说明

src/          # 主要源码
api/          # 接口路由
models/       # 数据模型
services/     # 业务逻辑
pages/        # 前端页面

6. 常见问题

• 问题 1：
• 问题 2：

---

## 8. 文档二：PROJECT_MAP.md

### 目标

这是最重要的项目地图文档。  
用户应当通过这个文件快速了解整个项目。

### 模板

```md
# 项目地图

## 1. 项目一句话介绍

本项目是一个……

## 2. 当前项目状态

- 当前阶段：MVP / 开发中 / 可上线 / 重构中
- 当前完成度：
- 最近主要修改：

## 3. 技术栈总览

| 层级 | 技术 | 说明 |
|---|---|---|
| 前端 |  |  |
| 后端 |  |  |
| 数据库 |  |  |
| 缓存 |  |  |
| AI 模型 |  |  |
| 文件存储 |  |  |
| 部署 |  |  |

## 4. 项目目录结构

```bash
.
├── frontend/
├── backend/
├── docs/
├── scripts/
├── docker-compose.yml
└── README.md

5. 已实现功能

用户端

• [x] 功能 A
• [x] 功能 B
• [ ] 功能 C

管理后台

• [x] 用户管理
• [ ] 权限管理

AI 功能

• [x] AI 功能 A
• [ ] AI 功能 B

6. 核心数据表

• users：用户信息
• generation_tasks：AI 生成任务
• materials：素材库
• admin_users：后台管理员

7. 核心 API

8. 核心业务流程

• 用户登录流程
• AI 生成流程
• 文件上传流程
• 支付流程
• 管理后台审核流程

9. 当前遗留问题

• 问题 A
• 问题 B
• 问题 C

10. 下一步建议

P0

• 必须优先处理的问题

P1

• 重要但不阻塞上线的问题

P2

• 后续优化项

---

## 9. 文档三：01_PROJECT_OVERVIEW.md

### 目标

从产品角度说明项目做了什么。

### 模板

```md
# 项目概览

## 1. 项目定位

本项目用于……

## 2. 目标用户

- 用户类型 A
- 用户类型 B

## 3. 用户核心场景

1. 用户在什么情况下打开项目
2. 用户主要完成什么任务
3. 项目如何帮助用户节省时间或解决问题

## 4. 当前已实现功能

### 模块一：用户系统

- 注册
- 登录
- 用户资料

### 模块二：核心业务功能

- 功能 A
- 功能 B

### 模块三：管理后台

- 用户管理
- 数据管理
- 记录管理

## 5. 未实现功能

- 功能 A
- 功能 B

## 6. 当前版本判断

当前项目属于：MVP / 内测版 / 可上线版 / 重构中

10. 文档四：02_TECH_STACK.md

目标

清晰说明项目使用了哪些技术。

模板

# 技术栈说明

## 1. 前端

- 框架：
- UI 方案：
- 状态管理：
- 路由：
- 请求方式：
- 主要目录：

## 2. 后端

- 语言：
- 框架：
- ORM：
- 鉴权方式：
- 异步任务：
- 主要目录：

## 3. 数据库

- 数据库类型：
- 数据库文件 / 连接方式：
- 表结构管理方式：
- 是否有 migration：

## 4. AI 能力

- 使用模型：
- 调用平台：
- 调用方式：
- Prompt 存放位置：
- 结果保存方式：

## 5. 文件存储

- 存储方式：本地 / 云存储 / 对象存储
- 上传入口：
- 文件访问方式：
- 文件安全限制：

## 6. 部署方式

- 是否使用 Docker：
- 是否使用 Nginx：
- 域名配置：
- HTTPS 配置：
- 启动命令：

11. 文档五：03_ARCHITECTURE.md

目标

说明项目整体架构和模块关系。

模板

# 系统架构说明

## 1. 架构总览

```mermaid
flowchart TD
  User[用户]
  Frontend[前端]
  Backend[后端 API]
  DB[(数据库)]
  AI[AI 模型服务]
  Storage[文件存储]

  User --> Frontend
  Frontend --> Backend
  Backend --> DB
  Backend --> AI
  Backend --> Storage

2. 模块划分

3. 请求链路

1. 用户在前端发起请求
2. 前端调用后端 API
3. 后端校验身份和参数
4. 后端执行业务逻辑
5. 读写数据库
6. 必要时调用 AI 或文件服务
7. 返回结果给前端

4. 部署结构

flowchart TD
  Browser[浏览器/小程序]
  Nginx[Nginx]
  App[应用服务]
  DB[(数据库)]

  Browser --> Nginx
  Nginx --> App
  App --> DB

---

## 12. 文档六：04_DATABASE_SCHEMA.md

### 目标

说明数据库结构。  
这是理解项目最重要的文档之一。

### 模板

```md
# 数据库结构说明

## 1. 数据库概览

- 数据库类型：
- ORM / 数据访问方式：
- migration 位置：
- 初始化方式：

## 2. 表结构

### users 用户表

用途：存储用户基础信息。

| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| id | integer | 是 | 用户 ID |
| openid | string | 否 | 微信 openid |
| email | string | 否 | 邮箱 |
| nickname | string | 否 | 昵称 |
| avatar_url | string | 否 | 头像 |
| created_at | datetime | 是 | 创建时间 |
| updated_at | datetime | 是 | 更新时间 |

### generation_tasks AI 生成任务表

用途：存储用户每次 AI 生成请求。

| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| id | integer | 是 | 任务 ID |
| user_id | integer | 是 | 用户 ID |
| tool_type | string | 是 | AI 工具类型 |
| status | string | 是 | pending/running/success/failed |
| input_data | json | 否 | 用户输入 |
| output_data | json | 否 | AI 输出 |
| error_message | text | 否 | 失败原因 |
| created_at | datetime | 是 | 创建时间 |

## 3. 表关系

```mermaid
erDiagram
  users ||--o{ generation_tasks : creates

4. 核心数据生命周期

以 AI 生成任务为例：

1. 用户提交生成请求
2. 后端创建 generation_tasks 记录，状态为 pending
3. 后端开始调用 AI，状态改为 running
4. AI 返回成功，状态改为 success，并保存 output_data
5. 如果失败，状态改为 failed，并保存 error_message

---

## 13. 文档七：05_API_SPEC.md

### 目标

说明后端接口能力。

### 模板

```md
# API 接口说明

## 1. 接口总览

| 模块 | 方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|---|
| 用户 | POST | /api/auth/login | 用户登录 | 否 |
| 用户 | GET | /api/user/me | 获取当前用户 | 是 |
| AI | POST | /api/generation/create | 创建生成任务 | 是 |
| AI | GET | /api/generation/history | 获取生成历史 | 是 |

## 2. 接口详情

### POST /api/auth/login

说明：用户登录。

请求参数：

```json
{
  "code": "微信登录 code 或其他登录凭证"
}

返回示例：

{
  "token": "xxx",
  "user": {
    "id": 1,
    "nickname": "用户昵称"
  }
}

POST /api/generation/create

说明：创建 AI 生成任务。

请求参数：

{
  "tool_type": "pet_photo",
  "input_data": {
    "prompt": "生成一张宠物写真"
  }
}

返回示例：

{
  "task_id": 1001,
  "status": "pending"
}

---

## 14. 文档八：06_CORE_LOGIC.md

### 目标

解释项目中的关键逻辑和复杂流程。

### 模板

```md
# 核心逻辑说明

## 1. 用户登录流程

```mermaid
sequenceDiagram
  participant User as 用户
  participant Frontend as 前端
  participant Backend as 后端
  participant Provider as 第三方登录服务
  participant DB as 数据库

  User->>Frontend: 点击登录
  Frontend->>Backend: 提交登录凭证
  Backend->>Provider: 校验登录凭证
  Provider-->>Backend: 返回用户身份信息
  Backend->>DB: 创建或更新用户
  Backend-->>Frontend: 返回 token

2. AI 生成流程

1. 用户选择 AI 工具
2. 前端提交参数
3. 后端创建任务记录
4. 后端组装 prompt
5. 后端调用 AI 模型
6. AI 返回结果
7. 后端保存结果
8. 前端展示结果

3. 任务状态流转

stateDiagram-v2
  [*] --> pending
  pending --> running
  running --> success
  running --> failed

4. 复杂逻辑说明

4.1 文件上传逻辑

• 上传入口：
• 文件大小限制：
• 文件类型限制：
• 存储位置：
• 访问方式：

4.2 权限控制逻辑

• 用户身份如何识别：
• token 如何生成：
• 接口如何鉴权：
• 管理员权限如何判断：

4.3 AI 调用逻辑

• prompt 在哪里组装：
• 模型在哪里配置：
• 超时如何处理：
• 失败如何记录：
• 结果如何保存：

---

## 15. 文档九：07_KNOWN_ISSUES.md

### 目标

记录当前项目的问题、风险和后续计划。

### 模板

```md
# 已知问题与后续计划

## 1. 已知 Bug

| 问题 | 影响 | 临时方案 | 后续修复建议 |
|---|---|---|---|
|  |  |  |  |

## 2. 未完成事项

- [ ] 功能 A 未完成
- [ ] 功能 B 只有前端，没有后端
- [ ] 支付逻辑未接入
- [ ] 管理后台缺少权限控制

## 3. 技术债

- service 文件过长，需要拆分
- 缺少单元测试
- 数据库字段缺少索引
- 错误处理不统一
- 配置项没有集中管理

## 4. 安全风险

- 环境变量不能提交到 Git
- 用户上传文件需要校验类型和大小
- 后台接口需要权限控制
- AI 接口需要限流
- 敏感日志不能输出 token / API key

## 5. 性能风险

- AI 生成任务不应长期同步阻塞
- 大文件上传需要异步处理
- 热门接口需要限流
- 数据列表需要分页
- 数据库查询需要索引

## 6. 下一步优先级

### P0

- 必须上线前解决的问题

### P1

- 重要但不阻塞上线的问题

### P2

- 后续体验优化

16. 文档十：08_CHANGELOG.md

目标

记录项目变化，避免 AI 多轮修改后人类不知道改了什么。

模板

# 更新记录

## YYYY-MM-DD

### 新增

- 新增功能 A
- 新增接口 B

### 修改

- 修改页面 C 的布局
- 调整数据表 D 的字段

### 修复

- 修复问题 E

### 注意事项

- 本次修改影响数据库结构，需要执行 migration

17. 给 AI / Codex 的执行要求

每次执行项目理解或代码修改任务时，必须遵守：

1. 修改代码前，先阅读 README.md、PROJECT_MAP.md、AGENTS.md 和 docs 目录。
2. 如果新增功能，必须更新 PROJECT_MAP.md。
3. 如果新增或修改数据表，必须更新 docs/04_DATABASE_SCHEMA.md。
4. 如果新增或修改接口，必须更新 docs/05_API_SPEC.md。
5. 如果新增复杂业务逻辑，必须更新 docs/06_CORE_LOGIC.md。
6. 如果发现未完成事项、临时方案、风险点，必须更新 docs/07_KNOWN_ISSUES.md。
7. 如果改变启动方式、环境变量或部署方式，必须更新 README.md。
8. 每次重要修改后，必须更新 docs/08_CHANGELOG.md。

18. 项目理解检查清单

分析项目时，必须完成以下检查。

# 项目理解检查清单

## 基础认知

- [ ] 这个项目是做什么的？
- [ ] 给谁用？
- [ ] 当前完成到什么程度？
- [ ] 哪些功能已经实现？
- [ ] 哪些功能还没实现？

## 技术认知

- [ ] 前端用什么？
- [ ] 后端用什么？
- [ ] 数据库用什么？
- [ ] AI 模型怎么调用？
- [ ] 文件怎么存？
- [ ] 项目怎么部署？

## 数据认知

- [ ] 有哪些核心表？
- [ ] 用户数据存在哪里？
- [ ] 业务数据存在哪里？
- [ ] 生成记录存在哪里？
- [ ] 表之间有什么关系？

## 逻辑认知

- [ ] 登录流程是什么？
- [ ] 核心业务流程是什么？
- [ ] AI 调用流程是什么？
- [ ] 错误处理怎么做？
- [ ] 权限控制怎么做？

## 风险认知

- [ ] 有哪些 Bug？
- [ ] 有哪些技术债？
- [ ] 有哪些安全问题？
- [ ] 有哪些性能问题？
- [ ] 下一步应该先改什么？

19. 最终输出格式

执行本 Skill 后，最终回复用户时应包含：

# 项目理解结果

## 1. 我已经识别到的项目类型

## 2. 当前技术栈

## 3. 当前已实现功能

## 4. 核心数据表

## 5. 核心接口

## 6. 核心业务流程

## 7. 发现的问题和风险

## 8. 建议下一步

## 9. 已生成或更新的文档

20. 推荐项目文档结构

最终建议项目中长期保留：

README.md
PROJECT_MAP.md
AGENTS.md
docs/
  01_PROJECT_OVERVIEW.md
  02_TECH_STACK.md
  03_ARCHITECTURE.md
  04_DATABASE_SCHEMA.md
  05_API_SPEC.md
  06_CORE_LOGIC.md
  07_KNOWN_ISSUES.md
  08_CHANGELOG.md

21. 一句话总结

本 Skill 的核心价值是：

> 让 AI 写出来的项目不再是黑盒，而是通过项目地图、技术栈、数据表、核心逻辑和遗留问题文档，让人能够快速理解、接手和继续开发。