Vibe Coding Prompt 最佳实践指南:实战项目解析

Vibe Coding Prompt 最佳实践指南:实战项目解析

目录


引言

在Vibe Coding中,Prompt(提示词)是开发者与AI交互的核心媒介。一个优秀的Prompt不仅能让AI准确理解你的意图,还能显著提升代码质量和开发效率。本文通过一个完整的实战项目——TaskFlow待办事项管理系统,深入剖析在不同开发阶段如何编写高质量的Prompt,总结出一套可复用的最佳实践。

本文目标
– 掌握Prompt的核心编写原则
– 学习不同场景下的Prompt编写技巧
– 通过实际案例理解Prompt的迭代优化过程
– 建立个人Prompt模板库


项目背景

项目概述

TaskFlow 是一个功能完善的待办事项管理系统,支持任务管理、分类、标签、提醒、协作等功能。

技术栈
– 后端:Python + FastAPI + SQLAlchemy + PostgreSQL
– 前端:Vue 3 + TypeScript + Element Plus
– 部署:Docker + Nginx

核心功能
1. 任务的增删改查(CRUD)
2. 任务分类和标签管理
3. 任务优先级和截止日期
4. 用户认证和授权
5. 团队协作和任务分配
6. 任务统计和报表

开发周期:2周(使用Vibe Coding)


Prompt最佳实践原则

1. 清晰性(Clarity)

原则:意图表达清晰明确,避免歧义。

示例

❌ 不好:
"帮我写个用户登录"

✅ 好:
"请帮我实现一个用户登录功能,要求:
1. 支持邮箱和手机号登录
2. 使用JWT进行身份验证
3. 密码使用bcrypt加密存储
4. 登录失败5次后锁定账户30分钟
5. 返回用户基本信息和JWT token
技术栈:Python + FastAPI + SQLAlchemy"

2. 具体性(Specificity)

原则:提供足够的细节和上下文,减少AI的猜测。

示例

❌ 不好:
"生成一个API接口"

✅ 好:
"请生成一个创建任务的API接口:
- 路径:POST /api/tasks
- 请求体:{title, description, priority, due_date, category_id, tag_ids}
- 验证:title必填,priority只能是low/medium/high
- 返回:创建成功的任务对象,包含自动生成的id和created_at
- 权限:需要用户登录
- 数据库:使用SQLAlchemy ORM"

3. 结构化(Structure)

原则:使用清晰的结构组织Prompt,便于AI理解。

推荐结构

## 背景
[项目背景和上下文信息]

## 任务
[具体要完成的任务]

## 要求
[功能要求、技术要求、质量要求]

## 约束
[必须遵守的约束条件]

## 输出格式
[期望的输出格式]

## 示例
[如果有,提供示例]

4. 上下文(Context)

原则:提供充分的上下文信息,帮助AI做出正确的决策。

示例

"项目背景:TaskFlow是一个待办事项管理系统,采用FastAPI开发。

现有数据模型:
- Task模型:id, title, description, status, priority, created_at
- User模型:id, email, password_hash, created_at

请基于现有模型,实现以下功能:
[具体任务]..."

5. 迭代性(Iteration)

原则:通过多次迭代逐步完善Prompt和代码。

示例

第一轮:
"帮我写一个任务列表查询接口"

第二轮(基于第一轮结果):
"在之前的代码基础上,增加以下功能:
1. 支持按状态筛选
2. 支持按优先级排序
3. 支持分页,每页20条
4. 只返回当前用户的任务"

实战案例:TaskFlow待办事项管理系统

阶段一:需求分析与架构设计

Prompt 1.1:需求分析

项目名称:TaskFlow待办事项管理系统

项目背景:
我需要开发一个功能完善的待办事项管理系统,帮助个人和团队高效管理任务。

核心功能需求:
1. 用户可以创建、查看、编辑、删除任务
2. 任务可以设置优先级(低、中、高)
3. 任务可以设置截止日期
4. 任务可以分类管理
5. 任务可以添加标签
6. 用户可以设置任务提醒
7. 支持团队协作,任务可以分配给其他用户
8. 提供任务统计和报表功能

技术要求:
- 后端:Python + FastAPI
- 数据库:PostgreSQL
- ORM:SQLAlchemy
- 认证:JWT

请帮我:
1. 分析这些需求,识别核心功能模块
2. 设计系统架构
3. 列出需要的数据模型
4. 列出主要的API接口
5. 给出开发优先级建议

AI输出

## 需求分析

### 核心功能模块
1. 用户管理模块(用户注册、登录、个人信息)
2. 认证授权模块(JWT token、权限控制)
3. 任务管理模块(CRUD、状态管理)
4. 分类管理模块(分类的增删改查)
5. 标签管理模块(标签的增删改查)
6. 提醒管理模块(任务提醒)
7. 团队协作模块(任务分配、共享)
8. 统计报表模块(数据统计、可视化)

### 系统架构
- 采用前后端分离架构
- 后端提供RESTful API
- 前端单页应用(SPA)
- 使用JWT进行无状态认证

### 数据模型
见下一节详细设计

### API接口
见下一节详细设计

### 开发优先级
Phase 1(核心功能):用户认证、任务CRUD
Phase 2(基础功能):分类、标签、优先级
Phase 3(高级功能):提醒、协作
Phase 4(增值功能):统计、报表

Prompt 1.2:数据模型设计

基于上面的需求分析,请帮我设计SQLAlchemy数据模型。

要求:
1. 使用Python类型注解
2. 包含所有必要的字段
3. 建立正确的表关系
4. 添加索引以提高查询性能
5. 包含created_at和updated_at字段
6. 使用字符串id而不是自增id(便于分布式)

需要的模型:
- User(用户)
- Task(任务)
- Category(分类)
- Tag(标签)
- TaskTag(任务-标签关联表)
- Team(团队)
- TeamMember(团队成员)
- Reminder(提醒)

请提供完整的模型代码,包括:
- 模型定义
- 字段类型和约束
- 表关系(relationship)
- 索引
- 字符串id生成方法

AI输出

from sqlalchemy import Column, String, DateTime, Integer, ForeignKey, Text, Enum, Boolean
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import relationship
from datetime import datetime
import enum
import uuid

Base = declarative_base()

def generate_uuid():
    return str(uuid.uuid4())

