01

课程简介

迭代 2 — 内容消费核心（Day 2 上午）

迭代 3 — 需求演进与功能改造（Day 2 下午）

核心挑战：模拟真实项目中"PM 改需求"的场景——在已交付代码上修改功能，而非添加全新模块。Agent 必须先理解已有设计意图，才能安全地修改。

本课程围绕 Harness Engineering 将知识点组织为 5 条知识体系，每条线在项目的不同阶段在用到的时候分层讲解，而非一次性灌输。

1. AI Native 认知、编程经验与 Harness 工程（约1.5h）

目标：建立"AI Native"思维，理解 Harness 工程体系，掌握核心实战经验

1.1 AI 能力演进的工程含义（10min）

• 从补全到推理（CoT / o1 / o3）：能力跃迁对软件工程意味着什么

• S-P-A 架构速览：Agent 如何感知-规划-执行（规格驱动/Agent友好架构的理论基础）

• 三级记忆模型：为什么上下文管理是 Agent 的核心挑战

• 未来工作模式：全能个体 + 多 Agent 与 Harness + 上下文窗口与成本管理

1.2 AI 编程核心经验（25min）

• 设计先行，架构不能外包

• 用 CLAUDE.md 或合适的 md 固化约束，而不是每次在 Prompt 里重复

• 把需求写成结构化 Prompt，而不是口头描述

• 小步拆解，每步可验证

• 用好 Git，随时掌握节奏

• 必须看代码，很多微观工程决策需要人来定，代码量增长后及时重构

• 管理好 Session 和上下文窗口

• 了解哪些任务AI不擅长

• 分清执行类和架构类任务，善用对比提问

• 对 Agent 保持高可观测性

• 保持人类最终裁决权（HITL）

1.3 Harness 工程系统介绍（35min）

• 什么是 Harness：模型只是拼图的一块，模型外部的工程组件共同组成 Agent 的 Harness，同等决定任务质量。

• Harness 项目空间纵览：展示一个典型项目完整Harness全貌

• 从四个层次理解Harness构筑的完整体系：文档层 -> 经验层 -> 约束层 -> 执行层

• Harness 的团队治理与 Git 管理：团队共治 Harness 时的现实思考

1.4 工具链说明（10min）

• 工具与模型选择：Agent介绍，为什么选择Claude Code，GLM / DeepSeek的选择

• Claude Code实用技巧：上下文超 50% 时主动 /compact 并指明保留方向；走偏了 Esc Esc 回滚，不硬扛；复杂任务先 Shift+Tab 进入 Plan Mode 规划再执行；小任务一句话完成，别上全套流程。

2. 产品设计（约1.5h）

目标：完成产品定义和可执行 Spec

2.1 [实践步骤] 竞品分析 + PRD 生成（10min）

• 任务：分析 Viki / WeTV / DramaBox 核心功能，生成 DramaFlow PRD

• 产出：PRD.md（All-in-One 单文件，包含以下内容）

     ○ 产品定位与目标用户：一句话定位、用户画像分层

     ○ 功能范围：按迭代划分，标注 P0/P1/P2 优先级，关联实现端

     ○ 非功能需求：性能、安全、兼容性等约束

     ○ 技术架构概要：前后端选型与通信方式

2.2 [实践步骤]  撰写可执行 Spec（20min）

• 为什么 PRD 不够用：PRD 描述"做什么"，但开发需要"怎么做才算完成"。可执行 Spec 的每项验收标准（AC）都可供开发者或 AI Agent 逐条自检，减少理解偏差和返工。

• 五段式格式：领域名词 → 前置条件 → 主流程 → 异常处理 → 验收标准（AC）。

• 范围：仅覆盖迭代 1+2（Drama / Episode / User / WatchRecord），迭代 3 的 Spec 在 Day 2 下午以增量方式补写

• 产出：SPEC.md 初版；培训场景以主体功能可用为验收标准，无需追求完备性

• 提效演示：让 Claude 从 PRD 草稿自动提取五段式 Spec 骨架，人工确认 AC

• HITL 检查点：AC 的最终确认必须由人完成

2.3 [实践步骤] 建可执行设计系统并创作原型（25min）

• 原型设计的演进：从说明书（Axure）到可复用组件（Figma）到可执行产品（v0/Bolt），AI 越能生成，设计系统的约束越重要

• 创建第一版可执行设计系统：tokens + constraints + design-rules，也可从已有 HTML 提取

