学习 Cue · 基于任务的教程

将口述缺陷报告转化为编程 Agent 任务简报

在发现问题之处直接描述它。使用 Cue 捕获可见症状，然后为编程 Agent 提供足够的复现和检查修复上下文，而无需主观臆测原因。

作者： Cue 产品团队 (English) · 更新于 。基于产品源审查编写。练习与输出仅供示意，并非录制的 Cue 实际运行记录。请以您安装版本中显示的控件为准。

如何为编程 Agent 提供一份实用的口述缺陷报告？

在受影响应用处于可见状态时使用 Cue 描述问题。将该描述转化为复现步骤、预期与观察到的行为、已知条件以及验收检查项。审查任务简报，然后明确将其移交至正确代码库中配置好的 Claude Code 或 Codex 任务。

需求： 具体的症状和初始状态；仅在后续移交时才需要配置好的编码工具。 结果： 一份可复现的报告和界定明确的任务，而非臆断的根本原因或已经验证的修复方案。

捕获您实际观察到的内容

“布局坏了”这种描述会让下一个人不得不自行重构您的现场情况。一份实用的语音报告应保留页面、操作、可见结果和条件。Cue 让您能在相关应用呈现在眼前时立即开始阐述；最终有价值的产出是一份可复现的简报，而非对代码自以为是的猜测。

  1. 保持受影响的页面或应用状态可见。在已知情况下记下 URL 或屏幕名称、应用版本、操作系统和浏览器。未掌握的细节应标为未知，切勿从先前的报告中照搬借用。
  2. 如果您希望将口述内容直接插入 issue 草稿，请聚焦其文本字段并使用 Cue Dictation。如果您需要一份结构化报告，请使用 Cue Agent 并明确指明相关屏幕或提供简短描述。
  3. 按顺序记录步骤，包括初始状态。区分“我看到过一次”与“我复现了三次”。如果您确实对照检查过正常状态，请注明该对比情况。
  4. 请求生成报告草稿。在目标项目、证据和范围明确之前，切勿授权修改代码库。

可见的屏幕上下文并不包含隐藏的浏览器日志、源代码或每一个标签页。如果屏幕截图有用，请捕获真实状态，去除隐私信息并审慎附加。在任务中亲眼看到附件之前，不要声称附件已存在。本教程不含任何产品截图或录制的测试运行记录。

实践：在不猜测原因的情况下描述失真的预览图

此虚构报告针对一个一次性示例网站，并非对当前 Cue 网站的陈述。其尺寸和复现次数均为练习设定事实；并未针对本示例在浏览器中进行实际测量。

源 B-01： 在示例站点的视频预览页面上，提供的图像尺寸为 1600 × 900 像素。在 390 像素的视口宽度下，打开预览会使图像看起来被纵向拉伸变形。在 1280 像素宽度下，同一图像显示比例正常。练习报告显示，窄视口下的异常行为出现了 3 次。浏览器版本、操作系统及受影响的代码路径未知。要求的修复仅限视觉表现；文本和下载行为必须保持不变。

提供 B-01 并向 Cue 提问：

将 B-01 转化为包含“摘要”、“环境”、“复现步骤”、“预期结果”、“观察结果”、“未知项”和“验收检查”的缺陷报告草稿。将客观观察与可能原因严格分开。不要捏造 CSS 选择器、文件路径、屏幕截图、根本原因或测试结果。包含 390 像素和 1280 像素两种情况。将工作范围限定在预览的纵横比和溢出问题上。仅生成草稿；不要提交 issue 或编辑代码。

示意性任务简报，非录制的 Cue 实际结果：

摘要： 在 390 像素视口下，视频预览呈现纵向拉伸变形。
环境： 示例网站；浏览器版本与操作系统未知。
步骤： 打开预览页面，将视口宽度设置为 390 像素，展示所提供的 1600 × 900 图像，并检查其比例。在 1280 像素下重复该操作。
预期： 在两种宽度下，预览均保留图像的 16:9 比例，且不会出现页面级水平溢出。
在 B-01 中观察到的现象： 报告称在 390 像素下尝试 3 次均出现拉伸变形；在 1280 像素下比例正常。
未知： 相关组件、CSS 规则及根本原因。
范围： 仅限视觉预览；保持文本、定价和下载行为不变。
验收检查:在 390 像素下，渲染的预览画面与 16:9 源比例的误差保持在 1% 以内，且页面无横向溢出；在 1280 像素下两者同样成立；下载链接、价格文本和预览说明文字与变更前保持字节级完全一致；覆盖这两个宽度的浏览器检查在修复前失败、在修复后通过。