class Priority(enum.Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

class TaskStatus(enum.Enum):
    PENDING = "pending"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    CANCELLED = "cancelled"

class User(Base):
    __tablename__ = "users"

    id = Column(String, primary_key=True, default=generate_uuid)
    email = Column(String, unique=True, index=True, nullable=False)
    password_hash = Column(String, nullable=False)
    name = Column(String)
    avatar_url = Column(String)
    is_active = Column(Boolean, default=True)
    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

    # 关系
    created_tasks = relationship("Task", back_populates="creator", foreign_keys="Task.creator_id")
    assigned_tasks = relationship("Task", back_populates="assignee", foreign_keys="Task.assignee_id")
    categories = relationship("Category", back_populates="user")
    teams_owned = relationship("Team", back_populates="owner")
    team_memberships = relationship("TeamMember", back_populates="user")

class Task(Base):
    __tablename__ = "tasks"

    id = Column(String, primary_key=True, default=generate_uuid)
    title = Column(String, nullable=False)
    description = Column(Text)
    status = Column(Enum(TaskStatus), default=TaskStatus.PENDING)
    priority = Column(Enum(Priority), default=Priority.MEDIUM)
    due_date = Column(DateTime)
    completed_at = Column(DateTime)

    # 外键
    creator_id = Column(String, ForeignKey("users.id"))
    assignee_id = Column(String, ForeignKey("users.id"), nullable=True)
    category_id = Column(String, ForeignKey("categories.id"), nullable=True)

    # 关系
    creator = relationship("User", back_populates="created_tasks", foreign_keys=[creator_id])
    assignee = relationship("User", back_populates="assigned_tasks", foreign_keys=[assignee_id])
    category = relationship("Category", back_populates="tasks")
    tags = relationship("Tag", secondary="task_tags", back_populates="tasks")
    reminders = relationship("Reminder", back_populates="task")

    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

class Category(Base):
    __tablename__ = "categories"

    id = Column(String, primary_key=True, default=generate_uuid)
    name = Column(String, nullable=False)
    color = Column(String, default="#3498db")
    icon = Column(String)
    user_id = Column(String, ForeignKey("users.id"), nullable=False)

    # 关系
    user = relationship("User", back_populates="categories")
    tasks = relationship("Task", back_populates="category")

    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

class Tag(Base):
    __tablename__ = "tags"

    id = Column(String, primary_key=True, default=generate_uuid)
    name = Column(String, nullable=False)
    color = Column(String, default="#2ecc71")

    # 关系
    tasks = relationship("Task", secondary="task_tags", back_populates="tags")

    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

# 任务-标签关联表
class TaskTag(Base):
    __tablename__ = "task_tags"

    task_id = Column(String, ForeignKey("tasks.id"), primary_key=True)
    tag_id = Column(String, ForeignKey("tags.id"), primary_key=True)

class Team(Base):
    __tablename__ = "teams"

    id = Column(String, primary_key=True, default=generate_uuid)
    name = Column(String, nullable=False)
    description = Column(Text)
    owner_id = Column(String, ForeignKey("users.id"), nullable=False)

    # 关系
    owner = relationship("User", back_populates="teams_owned")
    members = relationship("TeamMember", back_populates="team")

    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

class TeamMember(Base):
    __tablename__ = "team_members"

    id = Column(String, primary_key=True, default=generate_uuid)
    team_id = Column(String, ForeignKey("teams.id"), nullable=False)
    user_id = Column(String, ForeignKey("users.id"), nullable=False)
    role = Column(String, default="member")  # owner, admin, member

    # 关系
    team = relationship("Team", back_populates="members")
    user = relationship("User", back_populates="team_memberships")

    created_at = Column(DateTime, default=datetime.utcnow)

class Reminder(Base):
    __tablename__ = "reminders"

    id = Column(String, primary_key=True, default=generate_uuid)
    task_id = Column(String, ForeignKey("tasks.id"), nullable=False)
    remind_at = Column(DateTime, nullable=False)
    is_sent = Column(Boolean, default=False)

    # 关系
    task = relationship("Task", back_populates="reminders")

    created_at = Column(DateTime, default=datetime.utcnow)

点评:这个Prompt提供了充分的上下文、明确的要求和结构化的输出,AI生成的代码质量很高,包含了所有必要的关系和约束。


阶段二:数据模型设计

Prompt 2.1:Pydantic模型

基于之前设计的SQLAlchemy模型,请生成对应的Pydantic模型。

要求:
1. 包含所有CRUD操作需要的Schema
2. 使用BaseModel作为基类
3. 添加必要的验证规则
4. 区分输入和输出模型
5. 使用Python 3.9+的类型注解

需要的Schema:
- UserBase, UserCreate, UserResponse, UserLogin
- TaskBase, TaskCreate, TaskUpdate, TaskResponse, TaskListResponse
- CategoryBase, CategoryCreate, CategoryResponse
- TagBase, TagCreate, TagResponse
- TeamBase, TeamCreate, TeamResponse
- ReminderBase, ReminderCreate, ReminderResponse

请提供完整的Pydantic模型代码。

AI输出

from pydantic import BaseModel, EmailStr, Field, validator
from typing import Optional, List
from datetime import datetime
from enum import Enum

# 枚举类型
class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

class TaskStatus(str, Enum):
    PENDING = "pending"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    CANCELLED = "cancelled"

# User Schemas
class UserBase(BaseModel):
    email: EmailStr
    name: Optional[str] = None
    avatar_url: Optional[str] = None

class UserCreate(UserBase):
    password: str = Field(..., min_length=6)

    @validator('password')
    def validate_password(cls, v):
        if len(v) < 6:
            raise ValueError('密码至少6个字符')
        return v

class UserLogin(BaseModel):
    email: EmailStr
    password: str

class UserResponse(UserBase):
    id: str
    is_active: bool
    created_at: datetime

    class Config:
        from_attributes = True

# Task Schemas
class TaskBase(BaseModel):
    title: str = Field(..., min_length=1, max_length=200)
    description: Optional[str] = None
    priority: Priority = Priority.MEDIUM
    due_date: Optional[datetime] = None

class TaskCreate(TaskBase):
    assignee_id: Optional[str] = None
    category_id: Optional[str] = None
    tag_ids: Optional[List[str]] = []

class TaskUpdate(BaseModel):
    title: Optional[str] = Field(None, min_length=1, max_length=200)
    description: Optional[str] = None
    status: Optional[TaskStatus] = None
    priority: Optional[Priority] = None
    due_date: Optional[datetime] = None
    assignee_id: Optional[str] = None
    category_id: Optional[str] = None
    tag_ids: Optional[List[str]] = None

class TaskResponse(TaskBase):
    id: str
    status: TaskStatus
    creator_id: str
    assignee_id: Optional[str]
    category_id: Optional[str]
    tags: List['TagResponse'] = []
    created_at: datetime
    updated_at: datetime
    completed_at: Optional[datetime] = None

    class Config:
        from_attributes = True

class TaskListResponse(BaseModel):
    total: int
    page: int
    page_size: int
    tasks: List[TaskResponse]

# Category Schemas
class CategoryBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=50)
    color: str = "#3498db"
    icon: Optional[str] = None

class CategoryCreate(CategoryBase):
    pass

class CategoryResponse(CategoryBase):
    id: str
    user_id: str
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True

# Tag Schemas
class TagBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=30)
    color: str = "#2ecc71"

class TagCreate(TagBase):
    pass

class TagResponse(TagBase):
    id: str
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True