• 利用 Claude Code 做原型设计：可利用 CLAUDE.md 或封装 Prototype Skill 确保生成复合约束

• 其他工具推荐：v0.dev（React 原型）、Claude Design（交互原型）

• Spec + 可执行设计系统 + 原型：三者分工——逻辑正确性、视觉一致性、流程可见性

• 产出：design-system/ + prototype/ 可交互原型

2.4 [实践步骤] 可执行设计系统下的视觉验收（15min）

• 代码合规（自动）：Skill 生成时扫描 hardcoded 色值，ESLint / CI 提交时拦截——这层不过，后两层保障失效

• 渲染正确（工具辅助）：代码正确 ≠ 渲染正确；H5 用 Playwright 截图建基准快照，移动端靠布局树 + ROI 像素检查分层叠加

• 渲染验收的核心挑战：动态内容、CDN 图片、跨设备渲染差异造成大量噪音——难点不是"怎么对比"，而是"怎么区分真正的回归和正常差异"；多 baseline 消噪 + AI 看图兜底是推荐应对

• 体验质量（人工）：视觉节奏、信息层级、交互情绪感无法自动化；前两层卸掉合规负担，人工走查才能专注这里

• 写入视觉 AC：将可测量标准（如"卡片标题最多 2 行截断"）写入 SPEC.md，开发逐条自检

2.5 [Agent友好架构][HITL] PM 利用 Agent 直接改代码快速试错（10min）

PM 用自然语言描述产品优化意图，Agent 直接改代码（H5 + 后端），PM 在预览环境验收改动效果，满意后开发接手并参考改动。

• 预览部署：每次提交可自动构建并部署到 SaaS 预览环境（含后端 + H5），PM 获得可分享的预览链接。

• 改对地方：Agent 友好架构是前提——模块 README 清晰、CLAUDE.md 描述全栈结构，Agent 能准确理解改动涉及哪些层，减少误改和漏改。

• 可观测性：错误和变更影响以产品语言呈现，PM 无需读日志即可判断改动是否符合预期。

• PM 专用 Skill：preview-change（描述本次改动对用户的影响）、safe-check（提交前验证，结果以非技术语言呈现）

• 开发接手：开发可直接参考，形成协作闭环

3. 项目工程化 + 方法论准备（约 60min）

目标：搭建 Agent 友好型项目骨架，写入最小约束，完成数据建模，预习工具化 SDD

3.1 [Agent友好架构] CLAUDE.md 是 Agent 的”宪法”，Repo 即 Agent 的”操作系统”

3.2 [实践步骤] 项目初始化 + 架构骨架（15min）

• 指令示例：基于 SPEC.md 的模块划分，生成 Kotlin Android 项目骨架 + Vue3 H5 项目骨架 + Python FastAPI 后端骨架 + SQLite 初始化脚本

• 产出：可编译的项目目录结构（android/ + h5/ + backend/）+ 每个模块的 README 模板

3.3 [实践步骤][规格驱动] 撰写 CLAUDE.md + Prompt SDD 初体验（15min）

• 写入技术栈说明、架构约束（禁止跨模块直接调用）、命名规范、构建方式、测试命令，只放不可推断的信息，能从代码推断的不写。

• 写入 SDD 最小约束：接受任务前必须阅读对应 Spec、生成代码后自检 AC

• 演示：”无 Spec” vs “有 Spec”的 AI 响应差异；CLAUDE.md 中 SDD 约束如何影响 Agent 行为。

• Prompt SDD 的本质：在 CLAUDE.md 中固化约束 → Agent 读取后自动遵循

3.4 [规格驱动] OpenSpec：从 Prompt SDD 到工具化 SDD（15min）

• 问题暴露：项目复杂度上升后纯 Prompt 约束的局限（约束易遗漏、AC 无法自动化验证、Traceability 缺失）

• OpenSpec 核心能力演示：Change Proposal → Spec → Task → 实现

• 工具原理说明：Claude Code、OpenSpec 与 Spec 的互动关系

• 与 Prompt SDD 的对比：什么样的团队 / 项目值得引入工具化 SDD；说明两者并存，迭代开发时学员可自选使用

3.5 [实践步骤] 数据模型设计（15min）

• 任务：Drama / Episode / User / WatchRecord 数据模型 + SQLite 建表脚本 + 测试种子数据（SQLAlchemy ORM + 初始化脚本）

