写给正在掉头发的你你有没有过这样的经历通宵写完一个“用户登录”功能第二天测试同学给你报了七八个 Bug邮箱没校验、密码没限制、重复注册没拦截……你一边改一边嘀咕“需求又没说清楚”如果我告诉你从今天开始你不再是一个人战斗了——你有一个AI 搭档它能读懂你写的“合同”自动帮你写测试、写代码、甚至重构。而你只需要做两件事把需求说清楚把结果审一遍。这就是本章要带你认识的新工作方式Harmes Agent 驱动的 SDDTDD 开发模式。1.1 三个故事三种人生小明的故事没有方法论没有 AI小明接到作业“写一个登录注册功能。”他打开 VS Code 就开始干。写完发现邮箱没校验补上又发现密码太短再补最后代码成了一锅粥改一个地方就担心别的地方崩掉。提交后助教反馈“你这里重复邮箱的提示信息不对啊”小明心里苦“你之前也没说要返回什么错误码啊……”小红的故事有方法论没有 AI小红先花 15 分钟写了一份规格文档把邮箱格式、密码规则、各种错误情况都列得清清楚楚。然后她先写测试看着测试失败一片红再从容地写出让测试通过的代码。最后她甚至大胆地重构了代码结构因为测试这个“安全网”会告诉她有没有改出问题。最终她的代码几乎没有 Bug还特别容易看懂。小蓝的故事有方法论也有 AI 搭档小蓝也先写了一份规格文档但她写的是Spec.md——一份结构化的、AI 能读懂的“合同”。然后她对 AI 搭档说“这是需求先帮我写测试。”AI 在 30 秒内生成了 15 个 pytest 测试用例全部红灯。小蓝又说“现在帮我写代码让测试变绿。”AI 又生成了核心实现代码15 个测试全部通过。小蓝最后说“帮我重构一下提取常量拆分函数。”AI 照做了测试依然全绿。小蓝写代码了吗几乎没有。但他做了更重要的事定义“做什么”和“怎么算做对了”。代码是 AI 写的但质量是小蓝的。你想做小明、小红还是小蓝这门课让你成为小蓝。1.2 基础概念三个名词改变你的编程生涯1.2.1 SDD还没写代码先写“契约”SDDSpecification-Driven Development规格驱动开发是一种“先定义再实现”的开发方法。在写任何代码之前我们先产出一份功能规格说明书它就像是功能的“合同”或“契约”规定了输入是什么长什么样有哪些限制输出在成功时给什么失败时又是什么错误信息边界条件极端情况、异常情况怎么办业务规则核心的计算逻辑或状态变化SDD 的核心原则很简单也很有力先定义再实现不写没有规格的代码规格即契约任何变更必须先更新规格再改代码可验证性规格里不能有“差不多”、“大概”、“适当”这种废话必须能测试想象一下你要装修房子是先画设计图还是直接抡锤子砸墙SDD 就是那张设计图。1.2.2 TDD让测试成为你的“安全带”TDDTest-Driven Development测试驱动开发由 Kent Beck 老爷子提出节奏感极强跟着三个节拍跳舞红Red先写一个会失败的测试用例。这个测试就是你对代码的期待。绿Green编写刚好能让测试通过的最简单代码。别多想别过度设计。重构Refactor在测试全部通过的“绿色保护”下优化代码结构让它更美、更清晰。TDD 就像赛车手的安全带。有了它你才敢在重构的赛道上飙车因为每次微调测试都会自动告诉你“没翻车继续开”或者“翻车了快回退”1.2.3 Harmes Agent你的 AI 搭档Harmes Agent是一个 AI 开发助手它能读懂你写的 Spec.md结构化规格文档自动生成符合规格的 pytest 测试用例自动编写刚好让测试通过的最简实现代码自动执行代码重构优化自动维护需求追溯矩阵和测试报告但有一件事它不做定义需求。这件事只有你能做。Agent 是你的手Spec.md 是你的脑。1.3 一张表看懂三者的分工维度SDD规格驱动TDD测试驱动Harmes Agent关注点做什么What做得对不对How自动执行循环产出物Spec.md 规格文档测试用例 实现代码测试代码报告自动生成谁来做你人类你 Agent 协作Agent 自动执行编写时机编码之前编码过程中你定义任务后核心价值需求正确性实现正确性效率 ×10质量不减看到这张表了吗SDD 负责方向TDD 负责验证Agent 负责执行。你的角色从一个“码农”升级成了一个“指挥官”。1.4 SDD TDD Agent 结合工作流以后我们写 Python 登录功能就会反复走下面这个流程。现在你可以先把它理解为一种“三人舞蹈”flowchart TD A[你分析需求] -- B[你书写 Spec.mdSDD] B -- C[你 团队评审 Spec.md] C -- D[Agent自动编写测试TDD-Red] D -- E[Agent自动实现代码TDD-Green] E -- F{Agent 运行测试} F --|不通过| E F --|全绿| G[你审查代码质量] G -- H[Agent重构优化TDD-Refactor] H -- I[Agent生成测试报告与追溯矩阵] I -- J[你最终审查 合并]注意这个流程中的分工步骤谁来做做什么分析需求你理解用户想要什么写 Spec.md你把需求翻译成结构化规格评审 Spec你 团队确保需求理解一致写测试Agent根据 Spec 自动生成 pytest 用例写代码Agent写刚好通过测试的最简实现运行测试Agent自动运行全绿才进入下一步审查代码你确认代码符合你的预期重构Agent优化代码结构测试保持全绿生成报告Agent自动生成 HTML 报告 追溯矩阵最终审查你验收合并到主分支你写的是“合同”Agent 写的是“交付物”。1.5 登录规格初体验一份 Agent 可读的 Spec.md 长什么样假设我们要做一个最简单的用户登录功能以邮箱和密码登录。在你对 Agent 说任何话之前我们先写一份它看得懂的迷你 Spec.md。这只需要简单的 Markdown YAML 头部--- spec: name: 用户注册功能 version: 1.0.0 status: draft --- # 用户注册功能规格 ## 功能描述 提供用户注册能力。用户通过邮箱和密码完成注册返回用户标识和邮箱信息。 ## 输入参数 ### email -类型: string -必填: true -约束: 符合邮箱格式含 长度 ≤ 255自动去首尾空格并转小写 ### password -类型: string -必填: true -约束: 长度 8–64至少包含一个字母和一个数字 ## 输出结果 ### 成功HTTP 201 { userId: UUID v4 自动生成, email: 规范化后的邮箱 } ### 失败HTTP 4xx | 错误码 | HTTP 状态码 | 触发条件 | |--------|-------------|----------| | INVALID_EMAIL_FORMAT | 400 | 邮箱格式非法或长度超限 | | PASSWORD_TOO_SHORT | 400 | 密码长度 8 | | PASSWORD_TOO_LONG | 400 | 密码长度 64 | | WEAK_PASSWORD | 400 | 密码不含字母或数字 | | EMAIL_ALREADY_REGISTERED | 409 | 邮箱已被注册 | ## 边界条件 -邮箱长度刚好 255 字符允许注册 -邮箱长度超过 255 字符拒绝 -密码刚好 8 位允许 -密码刚好 64 位允许 -邮箱含首尾空格和大写字母自动规范化你看这份文档就是给 Agent 看的“合同”。有了它Agent 就知道你要什么然后自动帮你写测试、写代码。而你要做的就是确保这份合同写得对。1.6 这种新模式的三大优势1.6.1 效率 ×10质量不减传统开发你写测试30 分钟→ 你写代码1 小时→ 你重构30 分钟≈ 2 小时。Agent 开发你写 Spec20 分钟→ Agent 写测试代码重构3 分钟→ 你审查15 分钟≈ 38 分钟。你把时间花在了“思考”上而不是“打字”上。1.6.2 需求追溯自动生成以前你需要手动维护一份“需求 → 测试 → 代码”的追溯矩阵。现在Agent 在生成测试和代码的同时自动维护这份矩阵。任何时候你想知道“这个 Bug 对应哪条需求”打开traceability.md就够了。1.6.3 文档永不“过时”传统项目里代码改了但文档没改是常态。但在 Agent 模式下Spec.md 是唯一的真相来源。如果代码不符合 Spec测试会红Agent 会修复。如果你改了 SpecAgent 会重新生成测试和代码。文档和代码永远是同步的。1.7 什么场景最适合用这门课的场景就是其中之一后端 API 开发输入输出明确最适合写 Spec让 Agent 实现。对正确性要求极高的系统金融、医疗、考试系统每一条规则都可追溯到 Spec 的一条。课程设计 / 竞赛项目你有明确的需求文档或作业要求直接翻译成 Spec让 Agent 帮你写代码和测试。多人协作Spec.md 是团队的共同语言Agent 保证所有人的实现风格一致。当然也有几根“温柔的刺”要注意你不会写代码也没关系但你得会写 SpecSpec 的好坏直接决定了 Agent 产出的质量。Garbage in, garbage out。你必须审查 Agent 的产出Agent 会犯错。它写的代码可能符合 Spec 但结构不够好你需要做最终的“代码审查者”。别走火入魔像按钮动画、页面阴影这种 UI 细节别写 Spec 了直接自己调。Spec 最适合的是逻辑密集型的功能。1.8 这门课会带你经历什么在接下来的 10 章里你将搭好 Python 实验台和 Agent 配置第 2 章写一份完整的、Agent 可读的 Spec.md第 3 章看着 Agent 自动生成 15 个红灯测试第 4 章看着 Agent 逐个让测试变绿第 5 章让 Agent 补全边界测试织密安全网第 6 章审查 Agent 的代码并让它重构优化第 7 章让 Agent 集成数据库和 Web 框架第 8 章让 Agent 自动生成测试报告和追溯矩阵第 9 章把这一切方法论带走用到你未来的每一个项目里第 10 章拿到完整的项目文件清单随时可以复制运行第 11 章本章小结这一章我们没写一行代码但你认识了一个新朋友——Harmes Agent以及它和 SDD、TDD 的“三角关系”。SDD回答“我们要构建什么”你写 Spec.mdTDD回答“我们构建的是正确的东西吗”Agent 写测试Agent回答“我来帮你写测试、写代码、重构、出报告。”自动执行你的新角色是需求定义者 代码审查者。Agent 是你的手Spec.md 是你的脑TDD 是你的安全带。最后请记住这门课将要反复念诵的新口诀Spec 先写清楚Agent 自己跑红代码刚刚好审查重构不能少。下一章我们就卷起袖子搭好 Python 实验台并配置我们的 AI 搭档——创建 Agent.md、Task.md让它真正“认识”我们、了解我们的项目。你准备好了吗
写给正在掉头发的你你有没有过这样的经历通宵写完一个“用户登录”功能第二天测试同学给你报了七八个 Bug邮箱没校验、密码没限制、重复注册没拦截……你一边改一边嘀咕“需求又没说清楚”如果我告诉你从今天开始你不再是一个人战斗了——你有一个AI 搭档它能读懂你写的“合同”自动帮你写测试、写代码、甚至重构。而你只需要做两件事把需求说清楚把结果审一遍。这就是本章要带你认识的新工作方式Harmes Agent 驱动的 SDDTDD 开发模式。1.1 三个故事三种人生小明的故事没有方法论没有 AI小明接到作业“写一个登录注册功能。”他打开 VS Code 就开始干。写完发现邮箱没校验补上又发现密码太短再补最后代码成了一锅粥改一个地方就担心别的地方崩掉。提交后助教反馈“你这里重复邮箱的提示信息不对啊”小明心里苦“你之前也没说要返回什么错误码啊……”小红的故事有方法论没有 AI小红先花 15 分钟写了一份规格文档把邮箱格式、密码规则、各种错误情况都列得清清楚楚。然后她先写测试看着测试失败一片红再从容地写出让测试通过的代码。最后她甚至大胆地重构了代码结构因为测试这个“安全网”会告诉她有没有改出问题。最终她的代码几乎没有 Bug还特别容易看懂。小蓝的故事有方法论也有 AI 搭档小蓝也先写了一份规格文档但她写的是Spec.md——一份结构化的、AI 能读懂的“合同”。然后她对 AI 搭档说“这是需求先帮我写测试。”AI 在 30 秒内生成了 15 个 pytest 测试用例全部红灯。小蓝又说“现在帮我写代码让测试变绿。”AI 又生成了核心实现代码15 个测试全部通过。小蓝最后说“帮我重构一下提取常量拆分函数。”AI 照做了测试依然全绿。小蓝写代码了吗几乎没有。但他做了更重要的事定义“做什么”和“怎么算做对了”。代码是 AI 写的但质量是小蓝的。你想做小明、小红还是小蓝这门课让你成为小蓝。1.2 基础概念三个名词改变你的编程生涯1.2.1 SDD还没写代码先写“契约”SDDSpecification-Driven Development规格驱动开发是一种“先定义再实现”的开发方法。在写任何代码之前我们先产出一份功能规格说明书它就像是功能的“合同”或“契约”规定了输入是什么长什么样有哪些限制输出在成功时给什么失败时又是什么错误信息边界条件极端情况、异常情况怎么办业务规则核心的计算逻辑或状态变化SDD 的核心原则很简单也很有力先定义再实现不写没有规格的代码规格即契约任何变更必须先更新规格再改代码可验证性规格里不能有“差不多”、“大概”、“适当”这种废话必须能测试想象一下你要装修房子是先画设计图还是直接抡锤子砸墙SDD 就是那张设计图。1.2.2 TDD让测试成为你的“安全带”TDDTest-Driven Development测试驱动开发由 Kent Beck 老爷子提出节奏感极强跟着三个节拍跳舞红Red先写一个会失败的测试用例。这个测试就是你对代码的期待。绿Green编写刚好能让测试通过的最简单代码。别多想别过度设计。重构Refactor在测试全部通过的“绿色保护”下优化代码结构让它更美、更清晰。TDD 就像赛车手的安全带。有了它你才敢在重构的赛道上飙车因为每次微调测试都会自动告诉你“没翻车继续开”或者“翻车了快回退”1.2.3 Harmes Agent你的 AI 搭档Harmes Agent是一个 AI 开发助手它能读懂你写的 Spec.md结构化规格文档自动生成符合规格的 pytest 测试用例自动编写刚好让测试通过的最简实现代码自动执行代码重构优化自动维护需求追溯矩阵和测试报告但有一件事它不做定义需求。这件事只有你能做。Agent 是你的手Spec.md 是你的脑。1.3 一张表看懂三者的分工维度SDD规格驱动TDD测试驱动Harmes Agent关注点做什么What做得对不对How自动执行循环产出物Spec.md 规格文档测试用例 实现代码测试代码报告自动生成谁来做你人类你 Agent 协作Agent 自动执行编写时机编码之前编码过程中你定义任务后核心价值需求正确性实现正确性效率 ×10质量不减看到这张表了吗SDD 负责方向TDD 负责验证Agent 负责执行。你的角色从一个“码农”升级成了一个“指挥官”。1.4 SDD TDD Agent 结合工作流以后我们写 Python 登录功能就会反复走下面这个流程。现在你可以先把它理解为一种“三人舞蹈”flowchart TD A[你分析需求] -- B[你书写 Spec.mdSDD] B -- C[你 团队评审 Spec.md] C -- D[Agent自动编写测试TDD-Red] D -- E[Agent自动实现代码TDD-Green] E -- F{Agent 运行测试} F --|不通过| E F --|全绿| G[你审查代码质量] G -- H[Agent重构优化TDD-Refactor] H -- I[Agent生成测试报告与追溯矩阵] I -- J[你最终审查 合并]注意这个流程中的分工步骤谁来做做什么分析需求你理解用户想要什么写 Spec.md你把需求翻译成结构化规格评审 Spec你 团队确保需求理解一致写测试Agent根据 Spec 自动生成 pytest 用例写代码Agent写刚好通过测试的最简实现运行测试Agent自动运行全绿才进入下一步审查代码你确认代码符合你的预期重构Agent优化代码结构测试保持全绿生成报告Agent自动生成 HTML 报告 追溯矩阵最终审查你验收合并到主分支你写的是“合同”Agent 写的是“交付物”。1.5 登录规格初体验一份 Agent 可读的 Spec.md 长什么样假设我们要做一个最简单的用户登录功能以邮箱和密码登录。在你对 Agent 说任何话之前我们先写一份它看得懂的迷你 Spec.md。这只需要简单的 Markdown YAML 头部--- spec: name: 用户注册功能 version: 1.0.0 status: draft --- # 用户注册功能规格 ## 功能描述 提供用户注册能力。用户通过邮箱和密码完成注册返回用户标识和邮箱信息。 ## 输入参数 ### email -类型: string -必填: true -约束: 符合邮箱格式含 长度 ≤ 255自动去首尾空格并转小写 ### password -类型: string -必填: true -约束: 长度 8–64至少包含一个字母和一个数字 ## 输出结果 ### 成功HTTP 201 { userId: UUID v4 自动生成, email: 规范化后的邮箱 } ### 失败HTTP 4xx | 错误码 | HTTP 状态码 | 触发条件 | |--------|-------------|----------| | INVALID_EMAIL_FORMAT | 400 | 邮箱格式非法或长度超限 | | PASSWORD_TOO_SHORT | 400 | 密码长度 8 | | PASSWORD_TOO_LONG | 400 | 密码长度 64 | | WEAK_PASSWORD | 400 | 密码不含字母或数字 | | EMAIL_ALREADY_REGISTERED | 409 | 邮箱已被注册 | ## 边界条件 -邮箱长度刚好 255 字符允许注册 -邮箱长度超过 255 字符拒绝 -密码刚好 8 位允许 -密码刚好 64 位允许 -邮箱含首尾空格和大写字母自动规范化你看这份文档就是给 Agent 看的“合同”。有了它Agent 就知道你要什么然后自动帮你写测试、写代码。而你要做的就是确保这份合同写得对。1.6 这种新模式的三大优势1.6.1 效率 ×10质量不减传统开发你写测试30 分钟→ 你写代码1 小时→ 你重构30 分钟≈ 2 小时。Agent 开发你写 Spec20 分钟→ Agent 写测试代码重构3 分钟→ 你审查15 分钟≈ 38 分钟。你把时间花在了“思考”上而不是“打字”上。1.6.2 需求追溯自动生成以前你需要手动维护一份“需求 → 测试 → 代码”的追溯矩阵。现在Agent 在生成测试和代码的同时自动维护这份矩阵。任何时候你想知道“这个 Bug 对应哪条需求”打开traceability.md就够了。1.6.3 文档永不“过时”传统项目里代码改了但文档没改是常态。但在 Agent 模式下Spec.md 是唯一的真相来源。如果代码不符合 Spec测试会红Agent 会修复。如果你改了 SpecAgent 会重新生成测试和代码。文档和代码永远是同步的。1.7 什么场景最适合用这门课的场景就是其中之一后端 API 开发输入输出明确最适合写 Spec让 Agent 实现。对正确性要求极高的系统金融、医疗、考试系统每一条规则都可追溯到 Spec 的一条。课程设计 / 竞赛项目你有明确的需求文档或作业要求直接翻译成 Spec让 Agent 帮你写代码和测试。多人协作Spec.md 是团队的共同语言Agent 保证所有人的实现风格一致。当然也有几根“温柔的刺”要注意你不会写代码也没关系但你得会写 SpecSpec 的好坏直接决定了 Agent 产出的质量。Garbage in, garbage out。你必须审查 Agent 的产出Agent 会犯错。它写的代码可能符合 Spec 但结构不够好你需要做最终的“代码审查者”。别走火入魔像按钮动画、页面阴影这种 UI 细节别写 Spec 了直接自己调。Spec 最适合的是逻辑密集型的功能。1.8 这门课会带你经历什么在接下来的 10 章里你将搭好 Python 实验台和 Agent 配置第 2 章写一份完整的、Agent 可读的 Spec.md第 3 章看着 Agent 自动生成 15 个红灯测试第 4 章看着 Agent 逐个让测试变绿第 5 章让 Agent 补全边界测试织密安全网第 6 章审查 Agent 的代码并让它重构优化第 7 章让 Agent 集成数据库和 Web 框架第 8 章让 Agent 自动生成测试报告和追溯矩阵第 9 章把这一切方法论带走用到你未来的每一个项目里第 10 章拿到完整的项目文件清单随时可以复制运行第 11 章本章小结这一章我们没写一行代码但你认识了一个新朋友——Harmes Agent以及它和 SDD、TDD 的“三角关系”。SDD回答“我们要构建什么”你写 Spec.mdTDD回答“我们构建的是正确的东西吗”Agent 写测试Agent回答“我来帮你写测试、写代码、重构、出报告。”自动执行你的新角色是需求定义者 代码审查者。Agent 是你的手Spec.md 是你的脑TDD 是你的安全带。最后请记住这门课将要反复念诵的新口诀Spec 先写清楚Agent 自己跑红代码刚刚好审查重构不能少。下一章我们就卷起袖子搭好 Python 实验台并配置我们的 AI 搭档——创建 Agent.md、Task.md让它真正“认识”我们、了解我们的项目。你准备好了吗
