一、课程总览

学习目标

1. 掌握 AI 时代软件开发范式：SDD → TDD
2. 理解Harness Engineering（驭缰工程） 核心思想
3. 完成Ralph与Hermes Agent实战演练
4. 落地 AI 投研工具全流程开发与质量保障

---

二、AI 时代的软件开发：从 SDD 到 TDD

2.1 SDD 规格驱动开发

核心定义

SDD（Specification-Driven Development）：规格 = 一等公民，代码是规格的可执行表达；Spec 既是给人看的需求，也是给 AI Agent 看的任务说明书。

传统开发 vs SDD

模式	流程	问题 / 优势
传统开发	口头需求 → 直接写代码 → 事后补文档	需求在人脑，AI 无法读取
SDD	写 Spec → 提取测试 → 按测试写代码	规格可版本化、可校验、可被 AI 读取

思考疑问

• 为什么 Spec 必须放在代码仓库，而不是外部文档？
• Spec 的约束条件如何直接转化为可执行测试？

2.2 TDD 测试驱动开发

核心铁律

没有先失败的测试，就没有生产代码；先写代码再补测试→删除代码，重新开始。

红 - 绿 - 重构循环

1. Red（红灯）：写最小失败测试，验证测试有效、功能未实现
2. Green（绿灯）：写最少代码让测试通过，不做多余设计
3. Refactor（重构）：测试保持通过前提下优化代码

关键意义

• 测试定义什么是对的，而非验证代码是否正确
• 避免被实现细节绑架，强制覆盖边界场景

思考疑问

• 为什么后补的测试不具备防护价值？
• TDD 如何避免 “自欺欺人” 的心理陷阱？

2.3 实战案例：正整数判断功能

错误做法

先写代码→后补测试，被isinstance细节绑架，遗漏True/字符串/None等边界。

正确 TDD 流程

1. Red：编写覆盖全场景的测试，运行失败
2. Green：编写最小实现，处理所有边界
3. 验证：测试全通过，代码满足业务规格

2.4 实战案例：AI 投研工具（SDD+TDD 落地）

Step1：撰写 Spec 规格文档

• 输出格式：股票代码、名称、报告日期、4 大分析维度、综合评级、风险因素、信息来源
• 约束条件 C1~C7（每条直接对应测试用例）

C1~C7 核心约束

1. C1：必须包含基本面 / 市场面 / 消息面 / 分析师4 个维度
2. C2：每个维度摘要≥100 字符
3. C3：置信度 0.0~1.0
4. C4：评级仅buy/hold/sell
5. C5：来源 URL≥3 个
6. C6：风险因素非空
7. C7：必填字段不可缺

Step2：TDD 落地（以 C4 为例）

1. Red：编写评级校验测试，函数未实现→失败
2. Green：实现validate_report最小校验逻辑
3. 运行：pytest 验证全用例通过

Step3：真实数据接入（akshare）

• 4 大维度对应数据接口：基本面、市场面、消息面、分析师评级
• 编写 API 测试，验证真实返回结构合法性

思考疑问

• AI 投研工具中，如何保证 AI 生成内容符合 Spec 约束？
• 集成测试与单元测试的边界如何划分？

---

三、Harness Engineering 驭缰工程

3.1 核心定义

Harness = 模型之外的一切：约束系统、反馈回路、工具环境、验证机制。

Agent = Model + Harness

工程范式演进

1. 2023 提示词工程：关注单次指令
2. 2025 上下文工程：关注信息管理
3. 2026 驭缰工程：关注系统环境，让 Agent 可靠自主

关键结论

工程师核心产出从写代码→设计 AI 可靠工作的约束系统。

3.2 Harness 三支柱

1. Inform（告知）：AGENTS.md 导航、上下文工程
2. Constrain（约束）：架构边界、Lint 规则、权限控制
3. Verify（验证）：自动化测试、类型检查、结构校验

执行顺序：告知→约束→验证，形成闭环

3.3 仓库即记录系统

核心原则

不在仓库里的信息，对 AI 等于不存在。

• 需求、规范、决策必须以版本化文件存入仓库
• 禁止依赖聊天记录、会议纪要、个人记忆

3.4 AGENTS.md：地图而非手册

规范

• 长度50~100 行，仅做导航，不堆砌细节
• 超过 60 行效果下降，避免挤占上下文窗口
• 渐进式披露：Agent 按需深入查阅详情

AI 投研案例 AGENTS.md 内容

• 关键文件导航：Spec、reporter、stock_data
• 开发约定：TDD 强制、Spec 同步、测试隔离
• 架构约束：依赖方向固定，禁止反向依赖

3.5 Lint 规则：机械化执行约束

核心价值

• 文档会 “腐烂”，Lint 规则不会
• 错误信息必须嵌入修复指令，让 Agent 可自我纠正

普通错误 vs Harness 错误

• 普通：只告知错误，Agent 无法修复
• Harness：错误 + 修复方案，形成自动纠正闭环

3.6 给 Agent 自由：约束越严，越可靠

结论

限制解空间→AI 更可靠；自由度越高，犯错概率越高。

• 架构约束、数据约束、命名约束、质量约束共同保障输出一致性

3.7 Agent 会复制坏模式

问题

Agent 会模仿仓库中已有坏代码，快速扩散技术债。

解决方案

• 放弃人工清理：不可持续
• 自动化垃圾回收：将好品味编码为 Lint 规则，定期自动扫描修复