• 自我尝试：第一轮不读 SPEC.md 直接让 AI 生成模型 → 第二轮加入约束重新生成 → 对比差异，体会 SDD 如何约束输出质量

• 重点关注：WatchRecord 的字段设计（播放进度、时间戳），为迭代 2 播放进度持久化打基础

4. 迭代 1：用户认证 + 首页（约 3h）

功能：FastAPI JWT 认证 + 首页（Banner + 分类 + 剧集列表）

4.1 [实践步骤] Auth 模块开发（35min）

• 任务：Python FastAPI 认证接口（注册 / 登录 / JWT）+ Kotlin Android 登录页（ViewModel + LiveData 表单）

• 演示重点：Claude Code 读取 CLAUDE.md + auth/README.md + SPEC.md → 生成代码（Agent 如何利用上下文）

• 开发策略：先生成 Auth Service + API 路由（后端），再补充 Android UI 逻辑（多轮约束生成）

• Java 辅助演示：同一登录接口用 Java Spring Boot 实现一遍，对比 AI 在两种语言下的代码生成差异

4.2 [实践步骤] Home 首页开发（40min）

• 任务：Python 后端 /api/dramas 接口 + Vue3 H5 首页（Banner 轮播 + 分类 Tab + 剧集列表 + Pinia 状态管理）+ Android WebView 加载

4.3 [实践步骤] 实现第一个 Skill（25min）

• Skill 设计方法与适用场景：什么场景应该封装成 Skill？颗粒度如何把握？Skill目录结构，参数设计原则（最小化、自包含）

• 最佳实践：幂等性（可重复调用不产生副作用）、结构化反馈（成功/失败/变更明细）、可重复调用的设计模式、无需推理的固定逻辑考量用代码实现。

• 实现 rebuild-deploy Skill：编译 H5 → 启动后端 → 启动模拟器 → 安装 App 全流程，一键部署到模拟器

• 参考最佳实践，尝试重构和简化skill，讨论“用代码实现无需推理的固定逻辑”的必要性

4.4 [测试自愈] 怎么做测试（20min）

• 选择API级测试：单元测试绑定实现，AI 加速后技术债积累更快，维护成本高于价值。后端用 pytest 测 API 行为，不测实现。

• 选择行为级测试：Android 用 Espresso / ADB / UI Automator 测用户操作流程，可以设计为利用 Claude Code 等 Agent 调度测试流程

• 用 AI 生成测试场景矩阵（正常 / 异常 / 边界），人工筛选关键场景

• 实现 spec-validate Skill：以 Spec 为唯一来源，AC 覆盖检查，补充 API 测试，作为 SDD 的验收门

4.5 [实践步骤] CR + 重构（20min）

• 实现 cr-refactor Skill：输出 CR 清单 + 重构建议，参数最小化设计（只接受路径，自动定位问题）

• 寻找重构线索的提问框架及AI高频错误模式（重复逻辑 / 状态泄漏 / 命名混乱 / 不遵循设计 / 啰嗦的注释或实现）

• 学员按优先级执行 2–3 条重构，人工确认不破坏已通过的集成测试。

5. Day 1 分享总结（20min）

目标：让学员将一天的实战体验转化为可表达的认知，暴露问题，共同探讨解决方案

• 今天最大的一个发现 / 踩过的一个坑

• 探讨高频问题

• 提出明天迭代 2 的关注点（带着问题进入第二天）

6. 迭代 2：剧集详情 + 播放器（约 3h）

功能：Drama Detail 页（Vue3 H5）+ ExoPlayer 视频播放器（Android）+ 播放进度持久化

6.1 [实践步骤] Drama Detail 页（25min）

• 任务：Python 后端 /api/dramas/{id} 接口 + Vue3 H5 详情页（简介 / 集数列表 / 评分）+ Android WebView 加载

• 演示重点：Agent 如何通过 Project Context 自动发现关联的 Pydantic 模型（跨文件定位）；Android WebView 与 H5 的通信机制（JSBridge）

• 根据 AC 补充 API 测试

6.2 [实践步骤] 视频播放器集成（35min）

• 任务：Python 后端七牛云（Qiniu）签名 URL 接口 + Android ExoPlayer 集成 + 自定义控制条（Kotlin）

• 根据 AC 补充 API 测试

6.3 [实践步骤] 播放器状态机（20min）

• 任务：实现最基础的状态记忆

