面向“传统程序员”的端到端 10x Vibe Coding 指南(大型需求) - 从面向业务开发转向面向“Agent 员工”开发

本篇目标：解释实现大型需求自动化开发、验证的方法，展示效果，形成可复用（易复用）的方法论。

本篇由 AI 协助完成，10x “开发”文档

0 术语

术语	含义
CC	Claude Code，Anthropic 的 AI 编程助手
SDD	Spec-Driven Development，规格驱动开发
Spec	规格文档——SDD 各阶段的核心产出物
Context	输入给模型的上下文信息（含系统提示、对话历史、文件内容等）
Session	一次完整的人-模型交互会话
Fresh Session	全新的、无历史累积的干净会话
Subagent	主 Agent 派生的子 Agent，在独立 Session 中执行特定任务
MCP	Model Context Protocol，模型上下文协议（外部工具集成标准）
Skill	可复用的 Agent 行为模板（prompt + 约束 + 工具配置）
Plan Spec	任务计划文档，含原子任务列表及执行所需的 Context
Design Spec	系统设计文档，含架构、接口定义、数据模型

1 定义"长任务 Vibe"

先明确概念——长任务 vibe 和传统逐任务交互有什么本质区别。

graph LR
    subgraph "传统模式"
        A1[人工写系分] --> A2[人工拆任务]
        A2 --> A3[逐个手动给 AI]
        A3 --> A4[人工验证]
        A4 --> A3
    end

    subgraph "Long-task Vibe"
        B1["AI 生成 Design"] --> B2["AI 拆分 Tasks"]
        B2 --> B3["自动逐任务执行（Fresh Context）"]
        B3 --> B4[自动验证]
        B4 --> B3
    end

核心差异：人从"每一步的执行者"变成"流程的监督者"和"Context 决策者"。

传统模式下，人需要在每个任务上花费大量时间进行上下文切换、手动喊给 AI、再检查输出。Long-task vibe 模式下，人只在关键节点进行审核——需求是否对齐、设计是否合理、任务拆分是否完备——执行工作交由 Agent 在隔离的 Fresh Session 中自动完成。

要保证长任务的稳定性，关键在于两点：原子任务拆分的质量和任务 Context 隔离执行的能力。

2 模型决定下限和上限

模型能力决定了天花板和地板，但在这个范围内你实际落在哪里，取决于 context 质量。

差模型的信息密度低，且由于 context window 的强限制，其大量的无效输出会很快污染 context，导致输出质量逐渐降低。可以用一个二维坐标来理解不同模型的表现差异：

X 轴：Token 消耗量——完成同样任务，模型需要消耗多少 token（包括输入和输出）
Y 轴：智能程度——模型理解意图、做出正确决策的能力（体现为代码正确率、架构合理性、边界处理等）

理想模型位于左上角（低消耗、高质量）。闭源前沿模型（如 Claude Sonne/Gemini）倾向于更精简的输出，在相同 context 预算下能保持更高的信息密度；而部分开源或较弱的模型则倾向于生成大量解释性文字，快速消耗 context window。

Takeaways:

模型的"废话"会污染 context，压缩有效信息密度
不同模型输出的精简程度不一，闭源模型通常更简洁
重点：选对模型是前提，但不是全部——能管好 context 才是胜负手

3 SDD 开发与长任务

3.1 SDD 与传统需求的开发流程

根据 Wikipedia 的定义:

Spec-driven development (SDD) is a software engineering methodology where a formal, machine-readable specification serves as the authoritative source of truth and the primary artifact from which implementation, testing, and documentation are derived

规格驱动开发（SDD）是一种软件工程方法论，以一份正式的、机器可读的规格说明作为唯一权威的事实来源，实现、测试和文档均从该规格派生而来。

从定义中可以看出，Spec 是整个需求开发的中心。但在实践中，SDD 更关键的是一套伴随软件开发各个阶段的方法论——它规定了每个阶段应产出什么样的 Spec 文档，以及这些文档如何驱动下一阶段的自动化执行。

要理解它的价值，先看传统开发流程中 SDD 可以介入的环节：