3.8 Guides x Sensors 矩阵

	计算性（确定性 / 低成本 / 每次提交）	推理性（语义理解 / 高成本 / 选择性）
引导器（行动前）	脚本、代码模板、LSP	AGENTS.md、Skills、架构文档
传感器（行动后）	Lint、测试、覆盖率	AI Code Review、LLM 评审

引导 + 检测结合，提升首次成功率 + 兜底纠错

3.9 吞吐量改变合并理念

传统模式 vs Harness 模式

模式	人力 / Agent	合并策略	质量保障
传统	人力贵、低吞吐	精审 PR、慢合并	人工审查
Harness	Agent 便宜、高吞吐	快速合并、快速纠错	背压机制保底

背压机制

测试 / Lint / 结构检查不通过→强制 Agent 停止修复，防止代码腐烂。

3.10 CI/CD 质量门禁（三道门）

1. 第一道：结构 Lint 检查（秒级）
2. 第二道：单元测试（秒级）
3. 第三道：集成测试（分钟级，仅主分支运行）

---

四、Ralph 实战

4.1 什么是 Ralph

• 命名来源：《辛普森一家》Ralph（天真不可预测，需引导）
• 定位：Harness Engineering 开源实现，Bash 脚本编排器
• 能力：让 Agent 在循环中自主完成任务，人类仅写 PROMPT.md

4.2 Ralph 六大信条

1. Fresh Context：每轮清空上下文，提升可靠性
2. Backpressure Over Prescription：用背压代替处方
3. The Plan Is Disposable：计划可丢弃，成本低
4. Disk Is State, Git Is Memory：磁盘存状态，Git 存记忆
5. Steer With Signals：用路标引导，不微操
6. Let Ralph Ralph：人类设计约束，不介入执行

关键结论

Agent 出 Bug→改 Harness（补 Lint / 加测试 / 完善 AGENTS.md），而非手动改代码。

4.3 Ralph 帽子系统（角色隔离）

每轮迭代仅戴一顶帽子，避免任务混乱：

1. Planner（规划者）：拆解任务
2. Builder（构建者）：TDD 写测试 + 代码
3. Critic（审查者）：独立验证，不共享 Builder 上下文
4. Finalizer（终结者）：确认完成，输出 LOOP_COMPLETE

4.4 实战：构建 wc.py 文字计数器

人类输入

仅编写PROMPT.md（10 行任务描述）

全自动迭代

1. 规划者：拆分为具体步骤
2. 构建者：TDD 先写测试→实现→自修复 Bug
3. 审查者：独立验证全量场景
4. 终结者：确认完成，终止循环

成果

• 耗时：约 5 分钟
• 费用：≈2 元人民币
• 产出：wc.py+test_wc.py，全自动无人工编码

4.5 动手搭建 Mini Ralph

核心三步

1. 定义四顶帽子（System Prompt）
2. 按顺序调用 Qwen，循环迭代
3. 用文件（scratchpad.md）传递上下文

关键函数

• call_qwen：调用大模型
• run_tests：背压门控核心，测试不通过则触发修复

---

五、Hermes Agent 实战

5.1 什么是 Hermes Agent

• 定位：自进化 Agent，在 Ralph 基础上增加学习能力
• 能力：执行任务→自动创建 Skill→自我改进→持久化记忆

与传统 Agent 区别

• 传统：每次从零开始
• Hermes：越做越好，可复用技能

5.2 核心 Skill（4 大开发技能）

Skill1：测试驱动开发（铁律）

• 无失败测试→不写生产代码
• 先写代码再补测试→删除重来
• 击破常见借口：简单也要测、之后补测试无效、探索代码需丢弃

Skill2：编写实现计划

• 任务粒度：2~5 分钟 / 个，小而具体
• 拒绝大任务（如 “构建认证系统”）

Skill3：系统化调试（四阶段）

1. Root Cause：根因调查
2. Pattern：模式对比
3. Hypothesis：假设验证
4. Fix：先写回归测试再修复

三次法则：3 次修复失败→检查架构问题

Skill4：子 Agent 驱动开发

• 实施者→规格审查→质量审查（顺序不可颠倒）
• 双审查保障：做对 + 做好

5.3 Hermes 测试工程实践

1. 测试环境隔离：自动重定向 HOME、清空 API Key，避免真实调用
2. CI/CD 分层：单元测试并行、E2E 测试独立，密钥置空
3. 测试覆盖率：≈3000 个测试，保障全流程质量

---

六、AI 投研工具全流程整合

6.1 架构分层

akshare 真实数据 → Qwen 分析 → Analyzer 评分 → Reporter 组装 → Validator 校验

6.2 质量保障结果

• 结构 Lint：全部通过
• 单元测试：69 个全通过
• 真实数据测试：15 个通过、1 个跳过（网络波动）

---

七、核心知识递进总结

概念	作用	落地载体
SDD	定义什么是对的	spec/research_spec.md
TDD	证明它是对的	测试用例、pytest
Harness	保证一直对	AGENTS.md、Lint、CI/CD
Agent 编排	让 AI 自己做对	Ralph、Hermes

最终结论

测试与约束不再是辅助手段，而是 AI 时代 Agent 可靠工作的核心基础设施。

---

可提问思考清单

1. SDD 与 TDD 在复杂项目中如何协同，避免过度设计？
2. Harness Engineering 如何落地到企业现有研发流程？
3. Ralph 与 Hermes 的适用场景分别是什么？
4. 如何平衡 Agent 自由度与约束强度？
5. AI 生成代码的技术债如何长期治理？