# 需求: 长文档编辑策略

## §1 背景与目标

**来源痛点**: `docs/进化/进化-写文档不要卡住.md` 记录了一个真实 case：用户要求 AI 将 33 个补充问题融合到 ~1500 行的 writeup 文档中，AI 连续 9 轮说要写但一个字都没写出来。

**根因**: AI 试图用一次 Write 调用生成整个 1500+ 行文档，超出单次生成能力导致超时/静默失败。现有进化 agent prompt 中规则 1.5（实施粒度控制）只覆盖代码实施场景，没有覆盖长文档编辑场景。

**预期收益**:
- 消除"说要写但不写"的空转轮次（case 中浪费了 9 轮）
- 分段编辑提升质量（每次聚焦一个小节）

## §2 技术方案

### 改动文件

| 文件 | 改动类型 | 说明 |
|------|---------|------|
| `.opencode/agents/security-analysis-evolve.md` | 修改 | 新增规则 7 + 异常处理条目 |

### 规则 7 设计

在"强制规则"节中，紧跟规则 6 之后，新增规则 7: 长文档编辑策略。

核心内容:
1. **分段编辑原则**: 修改超过 300 行的文档时，必须拆分为多次 Edit 调用，每次只改一个小节
2. **禁止全量重写**: 禁止用 Write 工具整体重写超过 300 行的已有文档，必须用 Edit 工具局部修改
3. **执行策略**: 先列出要改的小节清单 → 逐个 Edit → 每次确认成功后再改下一个
4. **优先使用 Edit**: 即使新增内容，也优先用 Edit 在合适位置插入，而非 Write 全量替换

### 异常处理条目设计

在"异常处理"表中新增一行:
| 文档编辑连续 2 次未产出内容 | 暂停，列出待编辑小节清单，改用分段 Edit 策略 |

## §3 实现规范

### 改动范围表

| 项目 | 内容 |
|------|------|
| 改动文件数 | 1 |
| 新增代码 | ~30 行（规则 7）+ 1 行（异常处理表） |
| 修改代码 | 0 行 |
| 删除代码 | 0 行 |
| 编码规则 | Markdown 格式，与现有规则风格一致 |

### §3.1 实施步骤拆分

```
步骤 1. 新增规则 7: 长文档编辑策略
  - 文件: .opencode/agents/security-analysis-evolve.md
  - 预估行数: ~30 行
  - 验证点: 
    1. Read 确认规则 7 在规则 6 之后、Phase 输出模板之前
    2. 确认内容包含: 分段编辑原则、禁止全量重写、执行策略、优先使用 Edit
  - 依赖: 无

步骤 2. 新增异常处理条目
  - 文件: .opencode/agents/security-analysis-evolve.md
  - 预估行数: 1 行
  - 验证点: 
    1. Read 确认新条目在异常处理表中，格式与其他条目一致
  - 依赖: 无
```

## §4 验收标准

### 功能验收
- [x] 规则 7 包含分段编辑原则（拆分为多次 Edit）
- [x] 规则 7 包含禁止全量重写（禁止 Write 超过 100 行的已有文档）
- [x] 规则 7 包含执行策略（先列清单再逐个编辑）
- [x] 规则 7 包含优先使用 Edit 的指引
- [x] 异常处理表包含"文档编辑连续未产出"条目

### 回归验收
- [x] 现有规则 1-6 未被修改
- [x] Phase 流程图未被修改
- [x] 四维度量、反模式、高风险改动等节未被修改
- [x] 文档整体结构完整

### 架构验收
- [x] 新增内容位于正确位置（规则 7 在规则 6 之后）
- [x] 新增内容与现有规则风格一致
- [x] 展开后行数 < 450 行

## §5 与现有需求文档的关系

独立需求，不依赖其他需求文档。