graph TB
    A[需求评审] --> B[系统设计/系分]
    B --> C[技术方案评审]
    C --> D[任务拆分/排期]
    D --> E[编码开发]
    E --> F[自测/单元测试]
    F --> G[Code Review]
    G -->|打回| E
    G -->|通过| H[联调/集成测试]
    H --> I[QA 测试]
    I -->|Bug| E
    I -->|通过| J[发布上线]
    J --> K[线上验证/监控]

    subgraph SDD 可介入的环节
        B
        D
        E
        F
    end

需求评审：产品/业务方与研发对齐需求范围
系统设计/系分：人工编写系分文档（SDD 可辅助生成）
技术方案评审：架构师/TL Review 设计合理性
任务拆分/排期：手动拆分子任务并估时（SDD 可自动拆分）
编码开发：逐任务手写代码（SDD 可由 Agent 执行）
自测/单元测试：开发者手动验证
Code Review → 联调 → QA → 发布：传统人工驱动链路

传统流程的核心瓶颈在于：每个环节都高度依赖人的执行参与。SDD 的目标不是消除人，而是将人的角色从"执行者"提升为"决策者和审核者"。引入 SDD 后，流程变为：

3.1.1 SDD 增强后的开发流程

graph TB
    A[需求评审] --> B[PRD 文档化]
    B --> C["Agent 生成系分（Design Spec）"]
    C --> D[人工审核/交叉验证]
    D --> E["Agent 生成任务计划（Plan Spec）"]
    E --> F[人工审核任务拆分]
    F --> G["Agent 逐任务执行（隔离 Context）"]
    G --> H["Agent 生成 E2E 测试"]
    H --> I[自动执行测试]
    I -->|失败| G
    I -->|通过| J[人工 Code Review]
    J -->|打回| G
    J -->|通过| K[发布上线]

    subgraph 人工决策点
        A
        D
        F
        J
    end

    subgraph Agent 自动执行
        C
        E
        G
        H
        I
    end

对比两张图可以看到关键转变：人工执行的环节变成了人工审核的环节。Agent 承担了系分编写、任务拆分、编码和测试生成的执行工作；人则聚焦在需求评审、设计审核、任务审核和最终的 Code Review——这些是真正需要专业判断的节点。

3.2 SDD 弥补模型 Context 长度限制

要理解 SDD 为何能支撑长任务，需要先理解它解决的核心问题：模型的 Context 限制。

Transformer 的注意力机制天生存在限制。模型推理所需的资源随 Context 窗口增长而急剧增加，因此所有模型的 Context 窗口都有一个硬性天花板。更关键的是，即使在窗口之内，注意力机制也无法保证信息的均匀有效——研究表明，处于 Context 中间位置的信息尤其容易被"遗忘"（Lost in the Middle 现象）。

大多数开发实践中，为了规避这一缺陷，通常由开发者手动拆分较小的任务后交由模型执行。但这又回到了"人是每一步的执行者"的老路。SDD 用一种不同的方式解决了这个问题：

graph LR
    subgraph "传统交互：单 Session 累积"
        T1[Task 1] --> T2[Task 2]
        T2 --> T3[Task 3]
        T3 --> T4["Task N..."]
        T4 --> X["Context 膨胀 → 质量下降"]
    end

    subgraph "SDD：Spec 驱动 + Session 隔离"
        SPEC["Spec 文档（持久化）"] --> S1["Fresh Session → Task 1"]
        SPEC --> S2["Fresh Session → Task 2"]
        SPEC --> S3["Fresh Session → Task 3"]
        SPEC --> S4["Fresh Session → Task N"]
    end

在传统交互模式中，所有任务在同一个 Session 内顺序执行。前序任务的输出（包括大量无关的中间过程）不断累积，挤占后续任务的有效信息空间，导致越往后执行质量越差。

SDD 模式的关键突破在于：将 Spec 文档作为跨 Session 的持久化 Context。每个任务在独立的 Fresh Session 中执行，只加载当前任务所需的 Spec 片段，从而保证每个任务都拥有高质量、高密度的 Context 输入。这也是 SDD 工具箱（特别是集成了 Subagent 机制的实现）能支撑连续数小时长任务执行的根本原因。

3.3 SDD 核心机制：Spec 流水线

SDD 的运作依赖一条文档驱动的流水线。每个阶段产出的 Spec 文档，既是该阶段的交付物，也是下一阶段的输入 Context：

