一、 为什么需要新的文档格式？

在传统的开发流程中，需求文档是写给人看的，注重叙事和业务流程。但在 AI 辅助开发（AI-Driven Development）中，文档是写给模型看的。

传统文档的痛点：

• 上下文模糊：AI 难以从长文本中提取精确的技术约束。

• 状态丢失：多轮对话后，AI 容易忘记初始架构设定。

• 风格漂移：不同模块生成的代码风格不一致。

AI-Native 文档的核心原则：

1. 结构化（Structured）：使用 Markdown 层级，便于模型解析。

2. 模块化（Modular）：全局配置与具体任务分离。

3. 显式约束（Explicit Constraints）：明确技术栈、目录结构和错误处理。

4. 任务原子化（Atomic Tasks）：将大需求拆解为可独立执行的小步骤。

---

二、 项目文件结构建议

为了配合 Cursor/Trea 的工作流，建议在项目根目录建立以下文件结构：

project_root/
├── .cursorrules          # [核心] 全局系统指令（技术栈、规范、目录结构）
├── AI_SPEC.md            # [核心] 详细业务逻辑、数据模型、API 定义
├── ROADMAP.md            # [核心] 任务清单与进度管理
├── src/                  # 代码生成目录
└── tests/                # 测试代码目录

---

三、 完整文档模板（可直接复制）

以下模板分为两部分：全局规则文件 和 详细规格文件。

3.1 全局规则文件：.cursorrules/.trearules

用途：放在项目根目录。Cursor 会在每次对话时自动读取此文件，无需重复发送。它定义了“怎么做”。例如：

# Role
你是一位资深 Python 后端架构师，擅长使用 FastAPI、SQLAlchemy 和 Pydantic 构建高可用系统。
​
# Tech Stack
- **Language**: Python 3.10+
- **Framework**: FastAPI
- **Database**: PostgreSQL + SQLAlchemy 2.0 (Async)
- **Validation**: Pydantic V2
- **Testing**: Pytest + Httpx
- **Style**: PEP8, 强制类型提示 (Type Hints), Google Style Docstrings
​
# Directory Structure
# 必须严格遵守以下目录结构，不要随意创建新文件夹
project_root/
├── app/
│   ├── api/            # 路由层 (v1 endpoints)
│   ├── core/           # 配置、安全、中间件
│   ├── models/         # 数据库 ORM 模型
│   ├── schemas/        # Pydantic 请求/响应模型
│   ├── services/       # 业务逻辑层
│   └── main.py
├── tests/
├── .env
└── requirements.txt
​
# Coding Rules
1. **异步优先**：所有数据库操作和 IO 必须使用 async/await。
2. **依赖注入**：API 路由必须使用 FastAPI Depends 进行依赖注入。
3. **错误处理**：所有业务异常必须继承 `app.core.exceptions.AppException`。
4. **类型安全**：禁止使用 Any 类型，必须明确定义类型。
5. **注释规范**：复杂逻辑必须包含 Google Style 文档字符串。
​
# Response Format
- 生成代码前，先列出计划修改/创建的文件列表。
- 代码块必须包含完整路径注释，例如：`# File: app/api/v1/users.py`。
- 每次任务完成后，简要说明测试方法。

3.2 详细规格文件：AI_SPEC.md

用途：包含具体业务逻辑、数据模型和任务清单。在对话开始时作为上下文投喂，或按需分段投喂。例如：

# 1. 项目概述
- **项目名称**: [例如：SaaS 多租户管理系统]
- **核心目标**: [例如：实现用户管理、订阅支付、数据隔离]
- **当前阶段**: [例如：MVP 版本开发]
​
# 2. 数据模型定义 (Data Models)
# AI 生成代码前必须严格遵循此定义
​
## 2.1 User (用户表)
- **Table**: `users`
- **Fields**:
  - `id`: UUID (PK)
  - `email`: String (Unique, Index)
  - `hashed_password`: String
  - `tenant_id`: UUID (FK -> tenants.id)
  - `is_active`: Boolean (Default True)
  - `created_at`: DateTime
​
## 2.2 Tenant (租户表)
- **Table**: `tenants`
- **Fields**:
  - `id`: UUID (PK)
  - `name`: String
  - `plan`: Enum (free, pro, enterprise)
​
# 3. 接口规范 (API Specs)
​
## 3.1 认证模块
- `POST /api/v1/auth/login`: 
  - Body: {email, password}
  - Response: {access_token, token_type}
  - Error: 401 (Invalid Credentials)
​
## 3.2 用户模块
- `GET /api/v1/users/me`: 
  - Auth Required: Yes
  - Response: UserSchema
- `PUT /api/v1/users/me`: 
  - Auth Required: Yes
  - Body: UserUpdateSchema
