# 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

**用途：** 实施战略计划

**包含：**
- 执行摘要
- 当前状态分析
- 提议的未来状态
- 实施阶段
- 带有验收标准的详细任务
- 风险评估
- 成功指标
- 时间线估算

**何时创建：** 复杂任务开始时

**何时更新：** 范围变更或发现新阶段时

**示例：**
```markdown
# 功能名称 - 实施计划

## 执行摘要
我们正在构建什么以及为什么

## 当前状态
我们现在在哪里

## 实施阶段

### 阶段 1：基础设施（2 小时）
- 任务 1.1：设置数据库模式
  - 验收：模式编译，关系正确
- 任务 1.2：创建服务结构
  - 验收：所有目录已创建

### 阶段 2：核心功能（3 小时）
...
```

---

### 2. [task-name]-context.md

**用途：** 继续工作的关键信息

**包含：**
- SESSION PROGRESS 部分（经常更新！）
- 已完成与进行中的内容
- 关键文件及其用途
- 做出的重要决策
- 发现的技术约束
- 相关文件的链接
- 快速恢复说明

**何时创建：** 任务开始时

**何时更新：** **经常** - 在重大决策、完成或发现之后

**示例：**
```markdown
# 功能名称 - 上下文

## 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

**用途：** 跟踪进度的清单

**包含：**
- 按逻辑部分分解的阶段
- 复选框格式的任务
- 状态指示符（✅/🟡/⏳）
- 验收标准
- 快速恢复部分

**何时创建：** 任务开始时

**何时更新：** 完成每个任务或发现新任务后

**示例：**
```markdown
# 功能名称 - 任务清单

## 阶段 1：设置 ✅ 完成
- [x] 创建数据库模式
- [x] 设置控制器
- [x] 配置 Sentry

## 阶段 2：实施 🟡 进行中
- [x] 创建 PostController
- [ ] 创建 PostService（进行中）
- [ ] 创建 PostRepository
- [ ] 使用 Zod 添加验证

## 阶段 3：测试 ⏳ 未开始
- [ ] 服务的单元测试
- [ ] 集成测试
- [ ] 手动 API 测试
```

---

## 何时使用开发文档

**用于：**
- ✅ 复杂的多日任务
- ✅ 有很多移动部分的功能
- ✅ 可能跨越多个会话的任务
- ✅ 需要仔细规划的工作
- ✅ 重构大型系统

**跳过：**
- ❌ 简单错误修复
- ❌ 单文件更改
- ❌ 快速更新
- ❌ 琐碎修改

**经验法则：** 如果需要超过 2 小时或跨越多个会话，使用开发文档。

---

## 开发文档工作流程

### 开始新任务

1. **使用 /dev-docs 斜杠命令：**
   ```
   /dev-docs 重构认证系统
   ```

2. **Claude 创建三个文件：**
   - 分析需求
   - 检查代码库
   - 创建综合计划
   - 生成上下文和任务文件

3. **审查和调整：**
   - 检查计划是否合理
   - 添加任何缺失的考虑
   - 调整时间线估算

### 实施期间

1. **参考计划** 了解整体策略
2. **频繁更新 context.md：**
   - 标记已完成的工作
   - 记录做出的决策
   - 添加阻碍
3. **在 tasks.md 中勾选任务** 完成时

### 上下文重置后

1. **Claude 读取所有三个文件**
2. **在几秒内理解完整状态**
3. **从上次离开的确切位置继续**

无需解释您在做什么 - 一切都已记录！

---

## 与斜杠命令集成

### /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 部分应始终反映现实：**
```markdown
## SESSION PROGRESS (YYYY-MM-DD)

### ✅ 已完成（列出完成的所有工作）
### 🟡 进行中（您现在正在处理的工作）
### ⚠️ 阻碍（阻止进度的工作）
```

### 使任务可执行

**不好：** "修复认证"
**好：** "在 AuthMiddleware.ts 中实施 JWT 令牌验证（验收：令牌验证，错误发送到 Sentry）"

**包括：**
- 特定文件名
- 清晰的验收标准
- 对其他任务的依赖

### 保持计划最新

如果范围变更：
- 更新计划
- 添加新阶段
- 调整时间线估算
- 记录范围变更原因

---

## 对于 Claude Code

**当用户要求创建开发文档时：**

1. **如果可用，使用 /dev-docs 斜杠命令**
2. **或手动创建：**
   - 询问任务范围
   - 分析相关代码库文件
   - 创建综合计划
   - 生成上下文和任务

3. **使用以下结构化计划：**
   - 清晰的阶段
   - 可执行的任务
   - 验收标准
   - 风险评估

4. **使上下文文件可恢复：**
   - 顶部的 SESSION PROGRESS
   - 快速恢复说明
   - 带说明的关键文件列表

**从开发文档恢复时：**

1. **阅读所有三个文件**（计划、上下文、任务）
2. **从 context.md 开始** - 有当前状态
3. **检查 tasks.md** - 了解已完成和待处理
4. **参考 plan.md** - 了解整体策略

**频繁更新：**
- 完成任务后立即标记
- 重要工作后更新 SESSION PROGRESS
- 发现新任务时添加

---

## 手动创建开发文档

如果您没有 /dev-docs 命令：

**1. 创建目录：**
```bash
mkdir -p dev/active/your-task-name
```

**2. 创建 plan.md：**
- 执行摘要
- 实施阶段
- 详细任务
- 时间线估算

**3. 创建 context.md：**
- SESSION PROGRESS 部分
- 关键文件
- 重要决策
- 快速恢复说明

**4. 创建 tasks.md：**
- 带复选框的阶段
- [ ] 任务格式
- 验收标准

---

## 好处

### 使用开发文档前
- 上下文重置 = 重新开始
- 忘记决策原因
- 失去进度跟踪
- 重复工作

### 使用开发文档后
- 上下文重置 = 读取 3 个文件，立即恢复
- 决策已记录
- 进度已跟踪
- 无重复工作

**节省的时间：** 每次上下文重置数小时

---

## 下一步

1. **在下一次复杂任务中尝试此模式**
2. **使用 /dev-docs** 斜杠命令（如果可用）
3. **频繁更新** - 特别是 context.md
4. **查看实际操作** - 浏览 dev/active/public-infrastructure-repo/

**有疑问？** 查看 [CLAUDE_INTEGRATION_GUIDE.md](../CLAUDE_INTEGRATION_GUIDE.md)