1600 × 900 的源图像宽高比为 16:9。这一计算结果是有益的核验参考，但不能作为渲染尺寸的证据。在选择修复方案之前，请要求编程 Agent 检查实际图像和布局。“可能是 flexbox 问题”仅在有确凿证据时方可列入假设，绝不能当作已确认的成因。

交付前校对步骤与验收检查

口述生成的报告即便内容有误，读起来往往依然通顺。在转录中最容易受损的内容，恰恰是编码 Agent 最依赖的要素：步骤顺序、各项数值，以及你所观察到的现象与推导结论之间的区别。在将草稿交给他人成为任务前，务必对照原始事实回读核对。这只需花一分钟，却能省去含糊报告后续带来的一来一回沟通。

重现步骤

  • 每步只对应一个操作，并按实际执行顺序排列。“在 390 像素下打开预览页面并检查图片”实际上是两个步骤，它掩盖了究竟是哪一步出现问题。应拆分为两步。
  • 明确说明初始状态。是已登录还是未登录、何种账户类型、处于哪个页面、事先已打开了什么。如果某个重现过程只能在你的特定起始环境生效，那它就不是可重现的。
  • 提供精确数值，而非形容词。写 390 像素，而不是“狭窄窗口”；写 1600 × 900，而不是“大尺寸图片”；写尝试 3 次，而不是“通常如此”。请对照原始依据逐一检查每个数字，因为口述的数字最容易出现偏差。
  • 未知信息保持未知。若未记录浏览器版本，草稿必须写明未知，而非直接套用上一份报告里的版本。校对草稿时应专门找出那些凭空出现、没有事实来源的内容。
  • 确保其他人也能照着执行。请像从未见过这个缺陷一样来阅读这些步骤。凡是需要你额外开口询问的地方，都是遗漏的步骤。

验收检查

  • 不在场的人也能进行观察核验。“预览看起来正常”不是合格的检查项。“渲染出的预览保持了 16:9 的源比例，且页面在 390 像素与 1280 像素下均未出现横向溢出”才是合格的。
  • 与报告的症状紧密绑定。每项检查在当前状态下都应因你报告的该项原因而失败。如果某项检查已经通过，它就无法证实该缺陷已得到解决。
  • 至少包含一项反向（负向）检查。明确指明哪些内容绝不能变动——如下载链接、价格文本、说明文字。范围损伤（误伤周边）是小型修复中常见的失效模式，只要你没要求检查，它往往就隐蔽不显。
  • 明确指出什么才算作证据。实际运行某项检查的输出、发生变更的文件、对比截图。一句声称修复有效的断言不是证据，通过了无关组件的测试也不是证据。
  • 不要为了获得绿灯通过的结果而放宽检查条件。如果某项检查无法满足，那说明修复方案本身存在问题，而不是重写修改验收要求的理由。

针对同一项 B-01 步骤的两个版本，以便看出具体差别。薄弱版本：“我把窗口调小，预览看起来被拉伸了，可能是 flexbox 的问题。”这把视口尺寸、操作过程以及对原因的猜测混为一谈，给 Agent 的是一个待证实的假设，而非一个待重现的缺陷。经核对版本：“将视口设置为 390 像素。打开预览页面。展示所提供的 1600 × 900 图片。观察结果：图片高度超出了其 16:9 的源比例。重复测试 3 次。原因未知。”第二个版本可以被重现并证伪；第一个版本则无法做到。

如果是口述生成的报告，请直接阅读插入的文本本身，不要轻信自己对刚才说话内容的记忆——颠倒的数字或是漏掉的“不”字，在通顺的句子里往往极难被察觉。标识符和版本号值得逐字符对照源材料核对，而不是对照你本想说的内容。

明确将任务简报移交给 Claude Code 或 Codex

最简单的途径是经人工审查后的文本移交。在目标代码库中打开已配置的 Claude Code 或 Codex 任务并粘贴报告，或在其提示词字段中口述简短的后续要求。这属于向另一个工具进行语音输入，并不证明存在原生集成或共享会话。

途径 实际操作内容 能确立的事实 不能确立的事实
直接口述至对应工具自身的输入框中 聚焦 Claude Code 或 Codex 的提示词输入框，使用 Cue Dictation 控制，提交前仔细阅读插入的文本。 你的话语已送达该工具的输入框。适合简短追问的最快途径。 无法证明文本经过了审核检查。语音直接输入未经校对，这对标识符和数字来说是最容易出错的状态。
粘贴已完成校对的简报 在 Cue 中起草，按上述标准校对，复制内容，然后粘贴到对应的 Claude Code 或 Codex 任务中。 接收任务端获得了完全经你批准的文本。本练习采用的就是这一途径。 无法证明 Cue 与该工具之间存在任何连接集成。这是你手动执行的数据转移。
在 Cue 中配置外部 Agent 在 Cue 中选择已配置好的外部 Agent，并先检查其设置、登录状态与权限许可。 仅能确定你的自身配置和该服务商账户实际允许的范围。 列表中看到 Claude、Codex 或 Gemini 并不代表已建立连接、完成授权、具备可用模型或成功运行。计费与可用性遵循实际配置的途径，而非界面列表。