graph TB
    PRD["PRD（需求规格）"] -->|输入| DESIGN["Design Spec（系分文档）"]
    DESIGN -->|输入| PLAN["Plan Spec（任务计划）"]
    PLAN -->|拆分为原子任务| EXEC["Execution（逐任务执行）"]
    PLAN -->|输入| TEST["Test Spec（测试用例）"]

    PRD -.->|"人工编写 / 导入"| PRD
    DESIGN -.->|"Agent 生成 + 人工审核"| DESIGN
    PLAN -.->|"Agent 生成 + 人工审核"| PLAN
    EXEC -.->|"Agent 自动执行（Fresh Session）"| EXEC
    TEST -.->|"Agent 生成 + 自动执行"| TEST

    subgraph "文档 = 持久化 Context"
        PRD
        DESIGN
        PLAN
        TEST
    end

    EXEC --> VERIFY{验证通过?}
    VERIFY -->|是| DONE[完成]
    VERIFY -->|否| EXEC

这条流水线的设计遵循三个核心原则：

阶段隔离，文档传递：每个阶段结束后，产出的文档进入只读模式。下游阶段仅通过读取文档获取上下文，而非依赖同一个 Session 的记忆。这确保了信息传递的确定性——不会因为 Context 衰减而丢失关键信息。
原子任务，独立执行：Plan Spec 将大型需求拆分为若干原子任务，每个任务包含独立执行所需的全部上下文信息（涉及的文件路径、接口定义、依赖关系）。Agent 在 Fresh Session 中逐个执行，互不干扰。
Spec 作为外部记忆：模型的 Context Window 是易失的，但文件系统上的 Spec 文档是持久的。SDD 本质上是用文档系统弥补模型的记忆缺陷——将"需要记住的一切"外化为 Spec，让每个 Session 按需加载，而非依赖模型在长对话中"记住"。

3.4 Context 设置基本原则

Context 的质量直接决定 Agent 的输出质量。以下是经过实践验证的关键原则：

最重要的原则：始终关注当前 Context 会话占用情况

不要吝惜新建 session。把每个 session 当作一个独立的 Agent 员工——每个 Agent 只负责完成一个 Skill（一项明确的任务）。session 越长，context 越脏，模型的有效智能越低。当你感觉 Agent 开始“发瘴”的时候，正确的做法不是反复纠正，而是开一个新 session、给它干净的 context、让它重新出发。

Role 设定

为 Agent 设定明确的角色（如"后端架构师"、"QA 专家"）会显著影响其行为模式。例如，设定为 QA 角色的 Agent 会专注于发现问题而非擅自修复。Role 影响三个维度：instruction following 的严格程度、输出的语气风格、以及面对歧义时的决策倾向。

工具加载策略

工具不是越多越好——加载过多工具反而降低模型执行质量，因为每个工具的 schema 都会占用 context 空间。推荐策略：

MCP、Skills 按需加载到当前 session，一个 session 专注一个 skill
复杂任务用 specialized sub-agents 拆分执行，每个 subagent 只加载所需工具
优先使用本地信息通道（文件读取、grep 搜索），避免低效的远程调用

Workspace 范围

项目的 workspace 要包含全部相关子项目（如本项目同时包含管理态、运行态、接入层），避免 AI 缺少上下文做出错误假设。缺失的依赖信息是 Agent 产生幻觉的常见原因。

Subagent 的 Context 代价

Subagent 会扩展 context（其输出需要回传给主 agent），注意对上下文长度的影响。如果 subagent 输出过长，考虑让其只返回摘要或关键结果。

当前痛点

定义自己的 Agent（可复用 context、prompt）是提效的关键
Qoder 等非 CC 工具有时不严格遵循 SOP，需要在 prompt 中更强调约束

3.5 AGENTS.md

AGENTS.md 是项目根目录下的配置文件，Agent 在启动 session 时会自动读取。它的作用相当于给 Agent 一份"入职须知"：

编码规范：命名约定、代码风格、注释语言
项目架构：模块划分、分层结构、核心依赖关系
内部依赖：私有包的引用方式、版本约束
禁止操作：如本项目中规定 "Don't perform any git operations"
常见陷阱：项目特有的注意事项（如特殊的序列化方式、字段命名例外）

