大厂优秀工程师使用AI Coding的最新方法与经验
Coding Agent 已经可以根据一句话需求完成开发了，为什么我们还要学习方法？
在一些常见的小型项目中，一句话需求已经能够生成一个可以运行的初版。但这句话里通常还留着很多没有说清楚的内容：给谁用、在什么情况下用、需要哪些功能、做到什么程度才算符合预期。Agent 生成代码时会根据自己的理解补上这些，而这些补出来的内容是否符合实际需要，需要我们判断。
本文围绕四个问题展开：要做什么、怎样才算做对、用什么验证、根据什么继续修改。 前半部分讲 Spec 与 SpecDD，后半部分讲 Test Case 与 TDD，最后看两者怎样围绕同一条行为要求配合，并把这套方法整理成 Agent 可以读取的工作指引。
贯穿全文的案例是一个直播聊天分析应用：在本机监听一个直播间，在自己的界面显示采集到的评论；积累一段时间后，选择分析范围，向自己的 Agent 提问，例如"这段时间大家最关心的问题是什么"，在同一界面得到基于这批评论的回答。
2. 一句话能生成软件，为什么还要学习使用方法
在一句话需求的背后，通常还留着没有说清楚的部分。Agent 在生成代码时，会根据自己的理解补上这些内容。我们需要判断，它补出来的内容是否符合实际需要。
2.1 从一句话需求到具体的业务场景
比如"帮我做一个直播间聊天分析工具"。Agent 可以做一张词频图，也可以做自动回复机器人，或者做一个能针对评论提问的分析页面。这些方案解决的问题并不相同。
我们希望监听一个直播间，在自己的界面显示采集到的评论。积累一段时间后，选择分析范围，向自己的 Agent 提问，例如"这段时间大家最关心的问题是什么"，让它根据这批评论给出回答。
| 需要明确的内容 | 直播聊天分析应用 |
|---|---|
| 业务场景 | 使用者观察直播间评论，并围绕一段时间内的讨论提问 |
| 功能范围 | 开始与停止监听、显示评论、选择分析范围、提问与查看回答 |
| 关键效果 | 消息不重复入库，分析范围明确，回答可以对照实际评论 |
| 本次不做的事情 | 自动回复观众、管理直播间、检索站外资料或推断完整历史 |
明确了这些内容，才方便判断 Agent 给出的方案有没有偏离需求。如果只做成了词频图，就不能满足使用者自由提问、结合上下文理解讨论的需要。
2.2 为什么要固化关键效果
使用者选择 16:50～17:00，提问："这段时间大家最关心的问题是什么？"
模型可以用不同方式总结，但分析对象应该是这个范围内实际采集到的评论。把 17:05 才出现的话题算进去，或把两条评论描述成"所有观众都这样认为"，都会改变结果的含义。
固化关键效果，就是把需要保持的行为明确写下来，再用具体的检查方法确认它们是否成立。 例如：
- 同一条消息重复采集不重复保存；
- 开始分析时固定本次消息集合；
- 没有消息时提示范围为空；
- 回答可以回看对应评论。
如果只是临时验证一个想法，快速做出原型就很有帮助。如果希望做一个可以长期持续维护的真正产品，我们还需要明确场景、明确功能、固化关键效果。这样，开发结果是否符合预期就有了可以对照的标准。
实践前准备
实践涉及项目目录、运行环境、业务模型和浏览器采集入口。它们分别决定文档保存在哪里、代码怎样运行、AI 怎样处理消息，以及消息从哪里来。
一、所需工具清单
| 工具或材料 | 在开发中承担什么工作 |
|---|---|
| CodeBuddy IDE | 阅读项目、讨论方案、修改文件、运行命令和检查结果 |
| Chrome 与聊天采集入口 | 读取直播页面中的评论，在页面打开期间持续采集 |
| Python 与项目依赖 | 运行后端服务、模型请求和自动化测试 |
| Agently 与业务模型配置 | 在应用中发起模型请求，根据所选评论和使用者的问题生成分析回答 |
| Agently-Skills 套件 | 帮助 Coding Agent 正确选择和使用 Agently 的能力 |
CodeBuddy 中负责写代码的模型，与直播聊天分析应用运行时调用的业务模型，是两处独立配置。CodeBuddy 能正常对话，还不能说明应用已经能够调用业务模型。
Skills 是 Agent 可读取的工作指引。安装 Agently-Skills 也不会自动安装 Python 依赖或开通模型服务，这几项需要分别检查。
本案例采用 Python 3.11+、Agently 4.1.4.8、FastAPI 和 pytest；下载并安装 Agently-Skills 时还需要 Git、Node.js 与 npx。
二、项目与 Skills 配置
用 CodeBuddy 打开独立项目文件夹，让规格、用例和代码都保存在同一个项目中。讨论需求时可以使用规划模式，或明确要求"本轮只分析和整理文档"；进入实现时，再允许 Agent 修改代码和运行测试。
项目根目录
├── CODEBUDDY.md 项目工作约定，开始任务时明确要求 Agent 读取
├── .codebuddy/skills/ Agently-Skills 六项 + 随课方法 Skill spec-tdd-workflow
├── spec/behavior_spec.md 逐步形成的行为规格，区分已确认和待定内容
├── spec/test_cases.md 根据规格整理的测试用例、确认状态和检查方式
├── .env 业务模型凭据（不提交到版本库）
└── （业务代码与测试）| 项目中的位置 | 保存什么 |
|---|---|
CODEBUDDY.md | 项目工作约定，开始任务时明确要求 Agent 读取 |
.codebuddy/skills/ | Agently-Skills 和随课提供的方法 Skill |
spec/behavior_spec.md | 逐步形成的行为规格，区分已确认和待定内容 |
spec/test_cases.md | 根据规格整理的测试用例、确认状态和检查方式 |
规划阶段说明"只整理文档"，实现阶段再说明需要修改代码和运行测试。规划模式若仅输出方案，可以在确认后单独要求保存到指定文件。
Agently-Skills 套件
套件为 Coding Agent 提供 Agently 的使用指引。应用开发套件包含六项，排除 agently-migration 迁移部分；随课方法 Skill spec-tdd-workflow 另负责组织规格、用例和 TDD。
先在终端检查 git --version、node --version 和 npx --version。下面命令固定到与 Agently 4.1.4.8 对齐的套件版本，在自己的项目根目录执行：
npx -y skills add https://github.com/AgentEra/Agently-Skills/tree/ce3a5de74359b15159aab9a71fe18aebb60c49d5 --agent codebuddy --skill agently agently-design agently-request agently-runtime agently-stage agently-triggerflow --copy -y安装后，.codebuddy/skills/ 应包含下面六个目录，每个目录内都有 SKILL.md：
| Skill | 用途 |
|---|---|
| agently | 根据任务选择能力与实现方式 |
| agently-design | 设计和审查模型流程、职责与数据流 |
| agently-request | 配置模型请求、输入输出与结果消费 |
| agently-runtime | 接入运行资源、工具与服务 |
| agently-stage | 处理进程内任务生命周期与同步异步协作 |
| agently-triggerflow | 实现需要显式控制的应用工作流程 |
加上 spec-tdd-workflow，项目中共有七个 Skill。按任务读取相关指引即可，安装套件本身不会安装 Python 依赖或配置业务模型。
Python 环境与业务模型
本案例采用 Python 3.11+、Agently 4.1.4.8、FastAPI 和 pytest。使用 conda 时，可以为项目创建独立环境：
conda create -n vibe-live-chat python=3.11 -y
conda activate vibe-live-chat
python -m pip install "agently==4.1.4.8" fastapi uvicorn pytest httpx python-dotenv
python -c "import sys, agently, fastapi, pytest; print(sys.executable); print(sys.version); print(agently.__version__); print(agently.__file__)"CodeBuddy 的项目解释器与运行终端都选择这个环境。也可以使用 venv，保持 Python 和依赖版本一致。
CodeBuddy 的编码模型与应用运行时调用的业务模型分别配置。使用 DeepSeek 时，在项目根目录准备一份 .env.example 模板，再复制为 .env，填入自己的 API Key、服务地址和可用模型名称，并将 .env 加入 .gitignore。其他模型服务则调整相应配置映射。
项目工作约定模板（CODEBUDDY.md）
这份约定是项目级的，Agent 开始任务时应当先读取。它同样约束了后面的规格整理和 TDD 过程。
范围与依据
- 按用户当前任务推进，常规实现细节自主处理。先读相关 feature、行为规格和已确认用例，再修改相关文件。保留明确的范围限制。
- 业务规则未定且会改变用户结果或验收预期时，列出问题和选择后果。只暂停依赖该决定的部分，继续独立且已授权的工作。
测试与修正
- 新功能优先把已确认关键行为转成测试，小步实现并运行相关回归检查。现有问题先用失败、日志或静态证据确认，再处理根因。
- 业务预期未变时保留对应断言。测试组织可以改进；修改预期、删除断言或增加 skip 时，给出规格或证据依据，并单独说明测试差异。
- 核实实际解释器和依赖后运行检查。区分环境／收集失败和业务断言失败，区分已通过、失败、跳过与未运行。条件未变且无新证据时复用已有检查结果。
汇报与参考方法
- 短汇报保留：待定决定、改动范围、关键行为的影响、命令与结果、未验证内容。完整日志提供定位入口，避免用大量过程叙述掩盖失败。
- 按需使用项目
.codebuddy/skills/中的参考方法。Skill 描述处理步骤，业务正确性仍来自已确认规格与实际证据。
课堂示例为直播聊天分析应用：监听单个直播间，在自己的界面显示评论，选择时间范围后向 Agent 提问，由模型根据本次评论快照回答。采用 Python 3.11+、Agently 4.1.4.8 和配套 Agently-Skills 应用开发套件，排除 agently-migration。后端使用 FastAPI，测试使用 pytest。
程序负责采集、身份去重、时间过滤、快照与引用校验；模型负责理解评论、归纳主题与回答。发送时间缺失时保留未知，采集时间单独记录。抖音页面位置标识仅在当前页面会话内使用，不宣称平台消息 ID 或跨刷新可靠去重。
从已确认规格与用例推进实现。实际采集、数据回放与合成样本分别标识；模型替身不能证明真实模型效果。不自动回复观众、不管理直播间，不接入站外检索。第一版限定本地单用户，不扩展账号系统或多房间服务。
三、环境检查清单
环境检查包括下面几项：
- CodeBuddy 能读取当前项目约定，能在项目内保存文件。
- 终端使用预期的 Python 环境，能够导入依赖并运行测试工具。
- 项目中能找到 Agently-Skills 的六个应用开发 Skill，Agent 能读取对应文件。
- 用一条合成消息完成最小真实模型请求，确认配置可用；凭据保存在本地配置中。
可以按下面的指令检查运行条件：
本轮只检查项目环境和模型连接，不编写业务实现。
读取 CODEBUDDY.md，确认项目目录与文件读写能力。
检查实际 Python 解释器、Agently 版本与导入位置，以及服务和测试依赖。
检查 .codebuddy/skills 下的六项 Agently 应用套件和 spec-tdd-workflow，确认相关文件可读取。
检查业务模型配置，只报告变量是否存在，不输出凭据值。
使用已有授权配置发起一次最小真实请求，报告实际命令、结果和失败原因。
有环境或版本不一致时说明差异；分别列出实际通过的检查与仍未验证的内容。浏览器采集还需要确认：能读取当前聊天，能发现新消息，重复读取能识别同一条记录。Chrome 登录状态属于当前浏览器，CodeBuddy 需要单独接入或开发采集入口。
连接检查只能说明请求能够发出并返回。模型是否正确理解了聊天原文，仍要对照具体用例检查。
四、直播采集入口
选择一个可以正常访问的直播间，用 Chrome 打开。采集端读取页面已加载的评论，再观察新增消息；本机后端接收消息，自己的界面显示评论和采集状态。
页面 DOM 是浏览器当前呈现的内容。可见列表移除旧评论时，采集端需要保留已经取得的记录；页面未加载的历史消息不属于这一路径的采集范围。界面应明确显示开始、停止、失败或中断状态。
消息身份和时间字段取决于实际页面。可取得平台消息 ID 时，用它识别同一条消息；只能取得页面位置时，明确标注会话范围及刷新后的去重限制。发送时间缺失就保留未知，采集时间单独记录，时间筛选按已确认的口径执行。
Chrome 中已有登录状态，还需要开发或接入采集入口，应用才能获得评论。
采集与分析的消息约定
消息批次使用 schema_version、source、room_id 和 messages。每条消息包含 room_id、message_id、platform_message_id、identity_kind、sender、display_time、captured_at、text。
| 字段 | 含义与处理 |
|---|---|
room_id | 房间标识；后端以房间和 message_id 做导入幂等校验 |
message_id | 采集入口提供的标识 |
platform_message_id | 平台消息 ID，可以为空 |
identity_kind | 消息身份的来源类型；平台身份字段不足时可使用注明作用范围的采集标识 |
sender | 发送者（昵称） |
display_time | 页面显示的时间，可为空 |
captured_at | 观察（采集）时间 |
text | 评论原文 |
message_id 是采集入口提供的标识；platform_message_id 可以为空。平台身份字段不足时，可使用注明作用范围的采集标识；页面会话标识不代表跨刷新可靠身份。display_time 是页面显示的时间，可为空；captured_at 是观察时间。回放保留原始时间，不把加载文件的时间改成采集时间。
缺少房间、标识或文本的记录作为输入异常；发送时间缺失本身不是错误。时间筛选遇到 captured_at 为空时需提示无法归入时间范围，不能编造时间。
实时采集与 JSON 导入使用同一消息约定。界面标明实时数据或回放来源，分别检查采集、导入和分析过程。
3. Spec 与 SpecDD：思想和工作流程
Spec 是 Specification 的简称，可以理解为对软件预期行为的具体说明。它需要讲清楚：在什么场景下，接收什么输入，完成什么功能，产生什么结果，以及有哪些限制。
SpecDD（Spec-Driven Development，规格驱动开发，也常写作 SDD）的基本思路是：先把预期效果说清楚，再根据这些约定设计方案、编写代码和检查结果。
对于 Coding Agent，这份规格也是理解开发任务的依据。原来需要在对话中反复解释的要求，可以整理成一份双方都能查看和修改的文件。
3.1 Spec 的主要内容
写 Spec 时，可以先围绕"怎么用、做到什么程度"展开，再讨论实现方案。
| 需要说明的内容 | 直播聊天分析应用中的例子 |
|---|---|
| 场景与功能 | 使用者看到采集中的评论，选择范围后向 Agent 提问 |
| 输入与输出 | 输入所选评论与问题，输出分析回答及对应评论的引用 |
| 关键行为 | 同一条消息不重复保存；本次分析只使用已选定的消息集合 |
| 异常处理 | 没有评论时提示空范围；模型失败时保留问题和所选范围供重试 |
| 验收方式 | 选定时间段发起分析，核对传给模型的评论和回答引用是否属于该范围 |
"这段时间"还需要进一步解释。依据平台发送时间，还是采集器观察到消息的时间？页面没有提供发送时间时，不能把本机采集时间写成发送时间。首次读到的旧消息可能同时被采集，这也会影响时间范围的含义。
浏览器扩展、页面读取方式和模型配置属于实现方案。已有技术限制可以写进 Spec，具体实现方式再根据这些限制选择。
3.2 SpecDD 的工作流程
一轮规格驱动开发，可以按下面的过程推进：
- 讨论需求：明确用户、业务场景和功能范围。
- 形成规格：补充输入输出、关键行为、异常处理和验收条件。
- 确认规格：区分已经确定的内容和仍然需要讨论的问题。
- 安排实现：根据规格选择技术方案，拆分开发任务。
- 实现与验证：完成代码，检查实际效果是否符合规格。
规格驱动的一轮开发：每个阶段承接上一阶段的依据。发现关键歧义时，回到对应规则讨论；常规技术细节在已确认约束内自主处理。
规格和任务清单的作用不同。"增加消息导入接口"是一项开发任务，"同一条消息重复导入不增加记录"是一条行为要求。接口写完以后，还需要用这条要求检查它是否做对。
如果实现过程中发现规格有遗漏，就补充讨论对应的问题，再更新规格。Spec 需要能够继续指导开发，所以已经确认的修改也要写回文件。
3.3 Spec 的详细程度
规格的详细程度取决于当前任务。修改一个明确的字段校验规则，可能只需要几句话；开发一个包含持续采集和评论分析的新功能，就需要把输入输出、处理过程和异常情况写清楚。
可以用一个简单的问题检查：如果只根据这份 Spec 开发，哪些地方还需要靠猜？
影响业务效果的内容，尽量补充明确。例如，重复采集后是否会出现重复消息。常规实现细节可以让 Agent 选择，例如辅助函数叫什么名字、内部代码怎样拆分。这样，我们能把精力放在真正影响使用结果的决定上。
实操卡 D01：从一句话形成规格草稿
目标： 用一段自然语言需求，让 CodeBuddy 形成 Spec 草稿。
案例需求： 监听一个直播间，在自己的界面显示评论；一段时间后，使用者向 Agent 提问，由它根据所选评论回答。
发给 CodeBuddy：
我要做一个直播聊天分析应用，在本机监听一个直播间，并在自己的界面显示采集到的评论。
积累一段时间后，使用者选择分析范围，向自己的 Agent 提问，例如"这段时间大家最关心的问题是什么"，在同一界面得到回答。
先读取 CODEBUDDY.md；模型请求使用 Agently，相关用法参考 Agently-Skills。
本轮只整理 Spec 草稿，不写业务代码。写出开始监听、查看评论、停止监听、选择范围、提问和核对回答的连续过程。
说明消息身份、时间口径、采集范围、空数据、模型失败与重试，以及分析期间又有新评论到达时如何处理。
区分采集与去重、时间过滤等程序工作，和理解评论、归纳主题、回答问题等模型工作。
把功能、关键行为和验收条件写到 spec/behavior_spec.md，标明原需求、建议和待确认问题。
第一版只监听一个房间，是本地单人应用；不自动回复观众，不管理直播间，不检索站外资料，不声称拿到了完整历史。观察要点： Agent 补充了哪些原需求没有说的内容？这些建议是否符合业务场景？
4. Spec 生成过程中的关键难点
使用 Agent 的规划模式时，经常会一次得到很多内容：需求分析、架构设计、数据结构、接口定义、页面设计、开发任务等。
这些内容各有用途，但放在一起阅读时，很容易把注意力放在自己熟悉的技术细节上，漏掉真正需要确认的业务问题。审读 Spec 的重点，是找到会影响功能和使用结果的决定。
4.1 规划输出中的内容类型
比如，Agent 写了"只分析带问号的评论"。这条规则可能来自用户要求，也可能只是 Agent 为筛选消息提出的建议。审读时需要找到它的依据，再判断是否采用。
| 输出内容 | 需要检查什么 |
|---|---|
| 已确认需求 | 有没有准确保留原来的场景、功能和效果要求 |
| Agent 的假设或建议 | 是否合理，是否需要进一步讨论和确认 |
| 实现方案 | 能否满足规格，是否增加了不必要的功能和依赖 |
| 开发任务 | 是否覆盖了已确认要求，执行顺序是否合理 |
尤其需要注意那些写得很肯定、但从未讨论过的规则。Agent 可以帮助提出建议，采用哪一种规则还要结合实际场景判断。
4.2 Spec 的审读重点
可以先请 Agent 把下面四类信息单独整理出来：
- 场景与范围：给谁用，解决什么问题，这次做哪些功能。
- 关键行为：输入以后会发生什么，异常情况怎样处理。
- 待确认问题：哪些内容还只是建议，不同选择会有什么影响。
- 验收条件：通过什么操作、什么结果，判断功能已经做到。
以直播聊天分析应用为例，"这段时间按什么时间筛选""分析期间的新评论是否加入""没有足够评论时怎样回答"，都需要优先确认。页面配色和组件选择，可以在这些主要行为明确后继续调整。
整理摘要是为了帮助阅读。看到一个会影响结果的决定，仍然需要回到对应规则，检查它的条件和限制有没有被摘要省略。
4.3 围绕关键行为追问
追问尽量针对具体行为，让 Agent 给出可以判断的答案。
| 可以问的问题 | 主要解决什么问题 |
|---|---|
| 这条规则来自我提出的需求，还是你的建议？ | 分清原始要求和补充假设 |
| 举一个正常情况和一个异常情况，分别怎样处理？ | 把"合理处理""正确生成"等描述说具体 |
| 哪一步会保存记录或改变状态？由谁触发？ | 明确采集、分析和状态变化各自由谁触发 |
| 这次有哪些事情明确不做？ | 控制开发范围 |
| 做完以后，具体怎么检查这一项？ | 补充验收条件 |
比如"分析最近十分钟"还不够具体，可以继续问："页面没有发送时间时，按什么时间筛选？刚开始监听时读到的旧评论算在哪个范围？"这样就能从宽泛的要求，讨论到可以实现和检查的规则。
4.4 讨论结果与规格更新
讨论结束后，把已经采用的决定写回 Spec，仍未确定的内容继续标明待定。后续实现读取这份文件，就能知道哪些要求已经确定，哪些还需要讨论。
例如，讨论后确认了"评论保留原文""每次分析固定一批输入""回答只显示在自己的应用中"，就把这些决定写入规格。
"最关心"怎样判断，是另一个问题。可以根据所选评论中的重复主题做定性归纳，也可以按已定义的统计口径排序。按评论条数与按人数统计，结果可能不同；只有昵称时也不能可靠识别独立用户。选定口径后，再编写相关逻辑和测试。
针对案例，讨论阶段通常会把下面这些规则拎出来优先确认：
| 规则 | 讨论中的建议 | 要点 |
|---|---|---|
| 时间范围口径 | 按采集时间筛选，界面标明"采集时间"；发送时间缺失保留未知 | 首次加载的一批旧评论采集时间相近，不能说它们在同一时刻发送 |
| 区间边界 | 开始包含、结束不包含，程序执行精确过滤 | 边界口径需要在 Spec 中写明，否则测试预期无法确定 |
| 分析输入冻结 | 分析提交时冻结输入，新增评论留给下一次分析 | 提交之后到达的评论可以继续显示，但不自动混入已提交的分析 |
| "最关心"的口径 | 首版可按评论主题做定性归纳，并提供原文依据 | 若要热度数字或人数排名，需先确认指标与身份来源；计算由程序完成 |
| 输入过长 | 提示缩小范围，或在规格中另行明确分段策略 | 不能静默截断后声称分析了全部 |
把这些规则写进 Spec 之后，它们才能成为测试预期。只停留在对话里的决定，下一轮实现时很容易丢失。
实操卡 D02：审读规划输出，确认关键规则
目标： 从 D01 的输出中找到需要讨论的决定，确认后更新 Spec。
检查重点： 已有草稿是否准确表达了需求，哪些规则已经确定，哪些还需要讨论。
发给 CodeBuddy：
本轮只审查和更新 spec/behavior_spec.md，不进入测试代码或业务实现。
请把刚才的规划整理为四部分：场景与范围、关键行为、待确认问题、验收条件。
每条关键规则标明是原需求中的要求，还是你的建议。
重点检查：评论身份怎样确定、时间范围依据什么、分析输入何时固定、空范围与模型失败怎样反馈、回答怎样关联原评论。
对需要确认的规则给出具体例子，并说明不同选择会影响什么。
保留完整规格。根据我明确确认的决定更新文件，其他问题继续标为待定，暂不开始实现。观察要点： 哪些规则已经可以指导开发？还有哪些问题需要先做决定？
5. Test Case 与 TDD：思想和工作流程
Test Case 是测试用例，用来说明：在什么条件下，输入什么或进行什么操作，预期得到什么结果，以及怎样检查这个结果。
TDD（Test-Driven Development，测试驱动开发）则是一种开发方法：先为一项行为写测试，观察它失败，再编写实现让测试通过，然后整理代码并保持测试通过。
测试用例可以先用自然语言或表格表达，确认预期以后，再将适合自动检查的内容写成测试代码。测试由此参与开发过程，为每一步实现提供反馈。
5.1 从 Feature list 到 Test Case
Feature list 是功能清单，说明应用需要具备哪些能力。比如"监听和显示评论""选择分析范围""向 Agent 提问"。要形成测试用例，还需要继续讨论每个功能有哪些关键行为。
以"采集聊天"为例，能够读到新消息是一项行为；重复读取不产生重复记录、不同房间的消息不混在一起，也都属于需要处理的情况。
直播聊天分析应用的功能清单可以这样拆：
| 功能 | 输入与结果 | 关键行为 |
|---|---|---|
| F01 监听评论 | 直播页 → 消息批次 → 应用评论列表 | 开始、停止、采集状态；同一采集标识不重复保存 |
| F02 选择范围 | 已采集评论、开始与结束时间 → 分析快照 | 明确时间口径，展示条数；快照不随新消息变化 |
| F03 向 Agent 提问 | 问题和评论快照 → 回答及原文引用 | 基于本次输入，引用可核对，模型失败可重试 |
首版为本地、单用户、单房间。分析界面包含监听状态和评论列表、范围与提问区、回答及引用原文。不自动发回直播间，不管理观众，不检索站外资料，回答根据本次评论与提问产生。
从功能推导用例的过程，可以看 F01 的例子：
| 推导过程 | 具体内容 |
|---|---|
| 功能 | F01：采集聊天 |
| 需要固定的行为 | 同一房间、同一消息重复采集，只保留一条记录 |
| 前置条件与输入 | 已保存消息 M01，再导入包含 M01、M02 的批次 |
| 预期结果 | 总共保留两条消息，M01 原文和来源不变，只新增 M02 |
| 检查方法 | 检查消息数量、身份标识以及保存内容 |
这项检查可以使用固定消息数据，不需要调用模型。模型替身则用于稳定制造指定模型返回，例如让分析回答引用范围外的消息，检查程序能否拒绝无效关联。
5.2 关键行为与测试预期
固化用例时，需要把"希望它处理正确"进一步写成具体的预期，并确认这些预期来自已经讨论过的规则。
比如"不同观众发送相同文字，仍保留两条原消息"。可以把用例写成：准备两条文本相同、消息 ID 不同的消息，导入后检查原始消息列表有两条记录、各自的发送者保留。这些评论表达了什么主题，再由模型结合上下文理解。
| 用例需要包含的内容 | 作用 |
|---|---|
| 对应的功能和行为规则 | 说明为什么需要这个用例 |
| 前置条件、输入与操作 | 让测试可以重复执行 |
| 预期返回与状态变化 | 明确什么结果才算通过 |
| 不应发生的事情 | 检查重复保存、错误覆盖、额外调用等问题 |
一个功能通常会对应多个用例。先确认这些场景和预期，再让 Agent 编写测试，能减少它根据现有实现自行决定"什么算正确"的情况。
5.3 TDD 的红灯、绿灯与代码整理
TDD 用一个小循环推进实现：
- 红灯（Red）：写一条测试并运行，确认它因为目标行为尚未实现而失败。
- 绿灯（Green）：补充满足当前用例的最小实现，再运行测试确认通过。
- 代码整理（Refactor）：在行为不变的前提下改善代码组织，重新运行相关测试。
完成这一小步，再选择下一项已确认行为。环境或收集失败不能代替有效红灯；测试通过的结论保留实际覆盖范围。
例如，约定同一条消息不重复保存。测试连续导入相同消息，检查只保留一条；当前程序如果每次都直接追加，这条测试就会失败。补上消息身份检查后，再确认它通过。
可以先整理一份候选用例清单，再从中选择能够独立验证的一项。每完成一个小循环，继续下一项，并运行已有相关测试，检查新代码有没有影响已经完成的行为。
实操卡 D03：从功能和行为整理测试用例
目标： 根据已经确认的 Spec，形成可以逐项讨论的用例表。
检查重点： 用例要包含前置条件、操作、预期与检查方式，并对应到已确认行为。用例表需要审查，不代表测试已经执行。
发给 CodeBuddy：
读取 spec/behavior_spec.md 中已经确认的规则，本轮先整理测试用例。
根据功能清单和关键行为整理候选测试用例，标明每条用例对应的规则。
每项写清前置条件、输入与操作、预期结果、状态变化、不应发生的事情和检查方法。
重点考虑重复采集、不同 ID 的相同文本、时间范围边界、空范围、分析期间新增评论、范围外引用与模型失败。
区分使用模型替身的程序逻辑测试和需要真实模型参与的效果检查。
规则尚未确定的用例标为待定。先给出用例表和遗漏的情况，暂不编写测试代码或业务实现。
将候选表保存到 spec/test_cases.md，逐项标明待确认状态；根据我确认的预期更新状态，只有已确认用例进入实现。观察要点： 用例是否覆盖了我们希望固定的效果？预期结果是否与 Spec 一致？
用例确认： 候选用例需要经过审查，确认预期后才进入实现；确认状态也一并保存在文件中。
整理出来的候选表可以参考下面的结构（时间与消息标识均为合成测试数据）：
| ID / 功能 | 前置、输入与操作 | 候选预期 | 检查方式 |
|---|---|---|---|
| T01 / F01 | 同房间先导入 M01，再导入 M01、M02 | 共两条，M01 原文不变 | 程序测试 |
| T02 / F01 | 不同消息标识，发送者与文字相同 | 两条分别保留，不能按文本去重 | 程序测试 |
| T03 / F01 | 开始后出现新评论；停止后再出现一条 | 新增可见，停止后不继续收取；界面状态相符 | DOM 样本及真实页面分别验证 |
| T04 / F02 | 采集时间为 10:00、10:05、10:10；选择 [10:00,10:10) | 本次两条；边界口径待确认 | 程序测试 |
| T05 / F02 | 提交含 M01、M02 的分析后，又到达 M03 | 本次输入仍为两条；列表可显示三条 | 模型替身记录实际输入，再核对页面 |
| T06 / F02 | 选定范围没有评论 | 提示空范围，不调用模型，不展示旧回答为新结果 | 程序与页面 |
| T07 / F02 | 回放消息采集时间未知 | 提示无法纳入时间筛选，不补造发送或采集时间 | 程序测试 |
| T08 / F03 | 模型返回引用 M99，但输入只有 M01、M02 | 标记无效引用，不呈现为可信依据 | 模型替身与程序校验 |
| T09 / F03 | 模型超时；重试 | 显示失败，保留问题和原快照；重试仍使用已确认范围 | 程序测试 |
| T10 / F03 | 评论包含天气、交通、玩笑和否定表达 | 主题归纳有依据，不扩大为所有观众的意见 | 真实模型语义检查 |
| T11 / F03 | 修改范围后，上一次请求才返回 | 旧回答保留其原范围标记，不冒充新范围结果 | 延迟替身与页面操作 |
| T12 / F03 | 一次输入超过已约定容量 | 提示缩小范围，不静默省略评论 | 程序与页面 |
需要注意：抖音页面会话标识的跨刷新重复风险，不能通过 T01 就宣称解决。程序测试验证同一输入标识的幂等性；平台身份与完整性另有验收范围。
6. Test Case 与 TDD 过程中的关键难点
Agent 可以一次生成很多测试用例和测试代码，也可以给出很长的测试报告。我们需要判断：这些测试检查了哪些行为，预期是否正确，通过结果能说明什么。
尤其是在 AI 应用里，程序逻辑和模型效果需要分别考虑。同样一个"分析评论"功能，既涉及模型是否理解讨论，也涉及程序怎样筛选时间范围和固定输入。
6.1 用例的覆盖范围
先按功能查看对应的关键行为，再检查正常、边界、失败和重复操作是否有合适的用例。
例如，已经有十条"导入聊天，成功得到分析回答"的测试，仍然可能没有检查"重复导入是否增加记录"或"模型是否引用了不存在的消息"。这时补上失败场景，比继续增加相似的正常输入更有帮助。
| 审查用例时可以问 | 直播聊天分析应用中的例子 |
|---|---|
| 这条用例检查哪项关键行为？ | 本次分析不混入提交之后才到达的评论 |
| 预期结果从哪里来？ | 已确认的 Spec，或样本原文中的明确事实 |
| 哪些容易出错的情况还没有检查？ | 空范围、时间边界、无效引用、重复采集 |
| 检查结果是否完整？ | 返回成功之外，是否检查了保存数量和实际内容 |
测试中的"断言"，就是判断实际结果是否符合预期的检查语句。审查测试时，也要看断言是否真的检查了所讨论的行为。只检查状态码为成功，无法发现"关联了错误消息"的问题。
6.2 AI 应用的验证方式
程序约束、模型理解和使用流程，需要各自对应的检查。
| 检查内容 | 具体例子 | 可以怎样检查 |
|---|---|---|
| 输入范围 | 只传入所选房间与时间范围内的已采集评论 | 固定时间与记录，检查筛选结果和本次分析快照 |
| 输出结构与关联 | 回答引用的消息 ID 属于本次输入 | 使用字段校验和标识集合检查 |
| 消息语义 | 区分"爬长城很累吗"和"爬到一半能返回吗"，概括共同主题时保留差异 | 调用真实模型，对照原文和预先确定的评价标准 |
| 用户流程 | 页面明确显示本次范围、评论数量、提问与回答 | 检查接口状态，并实际操作页面 |
"大家在讨论长城游览安排"可以概括相关主题；"所有观众都认为长城太累"则加入了原文没有支持的结论。自由文本可以固定需要保留的含义，允许措辞变化。消息 ID、时间范围、输入条数和状态标签，则可以精确比较。
一次模型调用通过，只能说明这个样本在这次调用中符合要求。判断效果是否稳定，还需要更多有代表性的样本和重复运行，不能从一条成功结果推导所有输入都可靠。
6.3 红灯与绿灯的判断依据
红灯需要能对应到正在开发的行为。缺少依赖、模块无法导入、测试没有被运行，说明需要先解决运行条件，尚不能说明业务规则得到了检查。
如果测试第一次运行就通过，可以检查目标行为是否已经实现，或者断言是否漏掉了关键结果。已经满足的行为可以保留测试，继续下一项，不需要为了演示红灯故意改坏代码。
绿灯也需要结合测试方式判断。模型替身可以固定返回范围外的消息 ID，用来检查应用是否拒绝无效关联；真实模型是否准确概括了多条评论的共同主题，则要实际调用模型验证。两类检查分别回答不同的问题。
测试失败后，先对照 Spec 检查预期。预期正确，就修正实现；预期确实写错了，就说明依据并修正测试。为了通过而删除断言、跳过用例或迁就错误结果，会让原本需要检查的行为失去保障。
6.4 测试报告的阅读重点
先看失败项：哪条用例失败，预期是什么，实际是什么。再看关键行为有没有被检查，以及哪些内容仍未验证。
可以请 Agent 按下面四项汇报：
- 执行情况：实际运行了什么命令，在哪个环境中运行。
- 结果差异：失败用例对应哪条规则，预期和实际有什么区别。
- 测试改动：是否修改了期望、断言或跳过设置，修改理由是什么。
- 检查范围：哪些使用模型替身，哪些调用真实模型，哪些操作了实际页面。
"全部通过"需要结合这些内容阅读。例如，程序逻辑测试全部通过，但真实模型还没有调用，那么模型分析效果仍然需要验证。
实操卡 D04：观察一轮 TDD 的执行过程
目标： 选择一项已经确认的行为，观察测试怎样推动实现。
检查重点： 先观察目标行为导致的失败，再补实现、运行到通过并整理代码。汇报实际命令、预期与结果，以及尚未验证的内容。
发给 CodeBuddy：
读取 spec/behavior_spec.md 与 spec/test_cases.md，根据已确认用例进行 TDD 开发。
先选择"同一房间、同一消息重复采集不重复保存"这一项；若尚未确认，先列出需决定的预期。
建立最小可导入骨架，用带房间标识、采集消息标识、发送者、采集时间和原文的固定消息编写测试并实际运行。本项不调用模型。
确认失败是否来自目标行为。环境或导入有问题时，先修复运行条件。
观察到有效失败后，补充最小实现，运行到通过，再整理代码并运行相关测试。
如果首次运行已经通过，检查已有实现和断言，按实际情况说明，不故意制造失败。
本轮完成这一项后停下，汇报结果。继续下一项时，再处理已确认的"不同消息 ID 即使文本相同也分别保留"。
说明对应规则、预期、实际结果、运行命令和未验证内容。
业务预期不变时保留原断言；如需纠正测试，先说明对应的规格依据。观察要点： 失败是否对应目标行为？实现改了什么？通过以后，还不能确定哪些效果？
7. SpecDD 与 TDD 怎样配合
SpecDD 帮助明确要实现什么效果，Test Case 把这些效果写成具体的检查场景，TDD 再利用测试反馈逐步推进实现。
三者可以围绕同一条行为要求配合。规格中的约定成为测试预期，测试结果帮助判断实现是否满足约定；发现需求有歧义时，再回到规格中讨论。
7.1 同一条规则怎样贯穿开发
以"只根据选定范围内的评论回答"为例：
| 环节 | 具体做什么 |
|---|---|
| Spec | 明确时间口径；发起分析时固定本次评论集合，回答可以回看引用的原文 |
| Test Case | 准备范围内外的消息，以及提交分析后才到达的消息，写清各自是否属于本次输入 |
| 实现 | 程序筛选并保存分析快照，模型根据这批评论和提问生成回答，程序检查引用 |
| 验证 | 检查实际传入的评论；真实模型结果与原文对照；页面展示的范围与回答一致 |
同一条关键效果贯穿开发：规格含糊时讨论具体规则；预期明确时保留标准，修正实现、模型输入或验证环境。
模型负责理解与回答，程序负责范围、标识和状态。如果返回的是本次输入中的消息 ID，程序只能确认引用没有越界；这条评论是否真的支持回答，还需要语义检查。
如果问题是"大家最关心什么"，回答应说明依据是本次采集到的评论。评论中的讨论热度，不能直接推导整个直播间所有观众的真实想法。
7.2 根据验证结果继续推进
当测试失败时，先看具体差异，再判断需要修改哪里。实现不符合明确规则，就修改代码或模型请求；测试预期写错，就按规格修正；规格没有说清楚，就补充讨论。
自动化测试通过以后，还需要结合功能的实际使用方式检查。例如，页面已经切换到新的时间范围，却仍展示上一次分析的回答。实际修改范围再提问，检查范围、输入数量与回答的对应关系，就能发现这种问题。
验证结果按实际执行情况记录。已经检查的内容可以作为接受当前结果的依据，尚未执行的部分继续保留为待验证。
7.3 将方法整理为可复用的 Skill
前面的指令卡分别组织了规格讨论、规格审读、用例整理和测试驱动实现。把这些步骤及关键检查点保存下来，就可以在新项目中继续使用。
随课提供的简版 Skill spec-tdd-workflow，就是把这套方法整理成 Agent 可以读取的工作指引。
---
name: spec-tdd-workflow
description: 用于把应用需求整理为可确认的 Spec、从功能与关键行为形成测试用例，并用 TDD 小步实现和验证。
适合需求澄清、规格审读、用例固化、按测试开发或核对交付结果；按用户指定阶段执行，不因讨论需求就自动写代码。
---使用时，围绕四个问题整理思路：
| 需要想清楚的问题 | Skill 帮助组织的工作 |
|---|---|
| 要做什么？ | 从用户场景出发，整理功能范围和明确不做的事情 |
| 怎样才算做对？ | 补充关键行为、具体例子和验收条件，标明待确认问题 |
| 用什么验证？ | 根据已确认规则整理 Test Case，区分程序逻辑与模型效果检查 |
| 根据什么继续修改？ | 用 TDD 小步实现，根据预期与实际的差异定位问题，再核对实际效果 |
Skill 保存的是处理问题的方法，Spec 和 Test Case 保存的是当前项目的具体要求。换一个项目，方法仍然可以使用，业务规则和测试预期则要重新结合场景判断。
比如 Agent 提出"分析时自动加入最新到达的评论"，Skill 会要求它说明这条规则来自需求还是自己的建议，以及不同选择会影响什么。我们仍需要根据实际业务决定是否采用。进入实现后，Skill 会要求它实际运行测试，说明失败原因和检查范围，方便我们判断结果。
使用 Skill 时，仍需检查重要行为有没有遗漏、建议是否被当成要求、测试是否覆盖关键结果。它帮助组织工作，具体规格与验证结果仍需要结合业务判断。
Skill 内部的四个阶段
这份 Skill 按阶段组织工作，并要求在开始前先读取当前任务、项目约定、已有规格和相关用例；优先沿用现有文件及编号，新项目可使用 spec/behavior_spec.md 和 spec/test_cases.md，小任务也可合并为一份文件。只要求讨论、审查或整理用例时，完成对应产物即可；要求实现时，推进已明确且获授权的范围，无需为每个小步骤重新询问。会改变业务结果的未定项保留为问题，只暂停依赖它的部分。
阶段 1：整理 Spec——要做什么，怎样才算做对
- 明确使用者、实际场景、目标和本轮功能清单。用一条连续操作说明用户怎样开始、怎样获得反馈、怎样完成任务。
- 将功能写成可观察行为：输入与前置条件、预期输出、状态变化、必要的失败处理和不应发生的副作用。涉及接口时补充必要的输入输出约定。
- 对关键规则区分"已确认要求""建议""待定"，保留需求或用户决定的简短依据。原有约定冲突时说明冲突，不自行挑一条当已确认。
- 用具体例子检查含糊描述。例如"信息完整"需要说明缺少字段怎样表示、是否允许继续，而不是默认补齐事实。
- 技术方案与行为要求分开；保留已有技术限制，常规实现细节按项目选择。不为文档完整增加业务功能或复杂架构。
已有长规划时，先提炼场景与范围、关键行为、待确认问题、验收条件。只追问会改变范围、结果或测试预期的问题，并说明不同选择的影响。采用用户已确认的决定更新同一份 Spec，其他项继续标为待定。
阶段 2：固化 Test Case——用什么验证
从功能清单和已确认关键行为推导候选用例，覆盖相关的正常、边界、失败和重复操作。按行为重要性选择，合并没有增加覆盖的重复用例。
用例表至少包含：
| 用例 ID / 对应规则 | 前置条件、输入与操作 | 预期返回、状态与副作用 | 检查方式 / 状态 |
|---|
预期来自已确认规则和有依据的输入事实。规则未定就标为待定，不从当前代码或框架默认行为倒推正确答案。固化的是经过审查的预期；有明确业务变更或测试错误时可以修订，但说明依据与影响。
涉及 AI 应用时分开检查：
- 程序逻辑：字段结构、状态与保存规则可用确定性断言。模型替身用于稳定制造指定返回、错误或超时，不能证明真实模型效果。
- 模型效果：真实调用后对照原文检查事实、否定、条件、数量和诉求。确定字段可精确比较；自由文本固定事实与评价标准，允许不同措辞。一次通过只说明该次样本结果。
- 用户流程：接口通过之外，按相关实际操作检查输入、反馈、修改和最终保存结果。无法运行时保持待验证。
阶段 3：TDD——用测试反馈推进实现
仅在当前任务包含实现时执行。选一项已明确、可独立验证的行为，核实环境后建立最小可运行的测试入口。
- 红灯：先写测试并实际运行，确认目标行为导致断言失败。导入、依赖或测试收集错误先作为运行问题处理。首次已通过时检查已有实现和断言，按事实继续，不故意改坏代码制造红灯。
- 绿灯：补充满足当前行为的最小实现，重新运行到通过。不要通过删断言、跳过用例或迎合当前错误输出来获取绿灯。
- 整理：按需要改善代码组织，保持行为不变，再运行已有相关测试；随后推进下一项。
失败时比较预期与实际，定位规格歧义、测试错误、实现缺陷、环境问题或模型效果问题。预期明确就保留它并修正实现；预期确实有误则依据规格修正测试，说明原因。暂时无法定位时保留失败事实，不写成已解决。
阶段 4：核对实际效果与汇报
将已确认规则与用例、实际执行结果对应起来。AI 应用分别报告程序测试、真实模型检查和相关页面操作；未运行的部分明确标为未验证。需要修正时，只处理当前授权范围，再检查受影响的行为。
汇报保持简短：
- 本轮完成了什么，产物或修改在哪里。
- 需要用户决定什么，各选择会影响什么。
- 实际执行的命令或操作，关键预期与实际结果；注明真实调用或替身。
- 失败、跳过、未验证的内容，以及下一步。
按当前阶段汇报：规格阶段交规格与问题，用例阶段交候选用例和缺口，实现阶段再交实际执行结果。每项关键建议带上简短理由和具体例子，帮助用户审查；不生成虚构运行日志或未经执行的通过结论。
使用方式
指令卡 D01～D04 用普通指令展开方法；本节介绍方法 Skill，D05 明确读取并继续当前项目。之后可以按需要指定阶段：
请读取 .codebuddy/skills/spec-tdd-workflow/SKILL.md。
读取已有规格与测试用例。本轮只整理 Spec，标明建议和待确认问题，不写业务代码。需要实现时，可以改为："根据已确认规格和用例进入 TDD，先处理这一项行为。"新对话中指出 Skill、规格和用例的位置，并说明当前进度。
| 当前任务 | 产物 |
|---|---|
| 整理与审读规格 | 功能、关键行为、验收条件与待确认问题 |
| 固化用例 | 对应已确认规则的输入、预期、检查方式和确认状态 |
| TDD 实现 | 实际测试反馈、最小实现及相关复测结果 |
| 核对效果 | 程序、模型和页面检查的结果与未验证项 |
将方法 Skill 放入项目后，明确要求 Agent 读取对应 SKILL.md，并指定本轮任务。整理规格时使用规格阶段，按已确认用例开发时使用 TDD 阶段。
两类 Skills 可以配合使用：spec-tdd-workflow 帮助组织规格、用例和验证过程；Agently-Skills 帮助落实 AI 应用的框架用法。业务规则和验收预期仍然保存在项目自己的 Spec 与 Test Case 中。方法 Skill 为本课编写，需在项目中安装；它与 CodeBuddy 的内置功能分别配置。读取了 Skill 仍需要检查实际产物和执行结果。
实操卡 D05：从规格到实际使用效果
目标： 接通聊天监听，在自己的界面显示评论，再针对一段时间内的评论向 Agent 提问。
使用 Skill： 首次明确调用 spec-tdd-workflow，沿用已有规格、用例和实现。对照实际执行结果，检查采集、时间范围、模型分析和页面展示是否满足规格。
发给 CodeBuddy：
请读取 .codebuddy/skills/spec-tdd-workflow/SKILL.md，使用它继续本项目。
读取 spec/behavior_spec.md、spec/test_cases.md 和当前实现，沿用已确认决定；Agently 用法按需查套件。
按 TDD 补齐最小流程：监听一个直播间、在自有界面显示评论、选择时间范围、提问和展示 Agent 回答。
采集读取 Chrome 中当前直播页，首次读取已加载评论，再观察新增；提供开始、停止、状态和导出入口。
消息批次接入本机后端，并在自有界面显示原文、发送者、采集时间和监听状态。
按平台实际可用的身份字段处理重复采集；没有平台消息 ID 时，说明页面会话标识及刷新后的去重限制。
界面区分发送时间与采集时间。没有发送时间就保留未知，范围筛选使用 Spec 已确认的时间口径。
程序负责时间过滤与分析快照；分析开始后到达的新评论继续显示，但不自动混入已提交的分析。
模型读取本次评论快照和使用者提问，理解讨论并给出有原评论依据的回答，不检索站外资料，不自动发送聊天。
先处理"这段时间大家最关心的问题是什么"，展示本次范围、输入条数、回答与引用原文；数量统计由程序计算。
空范围不调用模型。模型失败保留提问与范围供重试；输入过长时明确提示缩小范围，不静默丢弃评论。
前端调用真实后端，验证评论到达、停止采集、范围选择、提问、回答与原文对应关系。
分别报告程序测试、真实模型、采集监听和页面操作的结果；区分实时采集与数据回放，未运行的部分保持待验证。观察要点： 页面显示的分析范围、实际传给模型的评论、回答所引用的原文，是否始终对应同一批数据？
8. SpecDD 和 TDD 对 Coding Agent 开发的价值
Coding Agent 可以承担需求整理、方案探索、代码生成和测试执行等工作。开发者需要结合业务场景确认目标，并根据实际结果判断是否达到了预期。
SpecDD 与 TDD 为这个过程提供了具体的工作方法：
- 明确场景和功能：把想法整理成可以讨论、可以确认的开发要求。
- 固化关键效果：把重要行为写成规格和用例，减少仅凭印象判断的情况。
- 让开发过程有反馈：通过测试发现预期与实现的差异，帮助 Agent 继续修正。
- 让结果可以检查：对应规格、测试和实际使用效果，知道哪些已经做到，哪些还没有验证。
规格和测试也需要人来审查。规格写错，可能让 Agent 很认真地实现了错误需求；用例遗漏，也可能在全部通过后留下问题。因此，人的判断仍然集中在业务场景、关键行为和验收标准上，Agent 则可以帮助完成大量整理、实现和验证工作。