# Ddev Exec

> 在当前会话里按已写好的实现计划顺序执行任务时使用

- Skill: `docevilock/ddev-exec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add docevilock/ddev-exec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/docevilock/ddev-exec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: docevilock (https://skillmd.com/u/docevilock)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/docevilock/ddev-exec

---


# 执行计划

读取计划，先做批判性检查，再按顺序执行所有任务，并在完成后进入默认收尾。执行时不只看计划本身，还要把计划引用的 architecture / detail / flow / dataflow 文档一并作为实现依据。

**开始时声明：** “我正在使用 ddev-exec skill 来执行这个计划。”

## 何时使用

- 已经有明确的实现计划文档
- 现在要按计划直接落地，而不是继续做规划
- 任务之间有顺序依赖，适合同一会话连续推进
- 不需要为每个任务单独派发新的实现子代理

## 流程

### 第一步：读取并审查计划

1. 读取计划文件
2. 读取计划里引用的 architecture / detail / flow / dataflow 文档
3. 先批判性审查一遍，找出缺口、歧义、风险和无法执行的地方
4. 如果计划存在关键问题，先向用户指出，再继续
5. 如果计划可执行，就创建 TodoWrite / `update_plan` 跟踪并开始

### 计划审查重点

- 每个任务是否都明确引用了上游设计文档，而不是只给抽象目标
- 计划里的任务边界、文件范围和验证动作，是否都能追溯到已确认设计
- 计划是否偷偷引入了文档里没有的新设计、新接口或新流程分支
- 如果计划与引用文档冲突，是否已经回退到上游澄清，而不是强行执行

### 第二步：按顺序串行执行

所有任务在主会话中逐个串行执行，不派发子代理：

1. 标记任务为 `in_progress`
2. 先阅读该任务引用的文档和图，确认输入、输出、状态、接口与流程约束
3. **读取目标文件当前内容（强制）**：对于本任务要修改的每个文件，先用 Read 读取其当前完整内容。确认：
   - 文件当前结构与计划中的预期一致
   - 计划要修改的行号/区域与文件实际内容匹配
   - 不存在未在计划中声明的并发修改或结构变化
   - 如果文件现状与计划预期不符，先停下来评估是否需要更新计划，不得盲目覆盖
4. 严格按计划步骤执行，不要擅自跳步，也不要脱离引用文档补设计
5. 运行该任务要求的验证
6. 做任务内一致性核对，确认实现结果与引用文档一致
7. 记录结果与未覆盖风险
8. 任务完成后再标记为 `completed`，然后进入下一个任务

如果计划里要求提交或补文档，就照计划执行，不要省略。如果计划里出现独立审查阶段、审查任务或派发审查 subagent 的安排，视为计划缺陷：停下来回退到 `ddev-plan` 修正，不在执行阶段自行加审查。

如果计划步骤与引用文档冲突，以已确认的 architecture / detail / flow / dataflow 文档为准，并立即回到计划审查，必要时先修计划再继续执行。

不要在任务刚做完时就提前宣称”计划完成”；默认要把最终完成结论留给收尾门禁。

### 第三步：默认收尾

当所有任务完成并通过计划要求的验证后，**自动进入默认收尾流程**。

**⚠️ HARD GATE — 执行完成后必须直接进入 ddev-gate**

所有 Task 执行完毕后，**禁止 agent 自行宣告"完成"或停留在代码已写的状态**。必须无条件、不可跳过地按照下方"默认收尾顺序"逐项推进，直至 `ddev-gate` 在同一份最终代码上给出双审查 `pass`。

- 不得以"代码简单""只改了几行""肉眼看过"为由跳过 ddev-gate
- 不得在 ddev-gate 双审查 pass 之前宣称完成
- 不得以"用户没要求"为由省略验收——ddev-gate 是本流程的强制终结点，不是可选项

**默认收尾顺序：**

1. 用 `verification-before-completion` 补齐最终结论所需的验证证据
2. 进入 `ddev-gate`。gate 会**同时派发两个独立 subagent**：
   - 一致性审查：只核对代码与 spec/detail/architecture 文档规划的架构是否一致（模块边界、接口、依赖方向、状态归属、数据流/流程骨架）
   - 代码评审：合并编码规范、代码质量、注释完整性、清理项识别（原 `ddev-clean` 职责）四个维度
3. 一致性审查报出的架构偏离：能修正的修正到一致；无法修正或决定不修正的，写入 `implementation-notes.md` 的 Deviations（偏离点、理由、影响范围），由审查确认已记录
4. 代码评审报出的阻塞项（CRITICAL/HIGH）和缺失注释：按其清单修复补齐；可清理项按 `ddev-clean` 的 regression-tests-first、最小 diff、最小作用域规则处理
5. 只要本轮发生过任何代码修改（清理或修复），必须让 gate 基于最终代码重新并行派发两个审查做只读复审
6. 如果 `ddev-gate` 返回 `blocked`，主 agent 必须先修改，再重新进入 `ddev-gate`
7. 如果 `ddev-gate` 返回 `need-info`，主 agent 必须先补齐缺失输入、范围或验证证据，再重新进入 `ddev-gate`
8. 只有当最后一轮中两个审查在同一份最终代码上都 `pass`、且该轮没有任何代码修改时，才能宣称"计划已经完成"

### ⚠️ 收尾阶段交接硬门禁

**ddev-gate 内部的「并行审查 → 修复/清理 → 只读复审」循环为自动化流程，不受此限制。** gate 通过后的后续动作（如 archive / commit / 发布），**必须等待用户明确确认**，禁止 agent 自动推进。

- gate 双审查 `pass` 后，向用户报告验收结论，询问是否继续后续操作。
- 用户未明确说”提交””归档””发布”等指令前，停留在 gate 结论输出阶段。

## 什么时候必须停下来

遇到下面情况要立刻停，先澄清再继续：

- 缺少依赖，导致关键步骤无法执行
- 计划中的步骤与代码现状明显不符
- 计划中的步骤与引用文档明显冲突
- 某一步说明不清，无法安全落地
- 计划要求的验证连续失败
- 发现计划本身需要改方向

不要硬猜，也不要在关键歧义下继续往前推。

## 重新回到计划审查的触发条件

以下情况要回到“读取并审查计划”这一步重新判断：

- 用户更新了计划
- 用户更新了 architecture / detail / flow / dataflow 文档
- 你发现计划中的关键假设已经失效
- 实现中暴露出上游设计缺口

## 红旗信号

**永远不要：**

- 不看计划就直接开写
- 不看任务引用的上游文档就直接开写
- **不看目标文件当前内容就直接开写**
- 计划有明显缺口还硬执行
- 跳过验证
- 把”代码写了”当成”任务完成”
- 计划和上游文档冲突时，私自选择其中一个继续写
- 没经过默认收尾就宣称整体完成
- 在 `ddev-gate` 双审查 `pass` 之前宣称完成
- 清理或修复改了代码，却不重新跑 `ddev-gate` 的并行复审
- 未经用户明确同意就在 `main` / `master` 上开始实现
- 把 `task_plan.md` / `progress.md` / `implementation-notes.md` 写到计划目录之外的仓库根目录或其他位置（见「执行文档存放位置」硬性规范）

## planning-with-files 状态追踪

执行过程中必须维护三份持久化文件，确保上下文穿越和断点恢复。

### ⚠️ 执行文档存放位置（硬性规范）

**`task_plan.md` / `progress.md` / `implementation-notes.md` / `findings/` 必须写在对应计划目录下**（`docs/plans/YY-MM-DD_<topic>/`，与 spec、exec_plans 同级），**禁止写仓库根目录、`docs/` 或其他与计划无关的位置**。

- 计划目录不存在时，先 `mkdir -p docs/plans/YY-MM-DD_<topic>/` 再创建文件。
- 若误写到仓库根目录或其他位置，立即 `git mv` 纠正到对应计划目录，不得保留孤儿执行文档。
- 与下游 `ddev-archive` 约定一致：归档时这些执行文档随计划目录一并删除，不迁移进 `archive/`（见 ddev-archive「执行文档存放位置」规范）。

### 文件职责

| 文件 | 位置（均在对应计划目录 `docs/plans/YY-MM-DD_<topic>/` 下） | 用途 | 何时创建 |
|------|------|------|---------|
| `task_plan.md` | 计划目录根 | 任务追踪：从 exec plan 提取 Task N 生成 checkbox 列表 + Errors 表 | 第一步完成后自动创建 |
| `progress.md` | 计划目录根 | 执行日志：每任务完成后记录产出和验证结果 | 首次写入时创建 |
| `implementation-notes.md` | 计划目录根 | 实现笔记：每任务完成后按 4 维度记录 AI 推理过程 | 首次任务完成后自动创建 |
| `findings/` | 计划目录下 `findings/` | 上游设计决策（由 ddev-spec/detail/doc-review 写入，本阶段只读） | 已存在 |

### 第一步后：创建 task_plan.md

审查计划通过后，从 exec plan 文档中提取所有 Task N，生成 `task_plan.md`（写到对应计划目录 `docs/plans/YY-MM-DD_<topic>/task_plan.md`）。格式：

```markdown
# 任务执行追踪

