Prompt工程06：文档上下文
从PRD、设计文档、接口文档到历史决策，理解如何为模型提供有效的文档上下文。
文档上下文是让模型理解业务需求和技术决策的关键。好的文档上下文能让模型更准确地理解需求背景，输出符合业务目标的结果。
文档上下文的重要性
缺少文档上下文的问题
当模型没有足够的文档上下文时：
用户输入：
帮我实现用户登录功能。问题：
- 模型不知道登录流程是什么
- 不知道安全要求是什么
- 不知道与其他系统的交互
- 不知道历史决策和技术债务
有文档上下文的效果
用户输入：
[PRD 摘要]
功能：用户登录
目标：支持手机号、邮箱、第三方登录
安全要求：密码 BCrypt 加密，登录失败5次锁定账号
[设计文档]
架构：前后端分离
认证方式：JWT Token
会话管理：无状态，Token 有效期2小时
[接口文档]
POST /api/login
请求：{"username": "xxx", "password": "xxx", "type": "phone"}
响应：{"token": "xxx", "expiresAt": "xxx"}
[历史决策]
- 选择 JWT 而非 Session，因为要支持多端
- 选择 BCrypt 而非 MD5，因为安全性更高效果：模型可以准确理解业务需求、技术方案和约束条件，输出符合预期的代码。
文档上下文的类型
常见文档类型
| 文档类型 | 内容 | 作用 |
|---|---|---|
| PRD | 产品需求文档 | 理解业务目标和功能需求 |
| 设计文档 | 技术设计文档 | 理解架构方案和实现细节 |
| 接口文档 | API 文档 | 理解接口契约和数据格式 |
| 变更日志 | 历史变更记录 | 理解演进过程和技术债务 |
| 决策记录 | 技术决策文档 | 理解为什么做这个选择 |
文档上下文层次
层次1：业务上下文
├── PRD（产品需求）
├── 业务流程（用户旅程）
└── 业务规则（业务逻辑）
层次2：技术上下文
├── 设计文档（架构方案）
├── 接口文档（API 契约）
└── 数据库设计（数据模型）
层次3：历史上下文
├── 变更日志（版本演进）
├── 决策记录（技术取舍）
└── 技术债务（已知问题）如何提供文档上下文
PRD 摘要
[PRD 摘要]
产品名称：电商平台
功能模块：用户认证
需求描述：
1. 支持手机号登录（验证码）
2. 支持邮箱登录（密码）
3. 支持微信、支付宝第三方登录
4. 登录失败5次后锁定账号15分钟
5. 登录成功后返回 JWT Token
业务目标：
- 提升用户登录体验
- 保障账号安全
- 支持多端登录（Web、APP、小程序）设计文档
[设计文档]
架构风格：前后端分离，无状态认证
核心组件：
1. AuthController - 认证 API 入口
2. AuthService - 认证业务逻辑
3. UserRepository - 用户数据访问
4. JwtUtil - JWT Token 工具类
5. RateLimitFilter - 登录限流
关键流程：
1. 用户提交登录请求
2. 验证账号是否锁定
3. 验证用户名和密码
4. 生成 JWT Token
5. 返回 Token 和过期时间
安全设计：
- 密码使用 BCrypt 加密存储
- JWT Token 使用非对称加密
- 登录接口添加限流（10次/分钟）接口文档
[接口文档]
1. 手机号登录
POST /api/auth/login/phone
请求：
{
"phone": "13800138000",
"code": "123456"
}
成功响应：
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresAt": "2024-01-15T12:00:00",
"user": {"id": 1, "phone": "13800138000", "nickname": "张三"}
}
失败响应：
{
"error": "INVALID_CODE",
"message": "验证码错误"
}
2. 邮箱登录
POST /api/auth/login/email
请求：
{
"email": "user@example.com",
"password": "password123"
}决策记录
[决策记录]
决策1：使用 JWT 而非 Session
原因：
- 需要支持多端登录（Web、APP、小程序）
- 无状态设计便于水平扩展
- 避免 Session 共享问题
决策2：密码使用 BCrypt 加密
原因：
- BCrypt 是业界标准，安全性高
- 支持加盐，防止彩虹表攻击
- Spring Security 原生支持
决策3：登录失败5次锁定
原因：
- 防止暴力破解攻击
- 15分钟锁定时间平衡安全和用户体验
- 支持管理员手动解锁
决策4：不支持用户名登录
原因：
- 用户名容易被猜测
- 手机号/邮箱更安全
- 符合用户习惯文档上下文的格式
结构化文档上下文
[业务背景]
产品：电商平台
模块：用户认证
目标：实现安全、便捷的多端登录
[PRD 需求]
1. 支持手机号验证码登录
2. 支持邮箱密码登录
3. 支持第三方登录
4. 登录失败5次锁定
[技术设计]
架构：无状态 JWT 认证
加密：BCrypt 密码加密
限流：10次/分钟
[接口规范]
POST /api/auth/login/[type]
返回：JWT Token + 用户信息
[历史决策]
- 选择 JWT 支持多端
- 选择 BCrypt 保证安全文档上下文组织原则
| 原则 | 说明 | 示例 |
|---|---|---|
| 摘要优先 | 先给文档摘要，再给详细内容 | 先给 PRD 摘要，再给完整 PRD |
| 重点突出 | 标注关键信息 | 使用加粗或高亮 |
| 引用来源 | 注明文档来源 | PRD 文档 v2.1 |
| 版本管理 | 注明文档版本 | 设计文档 v1.0 |
文档上下文的常见问题
问题1：文档缺失
表现：没有相关文档
解决方案：
- 从代码中反推设计意图
- 询问相关人员
- 创建临时文档记录
问题2：文档过时
表现：文档内容与实际代码不一致
解决方案：
- 以代码为准
- 更新文档
- 注明文档版本和更新时间
问题3：文档冗长
表现：文档内容太多，占用 Token
解决方案：
- 提取关键信息
- 使用摘要代替完整文档
- 提供文档链接
问题4：文档冲突
表现：不同文档之间内容不一致
解决方案：
- 确认最新版本
- 与相关人员沟通
- 记录冲突并说明
文档上下文的工具支持
文档管理工具
| 工具 | 功能 | 适用场景 |
|---|---|---|
| Confluence | 团队文档管理 | 大型团队 |
| Notion | 灵活文档管理 | 小型团队 |
| 飞书文档 | 协作文档 | 中文团队 |
| Markdown | 轻量文档 | 个人项目 |
文档提取工具
| 工具 | 功能 | 适用场景 |
|---|---|---|
| Pandoc | 文档格式转换 | 多格式文档 |
| Docx2txt | Word 转文本 | Word 文档 |
| PDFMiner | PDF 文本提取 | PDF 文档 |
文档上下文的最佳实践
开发中的文档上下文
角色：你是后端开发工程师
目标：实现用户登录功能
[业务背景]
产品：电商平台
模块：用户认证
[PRD 需求]
1. 手机号验证码登录
2. 邮箱密码登录
3. 登录失败5次锁定15分钟
[技术设计]
- JWT 无状态认证
- BCrypt 密码加密
- Redis 存储锁定状态
[接口规范]
POST /api/auth/login/phone
POST /api/auth/login/email
[代码约束]
- 使用 Spring Boot 3.2
- 使用 Spring Security代码审查中的文档上下文
角色：你是代码审查员
目标：审查登录功能的安全性
[业务背景]
这是核心认证模块，涉及用户账号安全
[安全要求]
- 密码必须加密存储
- 必须防止暴力破解
- Token 必须安全传输
[代码]
待审查的代码
[检查清单]
1. 密码是否使用 BCrypt 加密？
2. 是否有限流或锁定机制？
3. Token 是否使用 HTTPS 传输？排障中的文档上下文
角色：你是运维工程师
目标：排查登录接口响应慢的问题
[系统架构]
登录请求流程：
客户端 → Nginx → Gateway → AuthService → Redis + MySQL
[监控指标]
- P99 响应时间：2s
- 数据库查询耗时：500ms
- Redis 查询耗时：10ms
[相关日志]
慢查询日志、错误日志项目判断清单
- 模型不理解业务需求 → 提供 PRD 摘要
- 模型不知道技术方案 → 提供设计文档
- 模型不了解接口规范 → 提供接口文档
- 需要理解历史决策 → 提供决策记录
- Token 预算有限 → 使用文档摘要
- 文档缺失 → 从代码反推或询问相关人员
- 文档过时 → 更新文档或注明版本
- 需要长期维护 → 建立文档管理机制