SKILL.md

Skill 名称

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

1. Skill 目标

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

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

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

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

2. 适用场景

本 Skill 适用于以下场景：

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

3. 核心原则

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

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

优先理解：

项目目标
技术栈
目录结构
数据表
API 接口
核心业务流程
遗留问题

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

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

避免空泛描述，例如：

不推荐：

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

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 安装依赖

示例

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

目标

这是最重要的项目地图文档。

用户应当通过这个文件快速了解整个项目。

模板

# 项目地图

## 1. 项目一句话介绍

本项目是一个……

## 2. 当前项目状态

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

## 3. 技术栈总览

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

## 4. 项目目录结构

├── 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

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

## 8. 核心业务流程

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

## 9. 当前遗留问题

- 问题 A
- 问题 B
- 问题 C

## 10. 下一步建议

### P0

- 必须优先处理的问题

### P1

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

### P2

- 后续优化项

9. 文档三：01_PROJECT_OVERVIEW.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. 架构总览

flowchart TD

User[用户]

Frontend[前端]

Backend[后端 API]

DB[(数据库)]

AI[AI 模型服务]

Storage[文件存储]

User --> Frontend

Frontend --> Backend

Backend --> DB

Backend --> AI

Backend --> Storage


## 2. 模块划分

| 模块 | 目录 | 说明 |
|---|---|---|
| 用户模块 |  |  |
| 业务模块 |  |  |
| AI 模块 |  |  |
| 文件模块 |  |  |
| 管理后台 |  |  |

## 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

目标

说明数据库结构。

这是理解项目最重要的文档之一。

模板

# 数据库结构说明

## 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. 表关系

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

目标

说明后端接口能力。

模板

# 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

说明：用户登录。

请求参数：

{

"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

目标

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

模板

# 核心逻辑说明

## 1. 用户登录流程

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. 任务状态流转

| 状态 | 含义 |
|---|---|
| pending | 已创建，等待执行 |
| running | 正在执行 |
| success | 执行成功 |
| failed | 执行失败 |

stateDiagram-v2

[*] --> pending

pending --> running

running --> success

running --> failed


## 4. 复杂逻辑说明

### 4.1 文件上传逻辑

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

### 4.2 权限控制逻辑

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

### 4.3 AI 调用逻辑

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

15. 文档九：07_KNOWN_ISSUES.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 写出来的项目不再是黑盒，而是通过项目地图、技术栈、数据表、核心逻辑和遗留问题文档，让人能够快速理解、接手和继续开发。

project-understand

概述