AGENTS.md 应保持精简——它会占用每个 session 的 context 空间。只放全局性的、每次都需要的信息；阶段性的信息放在对应的 Spec 文档中。

3.6 项目开发流程

完成 Context 环境设置后，进入 SDD 的核心开发循环。整个流程由四个阶段组成，严格顺序执行：

graph LR
    PRD["00-PRD"] --> DESIGN["01-Design"]
    DESIGN --> PLAN["02-Plan"]
    PLAN --> TESTS["03-Tests"]
    TESTS -.->|"发现设计缺陷"| DESIGN2["01-Design v2"]
    DESIGN2 --> PLAN2["02-Plan v2"]

每个阶段结束时，产出的文档进入只读模式——这是 SDD 的铁律。下游阶段只能读取上游文档，不能反向修改。如果在执行中发现设计缺陷，应回到对应阶段重新生成 Spec，而非在代码中打补丁。

3.7 基本项目结构

project-root/
├── AGENTS.md              # Agent 全局配置（自动加载）
├── 00-prd/                # 阶段 0：产品需求文档
│   └── feature-x-prd.md
├── 01-design/             # 阶段 1：系统设计文档
│   └── feature-x-design.md
├── 02-plan/               # 阶段 2：任务计划文档
│   └── feature-x-plan.md
├── 03-tests/              # 阶段 3：测试用例 + 可执行脚本
│   ├── feature-x-e2e.md
│   └── run-e2e.sh
└── src/                   # 实际代码目录

这套目录结构的设计意图是：让 Agent 通过文件路径约定自动定位 context。当 Agent 需要生成设计文档时，它知道去 00-prd/ 读取需求；当它需要执行任务时，它知道去 02-plan/ 读取任务列表。约定优于配置，减少每次手动指定路径的开销。

3.8 PRD

PRD 是整条 Spec 流水线的起点，其质量直接决定下游所有产出物的上限。

核心原则：本地化。云文档（语雀、Notion 等）性能较差，Agent 无法原生快速搜索（如使用 grep）。应将需求文档导出为 Markdown 存放在 00-prd/ 目录下，确保 Agent 可以直接读取和引用。

PRD 应包含以下关键信息：

功能范围：明确哪些功能在本次需求范围内，哪些不在
接口契约：涉及的 API 变更、新增字段、数据结构
业务规则：状态流转、权限控制、数据校验规则
非功能需求：性能要求、兼容性约束、灰度策略

PRD 不需要面面俱到，但需要覆盖 Agent 在后续阶段做决策时所需的全部业务信息——因为 Agent 无法像人一样"去问一下产品经理"。

3.9 Design

Design 阶段是 Agent 第一次介入的产出环节。给 Agent 输入 PRD，让它生成系统设计文档（Design Spec），存放在 01-design/。

生成策略：交叉验证

不要只用一个模型生成设计。推荐流程：

graph LR
    PRD[PRD 文档] --> A["模型 A 生成初稿"]
    A --> B["模型 B 审核（新 Session）"]
    B --> C[人工终审]
    C --> D[Design Spec 定稿]

交叉验证的价值在于：不同模型有不同的"盲区"。模型 A 可能遗漏边界条件，模型 B 可能发现接口命名不一致。多视角审查能显著提高设计质量。

Design Spec 应包含：

架构变更概览（新增/修改了哪些模块）
数据模型变更（新增字段、表结构）
接口定义（请求/响应结构、状态码）
关键逻辑流程（状态流转、级联操作）

3.10 Tasks

任务拆分是长任务 vibe 的核心环节——拆分质量直接决定 Agent 自动执行的成功率。

拆分原则

原子性：每个任务应可独立执行和验证，不依赖其他任务的运行时状态
自包含 Context：每个任务必须附带执行所需的全部上下文——涉及的文件路径、接口签名、依赖的数据结构、预期的行为变更。Agent 在 Fresh Session 中不会"记得"之前的任务
有序依赖：任务按依赖关系排序（如先建表、再写 DAO、再写 Service、最后写 Controller）
可验证：每个任务完成后应有明确的验证标准（编译通过、测试通过、特定输出等）

Plan Spec 的结构

推荐将 Plan 按 Chunk（功能块）组织，每个 Chunk 内包含若干有序 Task。每个 Task 需包含：

