AI项目开发文档准备清单
AI 项目开发文档准备清单
完整清单。按依赖关系从上到下排列——上层文档是下层的输入。
一、战略与商业层
项目立项前必须对齐，否则后续所有文档都会偏。
1.1 商业画布
- 价值主张：解决什么问题，为谁解决
- 收入模式：怎么赚钱（或成本中心的预算来源）
- 核心指标：DAU、GMV、转化率等北极星指标
1.2 目标用户画像
- 用户是谁（角色、年龄、场景）
- 核心痛点和使用动机
- 用户分层（管理员 / 普通用户 / 游客等）
1.3 竞品分析
- 对标产品及其优劣
- 本项目的差异化定位
1.4 成功标准
- 上线后用什么指标判断项目成功
- 验收的最低标准（MVP 定义）
二、需求层
描述”做什么”。
2.1 需求文档（PRD）
- 项目背景和目标
- 功能需求清单（按模块组织）
- 非功能需求（性能、安全、可用性、兼容性）
- 优先级排序（P0/P1/P2）
- 明确的排除项（“本期不做 XX”）
2.2 用户故事
- 每个故事：角色 + 行为 + 目的
- 验收标准（Given/When/Then）
- 依赖关系（故事 A 完成后才能做故事 B）
2.3 用例文档
- 核心业务场景的完整路径
- 主流程 + 备选流程 + 异常流程
- 前置条件和后置条件
2.4 业务规则清单
- 所有业务约束的穷举（“余额不能为负”、“VIP 用户每日限额 10 次”）
- 规则之间的优先级和冲突处理
- 规则的生效条件和失效条件
2.5 数据字典 / 术语表
- 项目中所有专有名词的定义
- 字段级别的业务含义（“订单金额”含不含税？）
- 消歧义（“用户”是指登录账号还是注册实体？）
三、设计层
描述”怎么做”，是 AI 编码的直接输入。
3.1 原型 / 交互设计
- 页面结构和布局
- 交互流程（点击 A → 跳转 B → 弹窗 C）
- 异常态设计（加载中、空数据、错误、网络断开）
- 响应式断点（移动端 / 平板 / 桌面）
3.2 视觉规范
- 色彩体系（主色、辅色、语义色）
- 字体和排版规则
- 间距和圆角规范
- 组件库选择或自定义设计系统
3.3 架构设计
- 模块/服务划分：每个模块的职责边界
- 分层架构：Controller → Service → Repository，每层能做什么、不能做什么
- 服务间通信：同步调用 / 异步消息 / 事件驱动
- 关键交互流程：核心链路的时序图（同步 vs 异步、数据流转）
- 部署拓扑：几个服务、几个实例、怎么部署
- 技术约束：不允许跨层调用、不允许循环依赖等可执行规则
3.4 模型设计（领域模型）
- 核心实体：属性 + 行为 + 不变量
- 值对象：不可变的业务概念（金额、地址、坐标）
- 聚合与边界：哪些实体必须一起操作、事务边界在哪
- 领域事件：什么动作触发什么事件、事件通知谁
- 模型间关系：谁拥有谁、级联规则、引用方式
- 业务规则在模型上的体现：规则绑定到哪个实体的哪个方法
3.5 状态机设计
- 核心业务对象的所有状态
- 状态之间的合法转换路径
- 每次转换的触发条件和副作用（“支付成功 → 已支付，同时扣库存”）
- 非法转换的处理方式（忽略 / 报错 / 日志告警）
3.6 API 接口契约
- 每个接口：路径、方法、请求参数、响应结构、错误码
- 认证方式（JWT / Session / API Key）
- 分页约定（offset-based / cursor-based）
- 版本策略（/v1/ /v2/ 还是 Header 版本号）
- 限流规则
- 前后端共用的类型定义（TypeScript interface / Protobuf）
3.7 权限模型
- 角色定义（管理员、运营、普通用户等）
- 每个角色能访问哪些接口、操作哪些数据
- 数据权限（本人数据 / 部门数据 / 全局数据）
- 接口级 + 字段级权限控制
- 前端菜单/按钮的显隐规则
3.8 数据流设计
- 数据从哪来、经过哪些处理、到哪去
- 批量数据 vs 实时数据的处理路径
- 数据同步方案（哪些数据需要同步、延迟容忍度）
四、技术层
描述”用什么、怎么约束”。
4.1 技术栈选型
- 语言和版本（Node 20 / Python 3.12 / Go 1.22）
- 框架和版本（Express / FastAPI / Gin）
- 数据库和版本（PostgreSQL 16 / Redis 7）
- 关键依赖库及其版本锁定
- 选型理由（为什么选 A 不选 B）
4.2 项目脚手架
- 目录结构及每个目录的职责
- 入口文件和启动流程
- 环境变量清单及默认值
- Docker / docker-compose 配置
- CI/CD 流水线配置
4.3 数据库表结构
- 所有表的字段、类型、约束（NOT NULL / UNIQUE / DEFAULT）
- 主键和外键
- 索引策略（哪些字段建索引、联合索引顺序）
- 软删除 vs 硬删除约定
- 审计字段约定（created_at / updated_at / deleted_at）
- 分表策略（如果需要）
4.4 编码规范（AGENTS.md）
- 命名约定（变量、函数、文件、目录）
- 文件组织规则（一个文件多少行以内、一个函数多少行以内）
- 错误处理模式（统一的错误类、错误码体系）
- 日志规范（日志级别、格式、必须包含的字段）
- 注释规范（什么时候写、写什么）
- Git 提交规范（commit message 格式、分支命名）
- Lint 和格式化规则
4.5 错误处理规范
- 统一错误码体系（业务错误码 + HTTP 状态码映射）
- 用户可见错误 vs 内部日志错误的区分
- 前后端错误响应的统一 JSON 格式
- 全局异常捕获策略
- 第三方服务调用失败的降级方案
4.6 安全规范
- 输入校验规则（所有外部输入必须校验）
- SQL 注入 / XSS / CSRF 防护标准
- 敏感数据处理（加密存储、脱敏展示、日志中不打印）
- API 限流和防刷策略
- 认证和会话管理（Token 有效期、刷新机制、登出处理）
- CORS 策略
- 文件上传安全（类型检查、大小限制、病毒扫描）
4.7 测试策略
- 分层测试目标（单元 / 集成 / E2E 各占多少）
- 覆盖率目标（核心模块 100%，辅助模块 80%？）
- Mock 策略（外部服务怎么 Mock、数据库怎么 Mock）
- 测试数据管理（测试数据怎么构造、怎么隔离）
- 性能测试目标（QPS、P99 延迟）
4.8 第三方服务集成规范
- 每个外部服务的 API 文档链接
- 认证方式和密钥管理
- SDK 版本和封装方式
- 限流和重试策略
- 降级和熔断方案
- Webhook 回调处理规范
4.9 缓存策略
- 哪些数据需要缓存、缓存多久
- 缓存更新策略（Cache-Aside / Write-Through / Write-Behind）
- 缓存穿透 / 击穿 / 雪崩的防护
- 缓存 key 命名规范
4.10 国际化 / 本地化
- 支持哪些语言
- 文案管理方式（硬编码 / 配置文件 / 平台管理）
- 日期、货币、数字的格式化规则
- 时区处理策略
五、运维层
描述”上线后怎么保障”。
5.1 部署方案
- 环境划分（开发 / 测试 / 预发 / 生产）
- 部署方式（容器 / 虚拟机 / Serverless）
- 部署流程和回滚方案
- 灰度发布策略
5.2 监控与告警
- 关键业务指标监控（注册量、订单量、支付成功率）
- 系统指标监控（CPU / 内存 / 磁盘 / 网络）
- 应用指标监控（QPS / 延迟 / 错误率）
- 告警规则和通知渠道
- 日志采集和查询方案
5.3 备份与恢复
- 数据备份策略（全量 / 增量、频率、保留时长）
- 恢复流程和 RTO/RPO 目标
- 灾难恢复方案
5.4 数据迁移方案（如有）
- 旧系统数据怎么迁移到新系统
- 迁移脚本和验证方式
- 迁移期间的数据一致性保障
- 回滚方案
六、协作层
团队怎么配合 AI 工作。
6.1 AI Agent 配置
- 每个 Agent 的职责分工（哪些文件归哪个 Agent 改）
- Agent 之间的依赖关系
- 上下文传递规则（一个 Agent 的输出怎么给另一个用）
6.2 代码审查标准
- PR 必须检查的项（类型安全、错误处理、测试覆盖）
- AI 生成代码的额外审查点
- 性能和安全的红线
6.3 里程碑和交付节奏
- 分几个阶段交付
- 每个阶段的交付物和验收标准
- 评审节点和决策点
依赖关系图
商业画布 ──→ 用户画像 ──→ 需求文档(PRD)
│
┌───────────┼───────────┐
↓ ↓ ↓
用户故事 用例文档 业务规则清单
│ │ │
└───────────┼───────────┘
↓
数据字典
│
┌───────────┼───────────┐
↓ ↓ ↓
原型设计 架构设计 模型设计
│ │ │
↓ │ ┌────┴────┐
视觉规范 │ 状态机 权限模型
│ │ │
┌───────────┼──────┼────────┘
↓ ↓ ↓
API 契约 数据流设计 │
│ │
└─────────┬─────────┘
↓
技术栈选型
│
┌─────────┼─────────┐
↓ ↓ ↓
项目脚手架 数据库表结构 编码规范
│ │
┌─────────┼─────────┤
↓ ↓ ↓
错误处理规范 安全规范 测试策略
│ │ │
↓ ↓ ↓
第三方集成 缓存策略 国际化
│
↓
部署方案
│
┌─────────┼─────────┐
↓ ↓ ↓
监控告警 备份恢复 数据迁移
快速检查：你的项目准备好了吗？
| # | 文档 | 是否准备 | 优先级 |
|---|---|---|---|
| 1 | 商业画布 | ☐ | 战略层 |
| 2 | 用户画像 | ☐ | 战略层 |
| 3 | 竞品分析 | ☐ | 战略层 |
| 4 | 成功标准 | ☐ | 战略层 |
| 5 | 需求文档（PRD） | ☐ | 🔴 必须 |
| 6 | 用户故事 | ☐ | 🔴 必须 |
| 7 | 用例文档 | ☐ | 🔴 必须 |
| 8 | 业务规则清单 | ☐ | 🔴 必须 |
| 9 | 数据字典 / 术语表 | ☐ | 🔴 必须 |
| 10 | 原型 / 交互设计 | ☐ | 🔴 必须 |
| 11 | 视觉规范 | ☐ | 🟡 强烈建议 |
| 12 | 架构设计 | ☐ | 🔴 必须 |
| 13 | 模型设计 | ☐ | 🔴 必须 |
| 14 | 状态机设计 | ☐ | 🔴 必须 |
| 15 | API 接口契约 | ☐ | 🔴 必须 |
| 16 | 权限模型 | ☐ | 🔴 必须 |
| 17 | 数据流设计 | ☐ | 🟡 强烈建议 |
| 18 | 技术栈选型 | ☐ | 🔴 必须 |
| 19 | 项目脚手架 | ☐ | 🔴 必须 |
| 20 | 数据库表结构 | ☐ | 🔴 必须 |
| 21 | 编码规范（AGENTS.md） | ☐ | 🔴 必须 |
| 22 | 错误处理规范 | ☐ | 🔴 必须 |
| 23 | 安全规范 | ☐ | 🔴 必须 |
| 24 | 测试策略 | ☐ | 🟡 强烈建议 |
| 25 | 第三方服务集成规范 | ☐ | 🟡 强烈建议 |
| 26 | 缓存策略 | ☐ | 🟡 强烈建议 |
| 27 | 国际化 / 本地化 | ☐ | 🟢 按需 |
| 28 | 部署方案 | ☐ | 🟡 强烈建议 |
| 29 | 监控与告警 | ☐ | 🟡 强烈建议 |
| 30 | 备份与恢复 | ☐ | 🟢 按需 |
| 31 | 数据迁移方案 | ☐ | 🟢 按需 |
| 32 | AI Agent 配置 | ☐ | 🟡 强烈建议 |
| 33 | 代码审查标准 | ☐ | 🟡 强烈建议 |
| 34 | 里程碑和交付节奏 | ☐ | 🟡 强烈建议 |