📋 文档与任务模板
用少量真实记录，证明项目是怎样一步步做出来的
项目文档不是期末补交的一叠文字
立项书帮助控制范围，需求说明书明确做到什么程度，系统设计说明书指导开发，任务卡和周报记录过程，测试与验收记录证明系统真实运行。
模板的作用是提醒你保存关键事实和证据，不是让每个人填写一模一样的长文档。项目越小，文档可以越简洁，但不能缺少业务依据、修改过程和验证结果。
模板使用原则
根据课程阶段选择需要的模板，复制到自己的项目仓库后再填写。删除不适用的占位说明，保留仍需确认的问题，不要让 AI 编造调研、测试、人员贡献或教师结论。
查看课程阶段与弹性路线
进入项目选题与需求分析
进入原型与系统设计
🗺️ 每个阶段使用什么模板
| 阶段 |
推荐模板 |
解决的问题 |
主要证据 |
| 项目选题 |
项目选题与立项书 |
为什么做、给谁用、做多大 |
调研来源、范围和风险 |
| 需求分析 |
需求分析说明书 |
系统必须做什么、怎样算完成 |
角色、场景、规则和验收条件 |
| 系统设计 |
系统设计说明书 |
准备怎样实现 |
架构、页面、数据、接口和权限 |
| 项目开发 |
开发任务卡 |
当前只完成哪一个小任务 |
改动文件、验证方法和 Git 提交 |
| AI 协作 |
AI 协作记录 |
AI 提了什么、人做了什么决定 |
提示词、采纳理由和验证结果 |
| 每周推进 |
项目周报 |
本周产生了什么可运行成果 |
提交、截图、问题和下周计划 |
| 测试修复 |
测试用例与缺陷记录 |
系统是否符合需求，问题怎样关闭 |
实际结果、日志和复核记录 |
| 阶段验收 |
集成验收记录 |
当前版本能否进入下一阶段 |
核心流程、问题清单和版本标签 |
| 项目交付 |
项目 README |
别人怎样理解、运行和体验项目 |
环境、命令、账号、截图和地址 |
同一个事实不要在多个文档里反复维护
需求规则以《需求分析说明书》为准，技术和接口以《系统设计说明书》为准，实际启动方式以 README 为准。其他记录通过编号或链接引用它们，避免复制后互相矛盾。
📁 推荐的项目文档目录
可以在学生项目根目录使用下面的结构：
| 项目根目录/
├── README.md
├── AGENTS.md
├── docs/
│ ├── 01-项目选题立项书.md
│ ├── 02-需求分析说明书.md
│ ├── 03-系统设计说明书.md
│ ├── 04-测试报告.md
│ ├── tasks/
│ │ ├── TASK-001-项目启动.md
│ │ └── TASK-002-第一个模块.md
│ ├── reviews/
│ │ ├── 需求评审记录.md
│ │ └── 系统设计评审记录.md
│ ├── progress/
│ │ └── 第01周周报.md
│ └── acceptance/
│ └── v0.5-集成验收记录.md
├── sql/
└── src/ 或 backend/、frontend/
|
目录和文件名可以根据项目调整。重要的是：
- 最新版本容易找到；
- 临时草稿与正式文档分开；
- 图片和附件使用相对路径；
- 文档中的编号稳定；
- 变更能够通过 Git 查看；
- 不保存真实账号、密码、密钥和隐私数据。
✍️ 填写模板时遵守 6 条规则
- 写真实事实：没有访谈就不要写“经过大量用户调研”。
- 写具体结果：不要只写“功能完善”“测试正常”“体验良好”。
- 保留待确认项：使用
【待确认：具体问题】，不要让 AI 猜答案。
- 附上验证证据：记录命令、响应、截图、日志、数据库结果或提交编号。
- 及时更新版本：需求、设计或接口发生变化时，同步更新关联材料。
- 控制篇幅：课程项目优先清楚、可用和相互一致，不追求空泛的长文档。
💡 模板一：项目选题与立项书
适用阶段：项目选题和立项评审。
详细方法参见第二篇：项目选题与需求分析。
| # 【项目名称】项目选题立项书
## 1. 项目基本信息
- 项目名称：
- 项目负责人：
- 团队成员：
- 计划周期：
- 当前版本：
## 2. 项目背景
- 目标用户：
- 用户当前怎样完成任务：
- 当前存在的具体问题：
- 问题依据或调研来源：
## 3. 项目目标
- 本项目准备解决：
- 用户完成任务后获得：
- 可以观察或验收的结果：
## 4. 核心业务闭环
【角色】发起……
→ 【角色或系统】处理……
→ 【用户】获得……
## 5. 项目范围
### 5.1 本期必做
- （填写本期必须完成的内容）
### 5.2 选做
- （填写时间允许时再完成的内容）
### 5.3 本期不做
- （填写主动排除的内容）
## 6. 可行性
- 技术基础：
- 数据来源：
- 开发和部署环境：
- 时间与人员：
## 7. 初步计划
| 阶段 | 主要任务 | 可检查成果 | 计划时间 |
| --- | --- | --- | --- |
| 需求 | | | |
| 设计 | | | |
| 开发 | | | |
| 测试部署 | | | |
## 8. 风险与应对
| 风险 | 可能影响 | 应对办法 |
| --- | --- | --- |
| | | |
## 9. AI 使用说明
- 计划使用 AI 辅助：
- 必须由人工确认：
## 10. 评审结论
- 通过 / 修改后通过 / 不通过
- 主要修改要求：
- 确认人及日期：
|
立项书最低要求
- 用户和问题具体；
- 核心业务形成闭环；
- 必做范围能够在课程周期内完成；
- 选做和不做内容明确；
- 风险具有可执行的应对办法；
- 调研和评审结论没有虚构。
👥 模板二：需求分析说明书
适用阶段：从立项范围形成可开发、可测试的需求。
详细方法参见第二篇：项目选题与需求分析。
| # 【项目名称】需求分析说明书
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 版本 | V0.1 |
| 状态 | 草稿 / 待评审 / 已确认 |
| 编写人 | |
| 日期 | |
## 1. 项目概述与范围
- 项目目标：
- 目标用户：
- 核心业务闭环：
- 本期必做：
- 选做：
- 本期不做：
## 2. 用户角色与权限
| 角色 | 使用目标 | 主要操作 | 数据范围 | 不能做什么 |
| --- | --- | --- | --- | --- |
| | | | | |
## 3. 核心使用场景
### SC-模块-01【场景名称】
- 参与角色：
- 触发条件：
- 用户目标：
- 前置条件：
- 正常过程：
- 预期结果：
- 异常情况：
## 4. 功能需求
| 编号 | 功能 | 角色 | 前置条件 | 输入 | 系统处理 | 结果 | 优先级 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| FR-模块-01 | | | | | | | 必做 |
## 5. 核心业务流程与状态
- 流程图：
- 状态说明：
| 当前状态 | 允许操作 | 操作角色 | 下一状态 | 禁止操作 |
| --- | --- | --- | --- | --- |
| | | | | |
## 6. 业务规则与异常
| 编号 | 规则 | 对应功能 | 违反时的处理 |
| --- | --- | --- | --- |
| BR-模块-01 | | FR-* | |
## 7. 非功能要求
- 权限与数据安全：
- 可用性：
- 运行环境：
- 其他实际要求：
## 8. 验收条件
### AC-模块-01
- 对应需求：
- 给定：
- 当：
- 那么：
## 9. 待确认事项
| 编号 | 问题 | 影响 | 确认人 | 状态 |
| --- | --- | --- | --- | --- |
| Q-01 | | | | 待确认 |
## 10. 变更记录
| 版本 | 日期 | 修改内容 | 修改人 | 确认状态 |
| --- | --- | --- | --- | --- |
| | | | | |
|
需求不是页面菜单清单
每项核心需求应说明谁在什么条件下输入什么、系统怎样处理、成功后改变什么、失败时怎样处理。
🏗️ 模板三：系统设计说明书
适用阶段：把已经确认的需求转化为实现方案。
详细方法参见第三篇：原型与系统设计。
| # 【项目名称】系统设计说明书
## 文档信息
| 项目 | 内容 |
| --- | --- |
| 版本 | V0.1 |
| 需求基线 | 《需求分析说明书》V__ |
| 状态 | 草稿 / 待评审 / 已确认 |
| 编写人 | |
## 1. 设计目标、约束与技术选型
- 设计目标：
- 项目约束：
| 领域 | 采用方案 | 选择依据 | 风险与应对 |
| --- | --- | --- | --- |
| 前端 | | | |
| 后端 | | | |
| 数据库 | | | |
| 部署 | | | |
## 2. 系统架构与功能模块
- 总体架构图：
- 核心请求流程：
| 模块编号 | 模块名称 | 对应需求 | 职责 | 依赖 | 边界 |
| --- | --- | --- | --- | --- | --- |
| MOD-01 | | FR-* | | | |
## 3. 页面与用户流程
| 页面编号 | 页面名称 | 角色 | 对应需求 | 主要信息 | 主要操作 |
| --- | --- | --- | --- | --- | --- |
| UI-01 | | | FR-* | | |
- 核心页面流程：
- 加载、空数据、失败和无权限状态：
## 4. 数据库设计
- E-R 图：
| 表名 | 业务含义 | 主键 | 核心字段 | 约束 | 关联表 |
| --- | --- | --- | --- | --- | --- |
| | | | | | |
## 5. 接口设计
| 接口编号 | 方法与路径 | 功能 | 角色 | 前置状态 | 数据变化 |
| --- | --- | --- | --- | --- | --- |
| API-01 | | | | | |
## 6. 权限与业务状态
- 认证方式：
- 功能权限：
- 数据权限：
| 当前状态 | 操作 | 操作角色 | 前置条件 | 下一状态 | 失败结果 |
| --- | --- | --- | --- | --- | --- |
| | | | | | |
## 7. 部署、质量与安全
- 开发与运行环境：
- 配置和密钥管理：
- 日志与异常：
- 数据备份：
- 主要风险：
## 8. 需求—设计追踪
| 需求 | 模块 | 页面 | 接口 | 权限/状态 | 数据表 | 验证方式 |
| --- | --- | --- | --- | --- | --- | --- |
| FR-* | MOD-* | UI-* | API-* | | | AC-* |
## 9. 待确认事项与变更记录
- 待确认事项：
- 文档变更：
|
设计说明书最低要求
- 技术方案符合学生能力和部署环境；
- 页面、接口、权限、状态和数据能够相互对应；
- 核心流程同时说明成功和失败；
- 不使用无需求依据的复杂技术；
- 评审问题已经记录和复核。
🧩 模板四：开发任务卡
适用阶段：每次准备实现一个小功能、修复一个问题或修改一个模块。
| # TASK-___【任务名称】
## 1. 背景与目标
- 对应需求：FR-__
- 当前问题或已有能力：
- 本次完成后用户能够：
## 2. 本次范围
### 要完成
- （填写本任务要完成的内容）
### 明确不做
- （填写本任务不处理的内容）
## 3. 前置条件
- 已阅读：
- 依赖数据或接口：
- 需要确认的问题：
## 4. 实施计划
| 步骤 | 小任务 | 准备修改的文件 | 完成标准 |
| --- | --- | --- | --- |
| 1 | | | |
## 5. 验收标准
- [ ] 正常场景：
- [ ] 输入或边界场景：
- [ ] 未登录或越权场景：
- [ ] 数据库结果：
## 6. 实际改动
| 文件 | 修改目的 | 主要内容 |
| --- | --- | --- |
| | | |
## 7. 验证记录
| 验证方式 | 命令或步骤 | 实际结果 | 证据 |
| --- | --- | --- | --- |
| | | | |
## 8. 遗留问题
- （没有则填写“无”）
## 9. Git 提交
- 提交编号：
- 提交信息：
|
一张任务卡对应一个可以验证的小成果
如果任务卡包含十几个页面、多个模块和完整系统，说明任务仍需继续拆分。
🤖 模板五：AI 协作记录
适用阶段：记录 AI 在分析、设计、编码、调试、测试和评审中的参与。
| # AI 协作记录
## 1. 基本信息
- 日期：
- 当前任务：
- 使用工具或模型：
- 关联任务卡或提交：
## 2. 提供给 AI 的上下文
- 阅读的文档：
- 阅读的代码：
- 明确的范围与禁区：
## 3. 关键提示词
```text
【保留最关键的一到两个提示词】
```
## 4. AI 的主要建议
- （填写 AI 给出的关键建议）
## 5. 人工判断
| 建议 | 采纳/修改/拒绝 | 原因 |
| --- | --- | --- |
| | | |
## 6. 实际修改
- AI 生成：
- 人工调整：
- 最终决定：
## 7. 验证
- 执行命令或操作：
- 实际结果：
- 发现的问题：
- 修复方法：
## 8. 反思
- 下次怎样提供更准确的上下文：
- 哪项知识仍需学习：
|
AI 协作记录不需要保存每一句对话。保留能够说明关键决定、人工修改和验证过程的内容即可。
📅 模板六：项目周报
适用阶段：每周汇总真实进展，支持教师巡查和团队协作。
| # 第__周项目周报
## 1. 本周目标
- （填写本周计划完成的成果）
## 2. 本周完成
| 成果 | 对应需求或任务 | 验证证据 | 状态 |
| --- | --- | --- | --- |
| | | | 已完成/部分完成 |
## 3. Git 提交
| 提交编号 | 提交信息 | 完成人 |
| --- | --- | --- |
| | | |
## 4. 演示说明
- 可以演示的入口：
- 操作步骤：
- 最终结果：
## 5. 遇到的问题
| 问题 | 原因 | 已尝试方法 | 当前状态 |
| --- | --- | --- | --- |
| | | | |
## 6. AI 使用
- AI 参与的任务：
- 人工确认或修改：
- 验证结果：
## 7. 下周计划
| 优先级 | 任务 | 完成标准 | 负责人 |
| --- | --- | --- | --- |
| 必做 | | | |
## 8. 团队贡献
| 成员 | 本周实际贡献 | 提交或证据 |
| --- | --- | --- |
| | | |
|
不要把“学习了技术”“讨论了项目”当作唯一成果。每周尽量提供一个可以运行、查看或验证的变化。
🧪 模板七：测试用例
适用阶段：验证功能、接口、权限、状态和异常情况。
| # 测试用例
| 字段 | 内容 |
| --- | --- |
| 用例编号 | TC-模块-01 |
| 用例名称 | |
| 对应需求 | FR-* / BR-* / AC-* |
| 测试类型 | 功能 / 接口 / 权限 / 边界 / 异常 |
| 前置条件 | 角色、登录状态、初始数据和业务状态 |
| 测试数据 | |
| 操作步骤 | 1. 2. 3. |
| 预期结果 | 页面、接口、数据和最终状态 |
| 实际结果 | |
| 验证证据 | 截图、响应、日志或数据库结果 |
| 结论 | 通过 / 未通过 / 阻塞 |
| 执行人和日期 | |
|
最低测试组合
每个核心功能至少考虑：
- 一个正常场景；
- 一个输入或边界场景；
- 一个未登录或越权场景；
- 一个业务状态不允许场景；
- 一个重复操作场景（实际相关时）。
🐞 模板八：缺陷记录
适用阶段：发现问题、修复问题和执行回归测试。
| # BUG-___【缺陷标题】
## 1. 基本信息
- 发现版本：
- 发现环境：
- 关联需求或测试用例：
- 严重程度：阻断 / 重要 / 一般 / 建议
- 当前状态：待处理 / 处理中 / 待复核 / 已关闭 / 暂缓
## 2. 问题描述
- 预期结果：
- 实际结果：
- 影响：
## 3. 复现步骤
1. （填写第一步）
2. （填写第二步）
3. （填写第三步）
## 4. 证据
- 页面或截图：
- 请求与响应：
- 后端日志：
- 数据库结果：
## 5. 原因分析
- 根本原因：
- 影响范围：
## 6. 修复记录
- 修改文件：
- 修改内容：
- Git 提交：
## 7. 复核
- 原场景结果：
- 相关回归场景：
- 复核人和日期：
- 关闭结论：
|
“已修复”必须有复核证据。只修改代码、没有重新运行原场景，不能关闭缺陷。
✅ 模板九：阶段集成验收记录
适用阶段：中期演示、完整业务验收或进入部署前的阶段门。
详细方法参见第四篇 4.6：集成验收。
| # 【项目名称】阶段集成验收记录
## 1. 基本信息
- 验收版本：
- Git 提交：
- 技术路线：
- 验收环境：
- 验收日期：
- 参与人员：
## 2. 启动与构建
| 检查项 | 命令或方式 | 实际结果 | 结论 |
| --- | --- | --- | --- |
| 数据库初始化 | | | |
| 后端构建 | | | |
| 前端构建 | | | |
| 项目启动 | | | |
## 3. 核心业务流程
- 流程名称：
- 参与角色：
| 步骤 | 角色 | 操作 | 预期结果 | 实际结果 | 证据 |
| --- | --- | --- | --- | --- | --- |
| 1 | | | | | |
## 4. 异常与权限
| 场景 | 预期结果 | 实际结果 | 结论 |
| --- | --- | --- | --- |
| 业务失败 | 拒绝且数据不变 | | |
| 未登录 | 返回 401 | | |
| 越权 | 返回 403 或明确拒绝 | | |
| 重复或边界 | 不产生错误数据 | | |
## 5. 特色功能
- 功能名称：
- 正常结果：
- 失败或降级结果：
- 不适用原因：
## 6. 问题统计
| 等级 | 数量 | 未关闭编号 | 处理计划 |
| --- | ---: | --- | --- |
| 阻断 | | | |
| 重要 | | | |
| 一般 | | | |
| 建议 | | | |
## 7. 验收结论
- 通过 / 修改后通过 / 不通过
- 结论依据：
- 下一步：
- 确认人：
|
📖 模板十：项目 README
适用阶段：从项目启动开始持续维护，交付时形成项目入口。
| # 【项目名称】
## 1. 项目简介
- 目标用户：
- 解决的问题：
- 核心业务流程：
- 当前版本：
## 2. 功能与角色
| 角色 | 主要功能 | 数据范围 |
| --- | --- | --- |
| | | |
## 3. 技术栈
- 前端：
- 后端：
- 数据库：
- 开发与部署工具：
## 4. 项目结构
```text
【只列主要目录并说明职责】
```
## 5. 环境要求
| 工具 | 版本 |
| --- | --- |
| JDK | |
| MySQL | |
## 6. 本地运行
### 6.1 初始化数据库
```bash
【真实可执行命令】
```
### 6.2 配置
- 需要的环境变量：
- 不应提交的配置：
### 6.3 启动后端
```bash
【真实可执行命令】
```
### 6.4 启动前端
```bash
【如适用】
```
### 6.5 访问
- 页面地址：
- 接口地址：
- 测试账号：
## 7. 核心流程
1. （填写第一步）
2. （填写第二步）
3. （填写第三步）
## 8. 测试
```bash
【真实测试命令】
```
## 9. 部署
- 部署地址：
- 部署方式：
- 详细手册：
## 10. 项目截图或演示
- （填写截图位置或演示地址）
## 11. 已知限制与后续计划
- （填写已知限制；没有则填写“无”）
## 12. 团队分工与贡献
| 成员 | 负责内容 | 提交或证据 |
| --- | --- | --- |
| | | |
|
README 中的命令必须真实执行过
不要从其他项目复制端口、目录和启动命令。验收前应让一位没有参与开发的人按照 README 尝试运行。
🔄 模板十一：文档变更记录
适用阶段：需求、设计、接口、数据库或验收结论发生变化时。
| # 文档变更记录
| 版本 | 日期 | 变更内容 | 变更原因 | 影响范围 | 修改人 | 确认状态 |
| --- | --- | --- | --- | --- | --- | --- |
| V0.1 | | 创建初稿 | | | | 待确认 |
## 待同步检查
- [ ] 需求范围
- [ ] 页面原型
- [ ] 接口文档
- [ ] 权限与状态
- [ ] 数据库脚本
- [ ] 代码实现
- [ ] 测试用例
- [ ] README
|
修改一个状态、字段或接口时，不要只更新一份文档。先评估它会影响哪些页面、数据和测试，再同步修改。
🤖 怎样让 AI 帮你填写模板
AI 可以整理已有材料、发现缺项和生成初稿，但不能替你提供不存在的事实。
| 请先阅读当前项目的真实材料和代码。
我要填写：【模板名称】。
本次依据：【列出立项书、需求、设计、代码、测试记录等】。
请遵守：
1. 只使用材料中能够确认的事实；
2. 缺失内容写为“【待确认：具体问题】”；
3. 不虚构用户调研、测试结果、人员贡献和教师意见；
4. 不擅自增加需求、角色、接口或数据表；
5. 输出前检查不同文档的名称、状态和字段是否一致；
6. 列出仍需我人工确认和实际运行验证的内容。
先说明你读取到的依据和缺失项，再填写模板。
|
人工必须核对：
- 事实是否来自真实材料；
- 编号和术语是否一致；
- 测试结果是否实际执行；
- Git 提交是否真实存在；
- 团队贡献是否由成员确认；
- 待确认内容是否被错误写成结论；
- 文档是否与当前代码版本一致。
✅ 提交前统一检查
📝 总结
- 模板服务于项目，不是项目服务于模板：只保留当前阶段真正需要的内容。
- 事实和证据比篇幅重要：命令、响应、日志、截图和提交比空泛描述更有价值。
- 文档要跟着项目更新：需求、设计、代码和测试必须使用同一套业务语言。
- AI 可以整理，不能编造：调研、测试、贡献和评审结论必须由人确认。
- 最终形成完整过程链：立项有范围、需求可验收、设计能落地、开发有记录、测试有证据、交付能复现。
查看课程阶段与弹性路线
进入第四篇：项目开发与业务实现