• 留意状态机缺陷（缓冲/错误状态遗漏），识别"必须人工接手"的信号

• 根据 AC 补充 API 测试

6.4 [实践步骤] 播放进度持久化（25min）

• SQLite WatchRecord 模型 + 播放记录读写接口 + Android 写入调用

• 根据 AC 补充 API 测试

• Bug 注入演练——让 Agent 读取 Python / Android 错误日志自动修复；如何写出"不脆弱"的集成测试

6.5 [实践步骤] 迭代 2 CR + 重构（20min）

• 两轮代码积累后的系统性重构——跨模块重复模式识别；重构 vs 重写的判断标准；保持行为不变的重构提示词

• Architecture as Code——演示将架构规则嵌入 ruff / pylint（Python）/ Android Lint 自定义规则，阻止 AI 生成违规代码；ADR 写法示例

6.6 [实践步骤] Agent 自动化验收 / 探索性测试（25min）

• 解读测试框架：了解 test-agent（基于 ADB）的 CLI 命令、核心模块及原理

• 设计验收场景：编写 mission YAML，定义从登录到播放的核心验收路径，明确预期屏幕和通过条件

• 编写验收测试 Skill：理解 Skill 如何编排"截图→观察→定位→操作→记录→检查"的执行循环，基于 test-agent CLI 实现验收测试 Skill，设计参数（指定 mission 路径）、执行逻辑和结果反馈格式

• 执行和完善验收测试：运行测试 → 修复遇到的框架缺陷、环境适配、步骤不合理等问题 → 利用屏幕知识 screen_knowledge/ 提高执行效率和稳定性

6.7 [实践步骤] 实现 MCP Server（25min）

• MCP 设计方法与适用场景

• 场景：内容运营通过 AI 查询剧集数据和用户观看统计，无需直接接触数据库——既能用自然语言提问，又限制了原始数据的访问权限

• 任务：为 DramaFlow 实现一个只读 MCP Server，暴露两个工具：

      ○ get_drama_stats：查指定剧集的播放量、评分、平均完播率

     ○ get_user_watch_summary：查用户近期观看记录（最近观看剧集、完播数量、累计时长）

• 演示重点：MCP 工具定义 → 在 Claude Code 中注册 → 用自然语言触发工具调用（"查一下剧集 ID 为 3 的播放量和完播率"，"用户 1 最近在看哪些剧？"）

• 与 Skill 对比：Skill 编排 Agent 的执行流程，MCP 向 Agent 暴露受控的系统能力——两者解决不同层次的问题，可以组合使用

7. Day 2 上午分享总结（15min）

目标：趁着进入最复杂迭代（需求改造）之前，沉淀前两个迭代的认知

• 迭代 2 中遇到的最棘手问题（播放器状态 / AI 上下文断裂 / 测试不稳定）

• 重点讨论："AI 在哪里失效了？你是怎么接手的？"

• 迭代 3 的挑战：在已有代码上改需求，如何兼顾设计与实现

8. 迭代 3：需求演进与功能改造（约2.5h）

改造场景：首页推荐改版 + 播放器功能增强 + Auth 增强

8.1 [规格驱动]增量更新可执行 Spec（10min）

• 迭代 3 是需求演进，而非全新开发——原有 SPEC.md 中的 AC 需要增量更新

• 变更 Spec 的原则：直接覆盖为最新意图，历史由 git 记录。

• 演示：在首页推荐改版场景中，在原 Spec 基础上追加新 AC，标注哪些变更了

8.2 [规格驱动] 引入 GSD —— 执行优先的上下文工程（20min）

• 存量改造最大的挑战不是"改哪里"，而是"让 Agent 理解上下文不丢失"（context rot）

• GSD 核心理念：执行优先的上下文工程——用新鲜上下文隔离将复杂改造拆为上下文独立的原子波（Wave），并行编排、按阶段推进、每阶段可验证

• 安装与演示：修改首页推荐前，先用 GSD 思路输出"当前行为分析"→ 按阶段分解 → 逐阶段执行，适用长任务、跨模块改造、重构。

• 建议安装 Superpowers（与GSD同作者），并使用其中的 systematic-debugging，requesting-code-review 等实用技能。

8.3 [实践步骤] 首页推荐改版（40min）

• 任务：修改后端推荐 API（从按分类查询改为基于 WatchRecord 的个性化排序）+ 更新 Vue3 H5 首页数据绑定