# Team Schemas
class TeamBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = None

class TeamCreate(TeamBase):
    pass

class TeamResponse(TeamBase):
    id: str
    owner_id: str
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True

# Reminder Schemas
class ReminderBase(BaseModel):
    task_id: str
    remind_at: datetime

class ReminderCreate(ReminderBase):
    pass

class ReminderResponse(ReminderBase):
    id: str
    is_sent: bool
    created_at: datetime

    class Config:
        from_attributes = True

阶段三:API接口开发

Prompt 3.1:任务创建接口

请帮我实现任务创建的API接口

技术栈:FastAPI
ORMSQLAlchemy
认证:JWT

已有资源:
- Task模型(如前所示)
- TaskCreate和TaskResponse Pydantic模型
- 当前用户信息通过依赖注入获取

接口要求:
1. 路径:POST /api/tasks
2. 需要认证(使用JWT
3. 请求体:TaskCreate
4. 验证:
   - title必填
   - priority只能是low/medium/high
   - category_id必须属于当前用户
   - assignee_id必须是有效的用户
5. 业务逻辑:
   - creator_id自动设为当前用户
   - status默认为pending
   - 如果提供了tag_ids,需要创建关联
   - 如果提供了due_date,自动创建提醒(提醒时间:due_date前1小时
6. 返回:TaskResponse
7. 错误处理:
   - category_id不存在返回404
   - assignee_id不存在返回404
   - 验证失败返回422

请提供完整的路由代码,包括:
- 路由定义
- 依赖注入
- 业务逻辑
- 错误处理
- 数据验证

AI输出

from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from typing import List
from datetime import datetime, timedelta

from ..models import Task, Category, User, Tag, TaskTag, Reminder
from ..schemas import TaskCreate, TaskResponse
from ..database import get_db
from ..auth import get_current_user

router = APIRouter(prefix="/api/tasks", tags=["tasks"])

@router.post("", response_model=TaskResponse, status_code=status.HTTP_201_CREATED)
def create_task(
    task_data: TaskCreate,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """
    创建新任务

    参数:
    - task_data: 任务创建数据
    - db: 数据库会话
    - current_user: 当前登录用户

    返回:
    - TaskResponse: 创建的任务信息

    异常:
    - 404: category_id或assignee_id不存在
    - 422: 数据验证失败
    """
    # 验证category_id
    if task_data.category_id:
        category = db.query(Category).filter(
            Category.id == task_data.category_id,
            Category.user_id == current_user.id
        ).first()
        if not category:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"分类 {task_data.category_id} 不存在"
            )

    # 验证assignee_id
    if task_data.assignee_id:
        assignee = db.query(User).filter(
            User.id == task_data.assignee_id
        ).first()
        if not assignee:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND,
                detail=f"用户 {task_data.assignee_id} 不存在"
            )

    # 创建任务
    task = Task(
        title=task_data.title,
        description=task_data.description,
        priority=task_data.priority,
        due_date=task_data.due_date,
        creator_id=current_user.id,
        assignee_id=task_data.assignee_id,
        category_id=task_data.category_id,
        status=TaskStatus.PENDING
    )

    db.add(task)
    db.flush()  # 获取task.id

    # 处理标签关联
    if task_data.tag_ids:
        for tag_id in task_data.tag_ids:
            tag = db.query(Tag).filter(Tag.id == tag_id).first()
            if tag:
                task_tag = TaskTag(task_id=task.id, tag_id=tag_id)
                db.add(task_tag)

    # 如果有截止日期,创建提醒
    if task_data.due_date:
        remind_at = task_data.due_date - timedelta(hours=1)
        if remind_at > datetime.utcnow():
            reminder = Reminder(
                task_id=task.id,
                remind_at=remind_at
            )
            db.add(reminder)

    db.commit()
    db.refresh(task)

    # 加载关联数据
    return task

Prompt 3.2:任务列表查询接口(多参数)

请帮我实现任务列表查询的API接口

功能要求:
1. 路径:GET /api/tasks
2. 支持以下查询参数:
   - page: 页码(默认1
   - page_size: 每页数量(默认20,最大100
   - status: 状态筛选(pending/in_progress/completed/cancelled
   - priority: 优先级筛选(low/medium/high
   - category_id: 分类筛选
   - tag_id: 标签筛选
   - assignee_id: 执行人筛选
   - search: 关键词搜索(搜索title和description
   - sort_by: 排序字段(created_at/due_date/priority
   - order: 排序方向(asc/desc
3. 只返回当前用户的任务(包括作为创建者或执行者的任务)
4. 返回格式:TaskListResponse(包含totalpagepage_sizetasks
5. 性能要求:
   - 使用索引优化查询
   - 避免N+1查询问题
   - 预加载关联数据

请提供完整的路由代码,包含所有参数的处理逻辑。

AI输出

from fastapi import APIRouter, Depends, Query
from sqlalchemy.orm import Session, joinedload
from sqlalchemy import or_, and_
from typing import Optional
from enum import Enum

from ..models import Task, TaskTag, Tag
from ..schemas import TaskListResponse, TaskResponse, TaskStatus, Priority
from ..database import get_db
from ..auth import get_current_user
from ..models import User

router = APIRouter(prefix="/api/tasks", tags=["tasks"])

class SortBy(str, Enum):
    CREATED_AT = "created_at"
    DUE_DATE = "due_date"
    PRIORITY = "priority"

class Order(str, Enum):
    ASC = "asc"
    DESC = "desc"

@router.get("", response_model=TaskListResponse)
def get_tasks(
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    status: Optional[TaskStatus] = None,
    priority: Optional[Priority] = None,
    category_id: Optional[str] = None,
    tag_id: Optional[str] = None,
    assignee_id: Optional[str] = None,
    search: Optional[str] = None,
    sort_by: SortBy = SortBy.CREATED_AT,
    order: Order = Order.DESC,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """
    获取任务列表

    支持多维度筛选、搜索和排序
    """
    # 构建基础查询
    query = db.query(Task).filter(
        or_(
            Task.creator_id == current_user.id,
            Task.assignee_id == current_user.id
        )
    )

    # 状态筛选
    if status:
        query = query.filter(Task.status == status)

    # 优先级筛选
    if priority:
        query = query.filter(Task.priority == priority)

    # 分类筛选
    if category_id:
        query = query.filter(Task.category_id == category_id)

    # 执行人筛选
    if assignee_id:
        query = query.filter(Task.assignee_id == assignee_id)

    # 标签筛选(需要join)
    if tag_id:
        query = query.join(TaskTag).filter(TaskTag.tag_id == tag_id)

    # 关键词搜索
    if search:
        search_pattern = f"%{search}%"
        query = query.filter(
            or_(
                Task.title.ilike(search_pattern),
                Task.description.ilike(search_pattern)
            )
        )

    # 排序
    sort_column = {
        SortBy.CREATED_AT: Task.created_at,
        SortBy.DUE_DATE: Task.due_date,
        SortBy.PRIORITY: Task.priority,
    }[sort_by]

    if order == Order.DESC:
        query = query.order_by(sort_column.desc())
    else:
        query = query.order_by(sort_column.asc())

    # 计算总数
    total = query.count()

    # 分页
    offset = (page - 1) * page_size
    tasks = query.offset(offset).limit(page_size).all()

    # 预加载关联数据(避免N+1)
    tasks = db.query(Task).options(
        joinedload(Task.tags),
        joinedload(Task.category),
        joinedload(Task.creator),
        joinedload(Task.assignee)
    ).filter(
        Task.id.in_([task.id for task in tasks])
    ).all()

    return TaskListResponse(
        total=total,
        page=page,
        page_size=page_size,
        tasks=tasks
    )

Prompt 3.3:任务更新接口(复杂逻辑)

请帮我实现任务更新的API接口

业务逻辑要求:
1. 路径:PUT /api/tasks/{task_id}
2. 只有任务的创建者可以更新任务
3. 更新逻辑:
   - 如果status变为completed,自动设置completed_at
   - 如果status从completed变为其他状态,清空completed_at
   - 如果category_id改变,验证新分类属于当前用户
   - 如果assignee_id改变,验证新用户存在
   - 如果tag_ids改变
     * 删除旧的标签关联
     * 创建新的标签关联
   - 如果due_date改变
     * 删除旧的提醒
     * 如果有新的due_date,创建新的提醒(due_date前1小时
4. 返回:TaskResponse
5. 错误处理:
   - 403: 没有权限
   - 404: 任务不存在

请提供完整的路由代码。

AI输出

from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from datetime import datetime, timedelta
from typing import Optional

from ..models import Task, Category, User, Tag, TaskTag, Reminder, TaskStatus
from ..schemas import TaskUpdate, TaskResponse
from ..database import get_db
from ..auth import get_current_user

router = APIRouter(prefix="/api/tasks", tags=["tasks"])

@router.put("/{task_id}", response_model=TaskResponse)
def update_task(
    task_id: str,
    task_update: TaskUpdate,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """
    更新任务

    只有任务的创建者可以更新
    """
    # 获取任务
    task = db.query(Task).filter(Task.id == task_id).first()
    if not task:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"任务 {task_id} 不存在"
        )

    # 权限检查
    if task.creator_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="只有任务的创建者可以更新任务"
        )

    # 更新基本字段
    if task_update.title is not None:
        task.title = task_update.title
    if task_update.description is not None:
        task.description = task_update.description
    if task_update.priority is not None:
        task.priority = task_update.priority
    if task_update.due_date is not None:
        task.due_date = task_update.due_date

    # 处理status变化
    if task_update.status is not None:
        old_status = task.status
        task.status = task_update.status

        # 如果变为completed,设置completed_at
        if task_update.status == TaskStatus.COMPLETED and old_status != TaskStatus.COMPLETED:
            task.completed_at = datetime.utcnow()

        # 如果从completed变为其他状态,清空completed_at
        elif task_update.status != TaskStatus.COMPLETED and old_status == TaskStatus.COMPLETED:
            task.completed_at = None

    # 更新category_id
    if task_update.category_id is not None:
        if task_update.category_id != task.category_id:
            # 验证新分类
            if task_update.category_id:
                category = db.query(Category).filter(
                    Category.id == task_update.category_id,
                    Category.user_id == current_user.id
                ).first()
                if not category:
                    raise HTTPException(
                        status_code=status.HTTP_404_NOT_FOUND,
                        detail=f"分类 {task_update.category_id} 不存在"
                    )
            task.category_id = task_update.category_id

    # 更新assignee_id
    if task_update.assignee_id is not None:
        if task_update.assignee_id != task.assignee_id:
            # 验证新用户
            if task_update.assignee_id:
                assignee = db.query(User).filter(
                    User.id == task_update.assignee_id
                ).first()
                if not assignee:
                    raise HTTPException(
                        status_code=status.HTTP_404_NOT_FOUND,
                        detail=f"用户 {task_update.assignee_id} 不存在"
                    )
            task.assignee_id = task_update.assignee_id

    # 更新tag_ids
    if task_update.tag_ids is not None:
        # 删除旧的标签关联
        db.query(TaskTag).filter(TaskTag.task_id == task_id).delete()

        # 创建新的标签关联
        if task_update.tag_ids:
            for tag_id in task_update.tag_ids:
                tag = db.query(Tag).filter(Tag.id == tag_id).first()
                if tag:
                    task_tag = TaskTag(task_id=task_id, tag_id=tag_id)
                    db.add(task_tag)

    # 处理due_date变化,更新提醒
    if task_update.due_date is not None and task_update.due_date != task.due_date:
        # 删除旧的提醒
        db.query(Reminder).filter(Reminder.task_id == task_id).delete()

        # 创建新的提醒
        new_remind_at = task_update.due_date - timedelta(hours=1)
        if new_remind_at > datetime.utcnow():
            reminder = Reminder(
                task_id=task_id,
                remind_at=new_remind_at
            )
            db.add(reminder)

    task.updated_at = datetime.utcnow()
    db.commit()
    db.refresh(task)

    return task

阶段四:前端组件开发

Prompt 4.1:任务列表组件

请帮我开发一个任务列表组件。

技术栈:
- Vue 3 + TypeScript
- Element Plus UI框架
- Composition API

组件要求:
1. 组件名:TaskList
2. Props
   - tasks: Task[] - 任务列表
   - loading: boolean - 加载状态
3. Features
   - 显示任务列表,每行显示:标题、状态、优先级、截止日期、创建者
   - 状态用不同颜色的标签显示
   - 优先级用不同颜色的徽章显示
   - 支持点击任务行查看详情
   - 支持行内编辑状态
   - 支持删除任务
4. Events
   - @task-click: 点击任务时触发
   - @status-change: 状态改变时触发
   - @delete: 删除任务时触发
5. UI要求
   - 使用Element Plus的Table组件
   - 响应式布局
   - 空状态提示
   - 加载状态提示

请提供完整的组件代码,包括:
- Template
- ScriptTypeScript
- Style

AI输出

<template>
  <div class="task-list">
    <el-table
      :data="tasks"
      v-loading="loading"
      empty-text="暂无任务"
      @row-click="handleTaskClick"
      class="task-table"
    >
      <!-- 标题列 -->
      <el-table-column prop="title" label="标题" min-width="200">
        <template #default="{ row }">
          <div class="task-title">
            <span>{{ row.title }}</span>
            <el-tag
              v-if="row.tags.length > 0"
              size="small"
              type="info"
              class="task-tags"
            >
              {{ row.tags.length }}个标签
            </el-tag>
          </div>
        </template>
      </el-table-column>

      <!-- 状态列 -->
      <el-table-column prop="status" label="状态" width="120">
        <template #default="{ row }">
          <el-select
            :model-value="row.status"
            @change="handleStatusChange(row, $event)"
            size="small"
            @click.stop
          >
            <el-option label="待处理" value="pending" />
            <el-option label="进行中" value="in_progress" />
            <el-option label="已完成" value="completed" />
            <el-option label="已取消" value="cancelled" />
          </el-select>
        </template>
      </el-table-column>

      <!-- 优先级列 -->
      <el-table-column prop="priority" label="优先级" width="100">
        <template #default="{ row }">
          <el-tag
            :type="getPriorityType(row.priority)"
            size="small"
          >
            {{ getPriorityLabel(row.priority) }}
          </el-tag>
        </template>
      </el-table-column>

      <!-- 截止日期列 -->
      <el-table-column prop="due_date" label="截止日期" width="150">
        <template #default="{ row }">
          <span v-if="row.due_date" :class="getDueDateClass(row.due_date)">
            {{ formatDate(row.due_date) }}
          </span>
          <span v-else class="no-date">-</span>
        </template>
      </el-table-column>

      <!-- 创建者列 -->
      <el-table-column prop="creator.name" label="创建者" width="120">
        <template #default="{ row }">
          <div class="creator">
            <el-avatar :size="24" :src="row.creator?.avatar_url">
              {{ row.creator?.name?.[0] }}
            </el-avatar>
            <span>{{ row.creator?.name }}</span>
          </div>
        </template>
      </el-table-column>

      <!-- 操作列 -->
      <el-table-column label="操作" width="100" fixed="right">
        <template #default="{ row }">
          <el-button
            type="danger"
            size="small"
            link
            @click.stop="handleDelete(row)"
          >
            删除
          </el-button>
        </template>
      </el-table-column>
    </el-table>
  </div>
</template>

<script setup lang="ts">
import { defineProps, defineEmits } from 'vue'
import type { Task } from '@/types/task'

// Props
interface Props {
  tasks: Task[]
  loading: boolean
}

const props = withDefaults(defineProps<Props>(), {
  tasks: () => [],
  loading: false
})

// Emits
const emit = defineEmits<{
  taskClick: [task: Task]
  statusChange: [task: Task, status: string]
  delete: [task: Task]
}>()

// 优先级类型映射
const getPriorityType = (priority: string) => {
  const typeMap: Record<string, any> = {
    low: '',
    medium: 'warning',
    high: 'danger'
  }
  return typeMap[priority] || ''
}

// 优先级标签映射
const getPriorityLabel = (priority: string) => {
  const labelMap: Record<string, string> = {
    low: '低',
    medium: '中',
    high: '高'
  }
  return labelMap[priority] || priority
}

// 截止日期样式
const getDueDateClass = (dueDate: string) => {
  const now = new Date()
  const due = new Date(dueDate)
  const diff = due.getTime() - now.getTime()
  const days = diff / (1000 * 60 * 60 * 24)

  if (days < 0) return 'overdue'
  if (days <= 1) return 'urgent'
  if (days <= 3) return 'warning'
  return ''
}

// 格式化日期
const formatDate = (date: string) => {
  const d = new Date(date)
  return d.toLocaleDateString('zh-CN', {
    month: '2-digit',
    day: '2-digit',
    hour: '2-digit',
    minute: '2-digit'
  })
}

// 事件处理
const handleTaskClick = (task: Task) => {
  emit('taskClick', task)
}

const handleStatusChange = (task: Task, status: string) => {
  emit('statusChange', task, status)
}

const handleDelete = (task: Task) => {
  emit('delete', task)
}
</script>

<style scoped lang="scss">
.task-list {
  width: 100%;
}

.task-table {
  cursor: pointer;

  :deep(.el-table__row:hover) {
    background-color: #f5f7fa;
  }
}

.task-title {
  display: flex;
  align-items: center;
  gap: 8px;
}

.task-tags {
  margin-left: auto;
}

.creator {
  display: flex;
  align-items: center;
  gap: 8px;
}

.overdue {
  color: #f56c6c;
  font-weight: bold;
}

.urgent {
  color: #e6a23c;
  font-weight: bold;
}

.warning {
  color: #409eff;
}

.no-date {
  color: #909399;
}
</style>

阶段五:测试代码生成

Prompt 5.1:API测试

请为任务API生成完整的测试用例。

测试框架:pytest
测试库:pytest-asyncio, httpx

需要测试的接口:
1. POST /api/tasks - 创建任务
2. GET /api/tasks - 获取任务列表
3. GET /api/tasks/{task_id} - 获取任务详情
4. PUT /api/tasks/{task_id} - 更新任务
5. DELETE /api/tasks/{task_id} - 删除任务

测试要求:
1. 测试正常流程
2. 测试各种参数组合
3. 测试错误情况(404、403、422)
4. 测试权限控制
5. 测试数据验证
6. 使用fixture复用测试数据
7. 测试覆盖率 > 80%

请提供完整的测试代码。

AI输出

import pytest
from fastapi.testclient import TestClient
from sqlalchemy.orm import Session
from datetime import datetime, timedelta
import json

from app.main import app
from app.database import get_db, engine, Base
from app.models import User, Task, Category, Tag
from app.auth import create_access_token

client = TestClient(app)

# 测试数据库fixture
@pytest.fixture
def db_session():
    Base.metadata.create_all(bind=engine)
    db = next(get_db())
    try:
        yield db
    finally:
        db.close()
        Base.metadata.drop_all(bind=engine)

# 测试用户fixture
@pytest.fixture
def test_user(db_session: Session):
    user = User(
        email="test@example.com",
        password_hash="hashed_password",
        name="Test User"
    )
    db_session.add(user)
    db_session.commit()
    db_session.refresh(user)
    return user

# 测试用户2 fixture
@pytest.fixture
def test_user2(db_session: Session):
    user = User(
        email="test2@example.com",
        password_hash="hashed_password",
        name="Test User 2"
    )
    db_session.add(user)
    db_session.commit()
    db_session.refresh(user)
    return user

# 认证token fixture
@pytest.fixture
def auth_headers(test_user: User):
    token = create_access_token(data={"sub": test_user.id})
    return {"Authorization": f"Bearer {token}"}

# 测试任务fixture
@pytest.fixture
def test_task(db_session: Session, test_user: User):
    task = Task(
        title="Test Task",
        description="Test Description",
        priority="medium",
        creator_id=test_user.id,
        status="pending"
    )
    db_session.add(task)
    db_session.commit()
    db_session.refresh(task)
    return task

# 测试分类fixture
@pytest.fixture
def test_category(db_session: Session, test_user: User):
    category = Category(
        name="Work",
        user_id=test_user.id,
        color="#3498db"
    )
    db_session.add(category)
    db_session.commit()
    db_session.refresh(category)
    return category

# 测试标签fixture
@pytest.fixture
def test_tag(db_session: Session):
    tag = Tag(name="urgent", color="#e74c3c")
    db_session.add(tag)
    db_session.commit()
    db_session.refresh(tag)
    return tag

class TestCreateTask:
    def test_create_task_success(self, auth_headers):
        """测试成功创建任务"""
        response = client.post(
            "/api/tasks",
            json={
                "title": "New Task",
                "description": "Task Description",
                "priority": "high"
            },
            headers=auth_headers
        )
        assert response.status_code == 201
        data = response.json()
        assert data["title"] == "New Task"
        assert data["description"] == "Task Description"
        assert data["priority"] == "high"
        assert data["status"] == "pending"
        assert "id" in data

    def test_create_task_missing_title(self, auth_headers):
        """测试缺少标题"""
        response = client.post(
            "/api/tasks",
            json={"description": "Task Description"},
            headers=auth_headers
        )
        assert response.status_code == 422

    def test_create_task_invalid_priority(self, auth_headers):
        """测试无效的优先级"""
        response = client.post(
            "/api/tasks",
            json={
                "title": "New Task",
                "priority": "invalid"
            },
            headers=auth_headers
        )
        assert response.status_code == 422

    def test_create_task_with_category(
        self, auth_headers, test_category
    ):
        """测试带分类创建任务"""
        response = client.post(
            "/api/tasks",
            json={
                "title": "New Task",
                "category_id": test_category.id
            },
            headers=auth_headers
        )
        assert response.status_code == 201
        data = response.json()
        assert data["category_id"] == test_category.id

    def test_create_task_with_due_date_reminder(self, auth_headers):
        """测试创建带截止日期的任务自动创建提醒"""
        due_date = (datetime.utcnow() + timedelta(hours=3)).isoformat()
        response = client.post(
            "/api/tasks",
            json={
                "title": "New Task",
                "due_date": due_date
            },
            headers=auth_headers
        )
        assert response.status_code == 201

class TestGetTasks:
    def test_get_tasks_success(self, auth_headers, test_task):
        """测试成功获取任务列表"""
        response = client.get("/api/tasks", headers=auth_headers)
        assert response.status_code == 200
        data = response.json()
        assert "tasks" in data
        assert "total" in data
        assert len(data["tasks"]) >= 1

    def test_get_tasks_with_filter(
        self, auth_headers, db_session, test_user
    ):
        """测试带筛选条件获取任务"""
        # 创建不同状态的任务
        task1 = Task(
            title="Pending Task",
            status="pending",
            creator_id=test_user.id
        )
        task2 = Task(
            title="Completed Task",
            status="completed",
            creator_id=test_user.id
        )
        db_session.add_all([task1, task2])
        db_session.commit()

        # 筛选pending任务
        response = client.get(
            "/api/tasks?status=pending",
            headers=auth_headers
        )
        assert response.status_code == 200
        data = response.json()
        assert all(t["status"] == "pending" for t in data["tasks"])

    def test_get_tasks_with_pagination(self, auth_headers, db_session, test_user):
        """测试分页"""
        # 创建25个任务
        tasks = [
            Task(
                title=f"Task {i}",
                creator_id=test_user.id
            )
            for i in range(25)
        ]
        db_session.add_all(tasks)
        db_session.commit()

        # 获取第一页
        response = client.get(
            "/api/tasks?page=1&page_size=10",
            headers=auth_headers
        )
        assert response.status_code == 200
        data = response.json()
        assert data["page"] == 1
        assert data["page_size"] == 10
        assert len(data["tasks"]) == 10
        assert data["total"] == 25

    def test_get_tasks_unauthorized(self):
        """测试未授权访问"""
        response = client.get("/api/tasks")
        assert response.status_code == 401

class TestUpdateTask:
    def test_update_task_success(
        self, auth_headers, test_task
    ):
        """测试成功更新任务"""
        response = client.put(
            f"/api/tasks/{test_task.id}",
            json={
                "title": "Updated Task",
                "status": "completed"
            },
            headers=auth_headers
        )
        assert response.status_code == 200
        data = response.json()
        assert data["title"] == "Updated Task"
        assert data["status"] == "completed"
        assert data["completed_at"] is not None

    def test_update_task_unauthorized(
        self, auth_headers, test_task, test_user2
    ):
        """测试无权限更新"""
        response = client.put(
            f"/api/tasks/{test_task.id}",
            json={"title": "Hacked"},
            headers={"Authorization": f"Bearer {create_access_token(data={'sub': test_user2.id})}"}
        )
        assert response.status_code == 403

    def test_update_task_not_found(self, auth_headers):
        """测试任务不存在"""
        response = client.put(
            "/api/tasks/nonexistent",
            json={"title": "Updated"},
            headers=auth_headers
        )
        assert response.status_code == 404

    def test_update_task_status_to_completed(
        self, auth_headers, test_task
    ):
        """测试状态变为completed自动设置completed_at"""
        response = client.put(
            f"/api/tasks/{test_task.id}",
            json={"status": "completed"},
            headers=auth_headers
        )
        assert response.status_code == 200
        data = response.json()
        assert data["completed_at"] is not None

    def test_update_task_status_from_completed(
        self, db_session, auth_headers, test_task
    ):
        """测试状态从completed变为其他"""
        test_task.status = "completed"
        test_task.completed_at = datetime.utcnow()
        db_session.commit()

        response = client.put(
            f"/api/tasks/{test_task.id}",
            json={"status": "pending"},
            headers=auth_headers
        )
        assert response.status_code == 200
        data = response.json()
        assert data["completed_at"] is None

class TestDeleteTask:
    def test_delete_task_success(
        self, auth_headers, test_task
    ):
        """测试成功删除任务"""
        response = client.delete(
            f"/api/tasks/{test_task.id}",
            headers=auth_headers
        )
        assert response.status_code == 200

    def test_delete_task_unauthorized(
        self, auth_headers, test_task, test_user2
    ):
        """测试无权限删除"""
        response = client.delete(
            f"/api/tasks/{test_task.id}",
            headers={"Authorization": f"Bearer {create_access_token(data={'sub': test_user2.id})}"}
        )
        assert response.status_code == 403

阶段六:文档与部署

Prompt 6.1:API文档

请为TaskFlow API生成完整的API文档。

文档格式:Markdown

文档内容:
1. 项目简介
2. 技术栈
3. 认证方式(JWT)
4. API端点列表
5. 每个端点的详细说明:
   - 端点路径
   - 请求方法
   - 请求参数
   - 请求体
   - 响应体
   - 错误码
   - 示例请求和响应
6. 数据模型说明

请生成完整的API文档。

AI输出

# TaskFlow API 文档

## 项目简介

TaskFlow是一个功能完善的待办事项管理系统,支持任务管理、分类、标签、提醒、协作等功能。

## 技术栈

- 后端框架:FastAPI
- ORM:SQLAlchemy
- 数据库:PostgreSQL
- 认证:JWT (JSON Web Token)
- API文档:Swagger UI / ReDoc

## 认证方式

TaskFlow使用JWT进行身份验证。

### 获取Token

**端点**`POST /api/auth/login`

**请求体**:
```json
{
  "email": "user@example.com",
  "password": "password123"
}

响应

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "name": "User Name"
  }
}

使用Token

在请求头中添加:

Authorization: Bearer {access_token}

API端点列表

用户管理

  • POST /api/auth/register – 用户注册
  • POST /api/auth/login – 用户登录
  • GET /api/users/me – 获取当前用户信息
  • PUT /api/users/me – 更新当前用户信息

任务管理

  • GET /api/tasks – 获取任务列表
  • POST /api/tasks – 创建任务
  • GET /api/tasks/{task_id} – 获取任务详情
  • PUT /api/tasks/{task_id} – 更新任务
  • DELETE /api/tasks/{task_id} – 删除任务

分类管理

  • GET /api/categories – 获取分类列表
  • POST /api/categories – 创建分类
  • GET /api/categories/{category_id} – 获取分类详情
  • PUT /api/categories/{category_id} – 更新分类
  • DELETE /api/categories/{category_id} – 删除分类

标签管理

  • GET /api/tags – 获取标签列表
  • POST /api/tags – 创建标签
  • GET /api/tags/{tag_id} – 获取标签详情
  • PUT /api/tags/{tag_id} – 更新标签
  • DELETE /api/tags/{tag_id} – 删除标签

详细端点说明

GET /api/tasks – 获取任务列表

获取当前用户的任务列表,支持筛选、搜索、排序和分页。

请求方法GET

请求参数

参数 类型 必填 说明 示例
page integer 页码,默认1 1
page_size integer 每页数量,默认20,最大100 20
status string 任务状态筛选 pending
priority string 优先级筛选 high
category_id string 分类ID筛选 cat-id
tag_id string 标签ID筛选 tag-id
assignee_id string 执行人ID筛选 user-id
search string 关键词搜索 关键词
sort_by string 排序字段 created_at
order string 排序方向 desc

状态枚举
pending – 待处理
in_progress – 进行中
completed – 已完成
cancelled – 已取消

优先级枚举
low – 低
medium – 中
high – 高

排序字段
created_at – 创建时间
due_date – 截止日期
priority – 优先级

响应

{
  "total": 50,
  "page": 1,
  "page_size": 20,
  "tasks": [
    {
      "id": "task-id-1",
      "title": "完成项目文档",
      "description": "编写API文档和用户手册",
      "status": "in_progress",
      "priority": "high",
      "due_date": "2026-03-25T18:00:00",
      "creator_id": "user-id",
      "assignee_id": "assignee-id",
      "category_id": "cat-id",
      "tags": [
        {
          "id": "tag-id",
          "name": "urgent",
          "color": "#e74c3c"
        }
      ],
      "created_at": "2026-03-21T10:00:00",
      "updated_at": "2026-03-21T14:00:00",
      "completed_at": null
    }
  ]
}

错误码
401 – 未认证
500 – 服务器错误

POST /api/tasks – 创建任务

创建一个新的任务。

请求方法POST

请求头

Authorization: Bearer {access_token}
Content-Type: application/json

请求体

{
  "title": "任务标题",
  "description": "任务描述",
  "priority": "high",
  "due_date": "2026-03-25T18:00:00",
  "assignee_id": "user-id",
  "category_id": "cat-id",
  "tag_ids": ["tag-id-1", "tag-id-2"]
}

请求体参数

参数 类型 必填 说明 约束
title string 任务标题 1-200字符
description string 任务描述
priority string 优先级 low/medium/high
due_date string 截止日期 ISO 8601格式
assignee_id string 执行人ID 有效的用户ID
category_id string 分类ID 属于当前用户的分类
tag_ids array 标签ID列表 有效的标签ID数组

响应201 Created

{
  "id": "new-task-id",
  "title": "任务标题",
  "description": "任务描述",
  "status": "pending",
  "priority": "high",
  "due_date": "2026-03-25T18:00:00",
  "creator_id": "user-id",
  "assignee_id": "assignee-id",
  "category_id": "cat-id",
  "tags": [],
  "created_at": "2026-03-21T15:00:00",
  "updated_at": "2026-03-21T15:00:00",
  "completed_at": null
}

错误码
401 – 未认证
404 – 分类或用户不存在
422 – 数据验证失败

PUT /api/tasks/{task_id} – 更新任务

更新指定的任务。只有任务的创建者可以更新。

请求方法PUT

请求头

Authorization: Bearer {access_token}
Content-Type: application/json

路径参数
task_id – 任务ID

请求体(所有字段可选):

{
  "title": "更新后的标题",
  "description": "更新后的描述",
  "status": "completed",
  "priority": "medium",
  "due_date": "2026-03-26T18:00:00",
  "assignee_id": "new-user-id",
  "category_id": "new-cat-id",
  "tag_ids": ["tag-id-3"]
}

响应200 OK

返回更新后的任务详情,格式同创建任务响应。

错误码
401 – 未认证
403 – 无权限(非任务创建者)
404 – 任务不存在
422 – 数据验证失败

DELETE /api/tasks/{task_id} – 删除任务

删除指定的任务。只有任务的创建者可以删除。

请求方法DELETE

请求头

Authorization: Bearer {access_token}

路径参数
task_id – 任务ID

响应200 OK

{
  "message": "任务已删除"
}

错误码
401 – 未认证
403 – 无权限(非任务创建者)
404 – 任务不存在

数据模型

Task(任务)

字段 类型 说明
id string 任务ID(UUID)
title string 任务标题
description string 任务描述
status string 任务状态
priority string 优先级
due_date datetime 截止日期
creator_id string 创建者ID
assignee_id string 执行人ID
category_id string 分类ID
tags array 标签列表
created_at datetime 创建时间
updated_at datetime 更新时间
completed_at datetime 完成时间

User(用户)

字段 类型 说明
id string 用户ID(UUID)
email string 邮箱
name string 姓名
avatar_url string 头像URL
is_active boolean 是否激活
created_at datetime 创建时间

Category(分类)

字段 类型 说明
id string 分类ID(UUID)
name string 分类名称
color string 分类颜色
icon string 分类图标
user_id string 所属用户ID
created_at datetime 创建时间

Tag(标签)

字段 类型 说明
id string 标签ID(UUID)
name string 标签名称
color string 标签颜色
created_at datetime 创建时间

错误响应格式

所有错误响应遵循以下格式:

{
  "detail": "错误描述信息"
}

常见错误码:
400 – 请求错误
401 – 未认证
403 – 无权限
404 – 资源不存在
422 – 数据验证失败
500 – 服务器错误

---

## Prompt优化技巧

### 技巧1:使用示例驱动

**原则**:提供具体的输入输出示例,帮助AI理解期望。

**示例**:

请帮我编写一个函数,计算任务列表的完成率。

要求:
– 输入:Task对象列表
– 输出:完成率(0-1之间的浮点数)
– 完成率 = 已完成任务数 / 总任务数

示例:
输入:[
Task(status=”completed”),
Task(status=”pending”),
Task(status=”completed”)
]
输出:0.6667(2/3)

请提供Python代码实现。

### 技巧2:分步引导

**原则**:将复杂任务分解为多个步骤,逐步引导AI完成。

**示例**:

第一步:请帮我设计一个任务的SQLAlchemy模型,包含id、title、status、created_at字段。

第二步:基于上面的模型,创建对应的Pydantic Schema。

第三步:实现创建任务的API接口。

### 技巧3:明确约束条件

**原则**:明确说明必须遵守的约束和不能做的事情。

**示例**:

请生成一个用户注册的API接口。

要求:
– 使用FastAPI框架
– 密码必须使用bcrypt加密
– 邮箱必须验证格式
– 返回用户信息时不要包含密码
– 不要使用第三方认证库

约束:
– 必须验证密码长度(至少6位)
– 必须验证邮箱唯一性
– 必须处理重复注册的错误

### 技巧4:提供上下文

**原则**:提供充分的背景信息,帮助AI做出正确的决策。

**示例**:

项目背景:TaskFlow是一个待办事项管理系统,采用微服务架构。

当前情况:
– 用户服务已经完成,提供了用户认证API
– 任务服务正在开发中
– 需要调用用户服务验证用户ID

请实现任务创建接口,要求:
1. 验证用户ID是否有效(调用用户服务API)
2. 如果用户不存在,返回404错误
3. 如果用户存在,创建任务

用户服务API:GET http://user-service/api/users/{user_id}

### 技巧5:使用角色设定

**原则**:为AI设定角色,让AI以特定视角思考问题。

**示例**:

你是一个资深的FastAPI专家,专注于代码质量和最佳实践。

请帮我审查以下代码,指出潜在的问题:
[代码内容]

重点关注:
1. 安全性
2. 性能
3. 错误处理
4. 代码风格
5. 最佳实践

请提供详细的改进建议。

---

## 常见错误与解决方案

### 错误1:意图不明确

**问题**:

“帮我写个API”

**解决方案**:

“请帮我实现一个用户登录的API接口:
– 路径:POST /api/auth/login
– 请求体:{email, password}
– 验证:使用bcrypt验证密码
– 返回:JWT token和用户信息
– 错误:认证失败返回401”

### 错误2:缺少上下文

**问题**:

“生成一个Task模型”

**解决方案**:

“基于FastAPI和SQLAlchemy,生成一个Task模型:
– 包含id、title、status、priority字段
– 使用UUID作为id
– status使用枚举类型
– 添加created_at和updated_at时间戳
– 与User模型建立多对一关系”

### 错误3:缺少约束条件

**问题**:

“创建一个用户注册接口”

**解决方案**:

“创建一个用户注册接口:
– 验证邮箱格式
– 验证密码长度(至少6位)
– 检查邮箱是否已存在
– 密码使用bcrypt加密
– 不要返回密码哈希
– 处理所有可能的错误情况”

### 错误4:Prompt过长

**问题**:Prompt包含过多细节,导致AI理解困难。

**解决方案**:
- 将长Prompt拆分为多个短Prompt
- 使用结构化格式(列表、表格)
- 使用"参见"引用之前的上下文
- 分阶段完成任务

### 错误5:缺少迭代

**问题**:一次性生成,不进行优化。

**解决方案**:

第一轮:生成初始代码
第二轮:优化代码性能
第三轮:添加错误处理
第四轮:编写测试用例

---

## Prompt模板库

### 模板1API接口生成

```markdown
请帮我实现一个[功能名称]的API接口

技术栈[FastAPI/Flask/Django]
ORM[SQLAlchemy/Django ORM]

接口要求
- 路径[HTTP方法] /api/path
- 需要认证[是/否]
- 请求参数[参数列表]
- 请求体[请求体结构]
- 验证规则[验证规则]
- 业务逻辑[业务逻辑描述]
- 返回[返回数据结构]
- 错误处理[错误码和错误信息]

请提供完整的路由代码包括
- 路由定义
- 依赖注入
- 业务逻辑
- 错误处理
- 数据验证

模板2:数据模型生成

请帮我生成一个[模型名称]的SQLAlchemy模型。

要求:
- 使用Python类型注解
- 包含字段:[字段列表]
- 建立表关系:[关系描述]
- 添加索引:[索引列表]
- 包含时间戳:created_at, updated_at
- 使用字符串id

请提供完整的模型代码。

模板3:测试用例生成

请为[功能名称]生成完整的测试用例。

测试框架:pytest
需要测试的场景:
1. [场景1]
2. [场景2]
3. [场景3]

测试要求:
- 测试正常流程
- 测试边界情况
- 测试错误情况
- 使用fixture复用测试数据
- 测试覆盖率 > 80%

请提供完整的测试代码。

模板4:代码审查

请帮我审查以下代码,指出潜在的问题。

代码背景:[背景信息]
[代码内容]

重点关注:
1. 安全性
2. 性能
3. 错误处理
4. 代码风格
5. 最佳实践

请提供:
- 问题列表
- 严重程度评估
- 改进建议
- 优化后的代码(如有必要)

模板5:文档生成

请为[功能/模块]生成完整的文档。

文档格式:Markdown

文档内容:
1. 简介
2. 功能说明
3. 使用方法
4. API文档(如有)
5. 示例代码
6. 注意事项

请生成完整的文档。

总结

本文通过TaskFlow待办事项管理系统的完整开发过程,展示了Vibe Coding中Prompt编写的最佳实践。关键要点包括:

核心原则

  1. 清晰性:意图表达清晰明确,避免歧义
  2. 具体性:提供足够的细节和上下文
  3. 结构化:使用清晰的结构组织Prompt
  4. 上下文:提供充分的背景信息
  5. 迭代性:通过多次迭代逐步完善

实践技巧

  1. 示例驱动:提供具体的输入输出示例
  2. 分步引导:将复杂任务分解为多个步骤
  3. 明确约束:说明必须遵守的约束条件
  4. 提供上下文:帮助AI做出正确决策
  5. 角色设定:为AI设定特定角色

避免错误

  1. 避免意图不明确
  2. 避免缺少上下文
  3. 避免缺少约束条件
  4. 避免Prompt过长
  5. 避免缺少迭代优化

通过遵循这些原则和技巧,你可以编写出高质量的Prompt,显著提升Vibe Coding的效率和代码质量。记住,Prompt工程是一个持续改进的过程,需要不断实践和优化。


文档版本:v1.0
最后更新:2026年3月21日
作者:iFlow CLI
项目示例:TaskFlow待办事项管理系统