Task 标题：简述要做什么
Files：涉及的文件（新增或修改）
Context：执行所需的上下文引用（指向 Design Spec 的具体章节、现有代码的参考文件）
Steps：用 checkbox 列出具体步骤，便于跟踪进度

Task 的 Context 部分是关键——它就是 Agent 在 Fresh Session 中唯一的"记忆来源"。Context 写得越精确，Agent 执行的成功率越高。

3.11 E2E Tests

E2E 测试是 SDD 流水线的最后一道防线，用于验证从 Plan Spec 派生的代码变更是否符合预期行为。与传统手写测试不同，SDD 中的测试用例可由 Agent 从 Spec 文档自动派生（这是我设想的 E2E，还未标准化）——Spec 既定义了"要实现什么"，也定义了"如何验证"。

Backend

分两阶段——先生成测试用例文档，再转化为可执行脚本。

阶段一：生成测试用例（descriptive，不含可执行命令）

You are a **QA expert**. Given the implementation plans in `02-plan/`, generate a comprehensive E2E test case document and put it under `03-tests/`.

### Rules

1. **Format — descriptive, not executable.** For each test case, show:
   - Test ID and title
   - Endpoint (method + path)
   - Preconditions / setup
   - Request body (JSON)
   - Expected response (success/failure + key fields)
   - Assertions on specific field values
   - Side effects (DB changes, cascade behavior) where relevant
   - Do **NOT** generate concrete runnable commands (no curl, no shell scripts).

2. **Coverage requirements:**
   - Cover **every API endpoint** introduced or modified by the plans (both new and changed).
   - Cover **all VO/config structures** end-to-end (set via update, verify via query).
   - Include **negative cases**: missing required fields, invalid state transitions, wrong entity type.
   - Include **cascade behavior**: create → copy → delete chains to verify side effects.
   - Include **cross-entity interaction** where applicable (e.g., bot → skill relations → agent config).

3. **Regression tests — protect existing behavior:**
   - For every **modified** endpoint, add regression test cases that exercise the **pre-existing** request/response contract **without using any new fields**.
   - Verify existing filters, validation rules, and constraints still work unchanged.
   - Verify response schema backward-compatibility (no fields removed or renamed).
   - Verify business rules that should NOT be relaxed for existing entity types.

4. **Do NOT test:**
   - SQL migration scripts (DDL/DML) directly.
   - Internal code structure (enums, constants, mapper XML).
   - Compilation or unit-level concerns.

5. **Structure:**
   - Start with **Section 0: Regression** (existing behavior preservation).
   - Then group by feature area (CRUD, config update, bindings, copy, delete cascade, etc.).
   - End with an **execution order & variable dependency** graph.
   - Use `$VARIABLE_NAME` placeholders for IDs created during the test flow.

6. **Derive everything from the plans.** Read all files in `02-plan/` to understand:
   - What endpoints exist (new and modified).
   - What request/response fields were added.
   - What service-layer behaviors changed (cascade delete, cascade copy, constraint relaxation).
   - What data flows end-to-end (create → config → snapshot → publish).

阶段二：生成可执行 curl 脚本

You are a QA expert. Based on the test cases in `03-tests/`,
create executable E2E tests using curl and run them. 
The following is a runnable curl demo:
[CURL_DEMO]

CURL_DEMO 是从当前系统导出的可执行的 curl 命令，包含 cookies 以维持登录态。

Frontend

前端 E2E 调试有两种主流方式：

维度	Chrome DevTools	Playwright MCP
原理	Agent 通过 MCP 连接真实浏览器，人工保持 DevTools 打开观察	Agent 通过 Playwright MCP 用无头浏览器自动操作页面
调试反馈	Console 日志实时可见，人工可随时介入	截图 + DOM 快照自动回传给 Agent，无需人工监看
操作方式	Agent 只负责写代码，人工在浏览器中手动验证	Agent 直接控制浏览器（点击、填写、导航），全自动执行
适用场景	开发过程中的交互式调试，需要人工判断 UI 表现	回归测试、表单流程验证、可重复执行的 E2E 场景
优势	简单直接，不需额外配置；session 自动保持	完全自动化，Agent 能自我验证修复结果
劣势	依赖人工观察，无法自动化	需配置 Playwright MCP Server，复杂 UI 交互可能不稳定