本练习采用上述手动文本移交方式；它既不需要也不展示配置好的外部 Agent 连接器。如果您改为从 Cue 的 Agent 选择器中使用外部 Agent，请先检查该连接器的设置、登录状态和权限。为 Cue 自身的 Agent 选择模型与选择 Claude Code 或 Codex 运行时是两回事。可用性与计费取决于配置的路径。使用这些途径前，请先阅读 Agent、模型与上下文指南，不要假定它们可以互换。

任务： 在选定的网站代码库中调查所附的 B-01 报告。
第一步： 检查当前更改并保留无关工作。定位真实的预览实现。复现该症状并说明目前仍未知的细节。
然后，若获得授权： 添加针对 390 和 1280 像素下图像比例及溢出情况的浏览器回归检查，确认其能够针对观察到的缺陷报错，并进行最小程度的相关修复。
边界： 请勿更改文本、定价、下载、生产环境设置或无关组件。除非获得单独授权，否则请勿提交代码、创建 issue 或进行部署。
返回内容： 限定范围内的 diff、实际运行的命令、其执行结果以及任何仍存在的不确定性。

不同的 Agent 不会自动接收上一个任务的历史记录、文件或权限。请包含简报以及您获得授权共享的具体源文件或截图。代码库文件应来自所选项目，而非语音提示中猜测的路径。凭据、会话令牌和无关的客户记录绝不能出现在复现信息中。

Anthropic 的 Claude Code 最佳实践 建议为 Agent 提供验证其工作的方法。在此，具体的验收检查项远比让它“把页面改好”更有价值。该指引并不代表已安装 Cue 连接器，也不证明本练习已被实际执行。

审查修复结果，而不仅是解释说明

  • 前置确认： Agent 是否在正确的项目中复现了所报告的行为？如果没有，它应当返回其尝试过的操作，并索取缺失的环境信息。
  • Diff 与测试： 检查修改过的文件和实际的测试输出。建议运行的命令并不等同于实际运行过的命令；无关组件的测试通过（绿色）不能算作回归检查。
  • 视觉结果： 在两种宽度下对比真实的预览效果。验证其是否保持了原始纵横比且未产生页面级横向滚动。不仅要检查外层卡片，还要检查图像本身。
  • 范围： 确认没有更改任何无关的文案、价格或下载行为。如果补丁涉及共享的布局规则，也请检查引用该规则的其他组件。
  • 发布： 区分本地修改、已提交的代码、已合并的更改以及已部署的页面。在获得授权部署后，在公开页面上验证相同的场景。

对于本次编写练习而言，成功意味着报告具备可复现性并且如实陈述了未知项。完成实际修复则需要上述独立的代码库和浏览器检查。切勿将本示意性报告作为真实客户故障公开发布。

当 Agent 无法安全完成任务时

Agent 无法复现该缺陷

一次补充一项缺失的事实：确切页面、视口、浏览器版本、初始状态或经过脱敏的真实截图。询问它具体测试了什么。切勿仅仅为了获得通过（绿色）结果而放宽验收标准。

拟议的修复更改了无关的行为

暂停工作并指出工作范围边界。要求提供更精简的补丁或对依赖关系作出解释。在采取进一步行动之前审查当前的 diff；停止任务并不等于撤销（undo）操作。

重试可能会重复执行部分操作

先检查代码库、issue 草稿或部署状态。仅继续执行未完成的部分。新任务应当接收一份简短且经核实的现状摘要，而非盲目重复所有操作的指令。

如需提供更丰富的背景信息，请先将您的 会议纪要转化为链接到源的操作项，然后仅附加与此缺陷相关的决策和约束条件。如果报告基于屏幕上已有的文本起草，在信任草稿前，请务必核对 Agent 实际接收到的内容。

使用 Cue 亲自尝试

使用您配置的快捷键，并在 Cue Settings 中核实当前处于活动状态的模式。可用的应用上下文和操作取决于权限、版本和账户。在提供机密材料之前，请阅读 隐私政策 (English) ；本指南不保证所有数据处理均保留在您的设备本地。

获取适用于您电脑的 Cue · 当前方案 (English)

需要帮助或发现了错误？ 联系 Cue 支持 (English) 或发送电子邮件至 eli@sophoninc.com。请在来信中包含您的 Cue 版本、平台、模式以及脱敏后的示例。切勿发送密码、令牌或私密会议资料。