• 用 gsd 相关命令开发，project → milestone → phases，重流程，对比"直接改"的 AI 响应

• 在变更的 AC 旁用注释标注变更版本以便追溯（可选），或直接依赖 git 记录。

• 根据 AC 补充 API 测试

• 遇到 Bug 尝试用 RCA(Root Cause Analysis) 框架走一遍，现象 → 证据 → 假设 → 验证 → 根因

8.4 [实践步骤] 播放器增强 + Auth 增强（40min）

• 播放器：在已有 ExoPlayer 状态机中新增倍速枚举和状态转换（Kotlin）→ 演示 AI 对有限状态机的理解局限

• Auth：Android SharedPreferences / EncryptedSharedPreferences 持久化 Token + FastAPI JWT 自动刷新逻辑 → 安全逻辑须人工逐行审阅，不能依赖 AI 判断

• 根据 AC 补充 API 测试

8.5 [实践步骤] 迭代 3 CR + 重构（25min）

• 需求变更引入的技术债 vs 新增功能的技术债——区分"接受"和"立即修复"

• cr-refactor vs gsd:code-review vs requesting-code-review：前者是快速扫描影响范围，适合"先看看再改"；后两者是系统化的阶段化执行框架，适合"知道要改什么但步骤复杂"。它们是替代选择，按场景选用。

• SDD 闭环回顾 —— Spec 变更 → 代码变更 → 测试验收 - CR重构 的完整链条

9. 深入知识点讲解（约1h）

目标：系统总结两天实战经验，深入讲解案例未能充分展示的内容

9.1 通过 Agentic Harness 工程自动优化 Harness（20min）

• 自动演化三重障碍：异质动作空间、轨迹信息淹没、效果难以归因。核心洞察：瓶颈在可观测性，不在 Agent 能力

• AHE 三支柱：组件可观测性 → 经验可观测性 → 决策可观测性

• 关键结论：增益在 tools / middleware / memory，不在 system prompt；Harness 事实性结构可跨模型转移，散文式策略不可转移

• Claude Code 落地：Session JSONL → 提取失败信号 → LLM 分析根因 → harness 变更 → 频次对比验证

9.2 Harness 工程疑难杂症应对（25min）

• 高频问题：遗留代码无测试，Agent 过度重构，规范臃肿，多步骤错误累积，长会话规则失效等等

• 设计反模式：过时假设、重叠规则、防御性膨胀、万能 Prompt 补丁、推理替代脚本等等

• 维护原则：区分不可替代的架构约束和可淘汰的重复提示，换模型即跑裸奔基线退役无效组件，修复Harness的步骤

9.3 SDD 生态全景与扩展策略（15min）

• 回顾三层 SDD 递进：Prompt SDD（迭代1）→ OpenSpec（迭代2）→ GSD（迭代3）

• SDD 生态一览：

     ○ GSD（上下文工程层）：新鲜上下文隔离 + 波级并行编排，解决长任务上下文衰减

     ○ OpenSpec（变更隔离层）：棕地优先，变更目录防串扰 + 完整审计追踪

     ○ Spec Kit（企业治理层）：规格即契约，宪法机制统一团队规范

     ○ Kiro（代理 IDE 层）：意图即代码，最低摩擦的独立加速器

     ○ Trellis（跨平台工作流层）：工具无关的 Spec/Task，多 Agent 无缝切换

• SDD 的定制与扩展：认清 SDD 做的事，什么时候需要扩展，三种扩展方式

路老师：AI应用与研发效能领域的资深专家，曾在理想汽车、快手等多家企业任高阶技术管理岗位。他具有扎实的编码、设计、架构，以及丰富的大模型应用建设经验，主导研发过多款基于大模型的产品，包括AI数字助理、代码智能补全与生成系统、营销AI智能体等等。他也曾为众多企业交付过AI编程、技术实践、DevOps及项目管理等方面的咨询或培训服务。

翰德恩咨询，汇聚众多华为等世界500强10年以上资深专家与AI数智化实战专家，以深厚的IPD实战经验为底座，以敏捷方法为执行引擎，以AI技术为驱动，帮助企业重构业务流程、提升研发效能，实现降本增效与业绩持续增长。我们倡导轻量化IPD导入、敏捷与AI融合落地，结合企业行业特点与组织能力量体裁衣，已辅导众多企业实现升级——让效率看得见，让增长真实现！