> 来源计划：docs/plans/26-06-20_xxx/exec_plans/feature-name.md
> 创建时间：2026-06-20
> 目标：<一句话目标>

## Current Task
- **Task**: Task 1 — 错误码枚举定义
- **Status**: in_progress

## Tasks

- [ ] Task 1 — 错误码枚举定义
- [ ] Task 2 — 上下文结构体
- [ ] Task 3 — 状态机实现
- [ ] Task 4 — API 接口暴露
- [ ] Task 5 — 单元测试

## Errors Encountered
| Error | Attempt | Task | Resolution |
|-------|---------|------|------------|
```

### 第二步中：每任务读写规则

**每个任务开始时**：
1. 读取 `task_plan.md` 确认目标和当前任务

**每个任务完成后**：
1. 标记 `task_plan.md` 中该任务的 checkbox 为 `[x]`
2. 更新 `Current Task` 为下一个任务
3. 追加 `implementation-notes.md`，按 4 维度记录本任务的推理过程
4. 写入 `progress.md`，格式：

```markdown
### Task N — <任务名> ✅
- 新建/修改的文件列表
- 验证命令和结果
- 如有错误，简要说明
```

**错误发生时**：
- 写入 `task_plan.md` 的 Errors Encountered 表
- 遇到无法自行修复的错误，停止并上报用户

### implementation-notes.md 写入规则

每个任务完成后，必须在 `implementation-notes.md` 中追加本轮实现过程中出现的推理记录。格式：

```markdown
# Implementation Notes

