8.7 KiB
Dev Docs 模式
一种在 Claude Code 会话和上下文重置之间维护项目上下文的方法论。
问题
上下文重置会丢失一切：
- 实施决策
- 关键文件及其用途
- 任务进度
- 技术约束
- 为什么选择某些方法
重置后，Claude 必须重新发现一切。
解决方案：持久化开发文档
一个三文件结构，捕获继续工作所需的一切：
dev/active/[task-name]/
├── [task-name]-plan.md # 战略计划
├── [task-name]-context.md # 关键决策和文件
└── [task-name]-tasks.md # 清单格式
这些文件在上下文重置后仍然存在 - Claude 读取它们即可立即恢复状态。
三文件结构
1. [task-name]-plan.md
用途： 实施战略计划
包含：
- 执行摘要
- 当前状态分析
- 提议的未来状态
- 实施阶段
- 带有验收标准的详细任务
- 风险评估
- 成功指标
- 时间线估算
何时创建： 复杂任务开始时
何时更新： 范围变更或发现新阶段时
示例：
# 功能名称 - 实施计划
## 执行摘要
我们正在构建什么以及为什么
## 当前状态
我们现在在哪里
## 实施阶段
### 阶段 1：基础设施（2 小时）
- 任务 1.1：设置数据库模式
- 验收：模式编译，关系正确
- 任务 1.2：创建服务结构
- 验收：所有目录已创建
### 阶段 2：核心功能（3 小时）
...
2. [task-name]-context.md
用途： 继续工作的关键信息
包含：
- SESSION PROGRESS 部分（经常更新！）
- 已完成与进行中的内容
- 关键文件及其用途
- 做出的重要决策
- 发现的技术约束
- 相关文件的链接
- 快速恢复说明
何时创建： 任务开始时
何时更新： 经常 - 在重大决策、完成或发现之后
示例：
# 功能名称 - 上下文
## SESSION PROGRESS (2025-10-29)
### ✅ 已完成
- 数据库模式已创建（User、Post、Comment 模型）
- PostController 已实施，使用 BaseController 模式
- Sentry 集成正常工作
### 🟡 进行中
- 创建具有业务逻辑的 PostService
- 文件：src/services/postService.ts
### ⚠️ 阻碍
- 需要决定缓存策略
## 关键文件
**src/controllers/PostController.ts**
- 扩展 BaseController
- 处理帖子的 HTTP 请求
- 委托给 PostService
**src/services/postService.ts**（进行中）
- 帖子操作的业务逻辑
- 接下来：添加缓存
## 快速恢复
要继续：
1. 阅读此文件
2. 继续实施 PostService.createPost()
3. 查看任务文件了解剩余工作
关键： 每次完成重要工作后更新 SESSION PROGRESS 部分！
3. [task-name]-tasks.md
用途： 跟踪进度的清单
包含：
- 按逻辑部分分解的阶段
- 复选框格式的任务
- 状态指示符（✅/🟡/⏳）
- 验收标准
- 快速恢复部分
何时创建： 任务开始时
何时更新： 完成每个任务或发现新任务后
示例：
# 功能名称 - 任务清单
## 阶段 1：设置 ✅ 完成
- [x] 创建数据库模式
- [x] 设置控制器
- [x] 配置 Sentry
## 阶段 2：实施 🟡 进行中
- [x] 创建 PostController
- [ ] 创建 PostService（进行中）
- [ ] 创建 PostRepository
- [ ] 使用 Zod 添加验证
## 阶段 3：测试 ⏳ 未开始
- [ ] 服务的单元测试
- [ ] 集成测试
- [ ] 手动 API 测试
何时使用开发文档
用于：
- ✅ 复杂的多日任务
- ✅ 有很多移动部分的功能
- ✅ 可能跨越多个会话的任务
- ✅ 需要仔细规划的工作
- ✅ 重构大型系统
跳过：
- ❌ 简单错误修复
- ❌ 单文件更改
- ❌ 快速更新
- ❌ 琐碎修改
经验法则： 如果需要超过 2 小时或跨越多个会话，使用开发文档。
开发文档工作流程
开始新任务
-
使用 /dev-docs 斜杠命令：
/dev-docs 重构认证系统 -
Claude 创建三个文件：
- 分析需求
- 检查代码库
- 创建综合计划
- 生成上下文和任务文件
-
审查和调整：
- 检查计划是否合理
- 添加任何缺失的考虑
- 调整时间线估算
实施期间
- 参考计划 了解整体策略
- 频繁更新 context.md：
- 标记已完成的工作
- 记录做出的决策
- 添加阻碍
- 在 tasks.md 中勾选任务 完成时
上下文重置后
- Claude 读取所有三个文件
- 在几秒内理解完整状态
- 从上次离开的确切位置继续
无需解释您在做什么 - 一切都已记录！
与斜杠命令集成
/dev-docs
创建： 任务的新开发文档
用法：
/dev-docs 实施实时通知
生成：
dev/active/implement-real-time-notifications/- implement-real-time-notifications-plan.md
- implement-real-time-notifications-context.md
- implement-real-time-notifications-tasks.md
/dev-docs-update
更新： 上下文重置前的现有开发文档
用法：
/dev-docs-update
更新：
- 标记已完成的任务
- 添加发现的新任务
- 使用会话进度更新上下文
- 捕获当前状态
使用时机： 接近上下文限制或会话结束时
文件组织
dev/
├── README.md # 本文件
├── active/ # 当前工作
│ ├── task-1/
│ │ ├── task-1-plan.md
│ │ ├── task-1-context.md
│ │ └── task-1-tasks.md
│ └── task-2/
│ └── ...
└── archive/ # 已完成的工作（可选）
└── old-task/
└── ...
active/：正在进行的工作 archive/：已完成的任务（供参考）
示例：实际使用
查看此仓库中的 dev/active/public-infrastructure-repo/ 了解真实示例：
- plan.md - 创建此展示库的 700+ 行战略计划
- context.md - 跟踪已完成内容、做出决策、下一步
- tasks.md - 所有阶段和任务的清单
这是用于构建此展示库的实际开发文档！
最佳实践
频繁更新上下文
不好： 仅在会话结束时更新 好： 在每个重要里程碑后更新
SESSION PROGRESS 部分应始终反映现实：
## SESSION PROGRESS (YYYY-MM-DD)
### ✅ 已完成（列出完成的所有工作）
### 🟡 进行中（您现在正在处理的工作）
### ⚠️ 阻碍（阻止进度的工作）
使任务可执行
不好： "修复认证" 好： "在 AuthMiddleware.ts 中实施 JWT 令牌验证（验收：令牌验证，错误发送到 Sentry）"
包括：
- 特定文件名
- 清晰的验收标准
- 对其他任务的依赖
保持计划最新
如果范围变更：
- 更新计划
- 添加新阶段
- 调整时间线估算
- 记录范围变更原因
对于 Claude Code
当用户要求创建开发文档时：
-
如果可用，使用 /dev-docs 斜杠命令
-
或手动创建：
- 询问任务范围
- 分析相关代码库文件
- 创建综合计划
- 生成上下文和任务
-
使用以下结构化计划：
- 清晰的阶段
- 可执行的任务
- 验收标准
- 风险评估
-
使上下文文件可恢复：
- 顶部的 SESSION PROGRESS
- 快速恢复说明
- 带说明的关键文件列表
从开发文档恢复时：
- 阅读所有三个文件（计划、上下文、任务）
- 从 context.md 开始 - 有当前状态
- 检查 tasks.md - 了解已完成和待处理
- 参考 plan.md - 了解整体策略
频繁更新：
- 完成任务后立即标记
- 重要工作后更新 SESSION PROGRESS
- 发现新任务时添加
手动创建开发文档
如果您没有 /dev-docs 命令：
1. 创建目录：
mkdir -p dev/active/your-task-name
2. 创建 plan.md：
- 执行摘要
- 实施阶段
- 详细任务
- 时间线估算
3. 创建 context.md：
- SESSION PROGRESS 部分
- 关键文件
- 重要决策
- 快速恢复说明
4. 创建 tasks.md：
- 带复选框的阶段
- 任务格式
- 验收标准
好处
使用开发文档前
- 上下文重置 = 重新开始
- 忘记决策原因
- 失去进度跟踪
- 重复工作
使用开发文档后
- 上下文重置 = 读取 3 个文件，立即恢复
- 决策已记录
- 进度已跟踪
- 无重复工作
节省的时间： 每次上下文重置数小时
下一步
- 在下一次复杂任务中尝试此模式
- 使用 /dev-docs 斜杠命令（如果可用）
- 频繁更新 - 特别是 context.md
- 查看实际操作 - 浏览 dev/active/public-infrastructure-repo/
有疑问？ 查看 CLAUDE_INTEGRATION_GUIDE.md