建议：开发过程中用 Chrome DevTools 做交互式调试，回归验证时用 Playwright MCP 做自动化 E2E。

3.12 SDD 选型：speckit vs. superpowers

目前 SDD 工具有两种流行的实现路径：

维度	Speckit 风格	Superpowers 风格
核心理念	轻量级目录约定，以 Spec 文件为中心	Skill 框架，以可复用的 Agent 行为模板为中心
任务执行	顺序执行，每个任务独立 session	支持 Subagent 并行派发，主 agent 协调
Context 管理	手动指定每个任务的输入文件	通过 Skill 定义自动加载所需 context
适用场景	项目初期、流程简单、不需要并行	大型需求、多文件并行修改、需要角色分工
学习成本	低，只需理解目录约定	中，需要编写 Skill 定义和理解 agent 调度
执行效率	线性，受限于单 session 速度	更高，Subagent 并行可大幅缩短总时长

实践建议：从 Speckit 风格（手动目录结构 + 顺序执行）起步，熟悉 SDD 流程后，再引入 Superpowers 的 Subagent 机制提升执行效率。两者并非互斥——Superpowers 的 executing-plans skill 本质上就是在 Speckit 的 Spec 流水线之上加了自动化调度层。

Superpowers 核心阶段对应 Skill

开发阶段	推荐 Skill	说明
PRD / 需求探索	`brainstorming`	通过对话澄清意图，输出设计与 Spec，必须在实现前完成
Design / 系统设计	`brainstorming`	同上，设计需经人工 approve 后才进入下一阶段
Execution / 并行执行	`subagent-driven-development`	每个任务派发独立 Subagent，附带两阶段 Review（Spec 合规 + 代码质量）

跨阶段通用：

using-superpowers：元 Skill，每个 session 启动时自动检查可用 Skills
using-git-worktrees：为 feature 创建隔离工作区，避免污染主分支

4 效果展示

把上述方法串起来，在实际项目中落地的效果如何？

以某个实际需求为例——为智能客服平台新增一种完整集成平台模板的 Bot 运行模式 (ReAct Agent 模式)。在管理态，需要从枚举定义、数据库快照、服务层路由到前端 VO 全链路改造，同时必须保证已有模式的行为完全不变（向前兼容）。该需求涉及 2 个子项目，跨 30+ 个文件的新增和修改：

指标	传统开发	SDD 长任务 Vibe
总工时	~16 人天	~1.5 人天
效率倍数	基准	10x+
人工参与	全程编码 + 调试	PRD 编写 + 3 次审核 + 最终 CR
代码一致性	依赖个人水平	Agent 严格遵循 Spec，风格统一
测试覆盖	手动编写，覆盖率看心情	Agent 自动生成，覆盖全部 API 端点

省下来的不是编码时间，而是上下文切换时间。传统开发中，工程师需要在 30+ 个文件之间反复切换、记忆接口定义、保持一致性——这些正是模型擅长而人类容易出错的工作。

5 Future

从业务开发到 “Agent 员工开发”

每次清空 session 保证纯净 context，但关键信息如何跨 session 传递？当前依赖手动选择 memory，未来可优化到由 "Agent 员工" 自动管理。终极目标是每位工程师拥有自己的 Agent 员工阵列——Python NO.1 的后端 Agent、 Vue 偏执的前端 Agent、尤其喜欢回归历史 Bug 的测试 Agent，等等 —— 一切根据个人习惯和项目特点定制。

更轻、更通用的 AI IDE

当前流行的 IDE 工具存在模式冲突（Plan Mode 与 SDD Skills 的交互干扰）。开源社区日新月异，理想的 AI IDE 应该足够轻量——skills 动态加载即可，做好 Skill 与 “子 Agent” 集成（唤醒和通信），无需重量级的模式切换机制。

手动跨会话 Context 传递（“Context Engineer”）

SDD 用文档解决了跨 session 信息传递的问题，但"哪些信息需要传递"仍然依赖人的判断。未来或许能有可视化的 Context 选择工具——让工程师凭品味和专业知识手动筛选高价值 context，而非完全依赖自动压缩（或至少提供可选的自动化方案）。