> 来源计划：docs/plans/YY-MM-DD_xxx/exec_plans/feature-name.md
> 创建时间：2026-07-08

## Design Decisions
> spec/detail 文档未覆盖、AI 在实现过程中自行做出的设计选择

### Task N — <任务名>
- **决策**：<做了什么选择>
- **触发原因**：<spec 中哪个点没说清楚，导致必须自己做判断>
- **影响范围**：<哪些文件/接口受此决策影响>

## Deviations
> 故意偏离 spec/detail/plan 的实现，及偏离理由

### Task N — <任务名>
- **偏离点**：<文档要求 A，实际实现为 B>
- **理由**：<为什么偏离>
- **影响范围**：<哪些文件/接口受影响>

## Tradeoffs
> 考虑过但最终放弃的替代方案，及放弃原因

### Task N — <任务名>
- **替代方案**：<描述考虑过的方案>
- **放弃原因**：<为什么不选>
- **当前方案**：<实际采用的方案简述>

## Open Questions
> 拿不准、需要用户集中定夺的问题（攒着，不零散打断）

### Task N — <任务名>
- **问题**：<描述不确定点>
- **当前处理**：<临时用了什么方式>
- **建议**：<你认为应该怎么处理>
```

四个维度中，Design Decisions 和 Deviations 为**强制维度**——每个任务完成后必须至少检查这两类。Tradeoffs 和 Open Questions 为**按需维度**——有则必写，无则标注"无"。不得跳过整个文件。

Open Questions 中的问题在 ddev-gate 验收阶段会作为未决项被检查，因此在进入默认收尾前必须全部回答完毕。

### 第三步前：Stop Gate 前置检查

进入默认收尾前，验证 `task_plan.md` 中所有 Tasks 均已 `[x]`，且 `implementation-notes.md` 中 Open Questions 已全部回答完毕。未全部完成的不进入第三步。

### 断点恢复

会话中断后重新开始时：

0. 运行 `python scripts/session-catchup.py` 获取 5-Question Reboot Test 摘要
1. 读取对应计划目录下的 `task_plan.md`（`docs/plans/YY-MM-DD_<topic>/task_plan.md`）定位当前任务和未完成的任务
2. 读取 `progress.md` 了解已完成任务的产出和验证结果
3. 读取 `implementation-notes.md` 了解已完成任务中的设计决策、偏离和未决问题
4. 从第一个未完成任务继续——已完成的任务不重复执行

## 集成

**状态追踪文件：**
- 读取 `task_plan.md` — 每任务开始前确认目标，每任务完成后更新 checkbox
- 写入 `progress.md` — 每任务完成后记录产出和验证结果
- 写入 `implementation-notes.md` — 每任务完成后按 4 维度记录推理过程

**Required workflow skills:**
- **ddev-plan** - 产出本 skill 要执行的计划
- **verification-before-completion** - 对最终结论补齐验证证据
- **ddev-gate** - 默认最终验收（同时派发一致性审查 + 代码评审两个独立 subagent）
- **ddev-code-review** - 独立触发的代码质量审查；gate 内的质量审查已并入代码评审 subagent
- **ddev-clean** - 独立的受限 cleanup / deslop；gate 内的清理项识别已并入代码评审，执行由主 agent 按需调用