​
# 4. 开发任务清单 (Roadmap)
# 请严格按照以下顺序执行，每完成一个任务需等待确认
​
- [ ] **Task 0**: 初始化项目结构，创建 requirements.txt 和基础目录
- [ ] **Task 1**: 实现 app/core/config.py (Settings) 和 database.py (Connection)
- [ ] **Task 2**: 定义 app/models 和 app/schemas (User, Tenant)
- [ ] **Task 3**: 实现用户认证逻辑 (JWT, Password Hashing)
- [ ] **Task 4**: 实现用户 CRUD 接口 (Protected Routes)
- [ ] **Task 5**: 编写 Pytest 集成测试
- [ ] **Task 6**: 编写 Dockerfile 和 docker-compose.yml
​
# 5. 特殊业务逻辑说明
- **多租户隔离**：所有查询必须自动过滤 `tenant_id`，禁止跨租户访问。
- **密码安全**：使用 bcrypt 进行哈希，盐值长度 12。

3.3 进度管理文件：ROADMAP.md (可选但推荐)

用途：用于在长对话中同步状态。每次任务完成后，让 AI 更新此文件。例如：

# 项目进度状态
​
## 已完成
- [x] Task 0: 项目初始化 (2023-10-27)
- [x] Task 1: 数据库连接配置 (2023-10-27)
​
## 进行中
- [ ] Task 2: 数据模型定义
​
## 待办
- [ ] Task 3: 认证逻辑
...

---

四、交互工作流（如何依次性投喂）

不要试图一次性让 AI 生成所有代码。采用 “全局上下文 + 增量任务” 的模式。

步骤 1：初始化会话

打开 Cursor 聊天窗口，输入以下指令（或确保 .cursorrules 已生效）：

Prompt: "@.cursorrules 我已经上传了 AI_SPEC.md。请阅读该文件，理解项目目标、数据模型和任务清单。不需要生成代码，只需确认你已理解项目架构和任务顺序。"

步骤 2：执行原子任务

按照 AI_SPEC.md 中的 Task List 依次发送指令。

Prompt (Task 1): "现在开始执行 Task 1。请根据 AI_SPEC.md 中的技术栈要求，创建 app/core/config.py 和 app/core/database.py。 要求：

1. 使用 pydantic-settings 管理配置。

2. 数据库连接需支持连接池。

3. 生成代码后，请说明如何配置 .env 文件。"

步骤 3：代码审查与修正

在 AI 生成代码后，不要急着进行下一步。

Prompt: "代码看起来不错。但在 database.py 中，请确保添加连接关闭的依赖项（async with 上下文管理）。修改后，请告诉我如何运行一个简单的脚本来测试数据库连接。"

步骤 4：状态同步（关键）

当任务较多，对话窗口可能重置时，使用 ROADMAP.md 恢复上下文。

Prompt: "这是当前的 ROADMAP.md 进度。我们刚刚完成了 Task 2。现在请更新进度文件，并准备开始 Task 3。请回顾 AI_SPEC.md 中关于认证模块的定义。"

---

五、提升生成质量的 3 个技巧

5.1 使用“伪代码”约束函数签名

在 AI_SPEC.md 中，直接写出你期望的函数定义，AI 填充内部逻辑的准确率远高于让它自己设计。

# 期望函数签名
# 请在 service 层实现以下接口
async def create_user(
    db: AsyncSession, 
    user_in: UserCreateSchema, 
    tenant_id: UUID
) -> User:
    """创建新用户，自动处理密码哈希"""
    pass

5.2 提供“少样本” (Few-Shot)

如果在 AI_SPEC.md 中能提供一个“完美代码示例”，AI 会模仿这个风格。

# 代码风格示例
# 请参考以下依赖注入的写法（不要使用全局变量）：
async def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: AsyncSession = Depends(get_db)
) -> User:
    ...

5.3 强制自检 (Self-Correction)

在每个任务结束时，要求 AI 进行自检。

Prompt: "在输出最终代码前，请检查：

1. 是否所有导入路径都正确？

2. 是否处理了数据库会话未关闭的风险？

3. 类型提示是否完整？ 如有问题，请先自我修正。"

---

六、总结

使用 Cursor 或 Trea 进行开发时，文档的质量直接决定了代码的质量。

1. .cursorrules 是项目的“宪法”，定义技术底线。

2. AI_SPEC.md 是项目的“蓝图”，定义业务细节。

3. ROADMAP.md 是项目的“日志”，管理开发状态。

4. 原子化任务 是核心策略，避免上下文过载。

通过这套标准化模板，可以将 AI 从一个“随机代码生成器”转变为一个“可控的结对编程伙伴”，大幅减少调试时间，提升项目交付效率。