學習 Cue · 任務導向教學

將口述錯誤回報轉換為編程 Agent 任務簡報

在看見問題之處描述問題。使用 Cue 擷取可見的症狀，然後提供編程 Agent 足夠的上下文以重現並驗證修復，而無需胡亂猜測原因。

作者： Cue 產品團隊 (English) · 更新於 。根據產品來源審查撰寫。練習與輸出僅供說明，並非錄製的 Cue 執行紀錄。請依照您安裝版本中顯示的控制項操作。

如何向編程 Agent 提供有用的口述錯誤回報？

在受影響的應用程式清晰可見時使用 Cue 描述問題。將該描述轉化為重現步驟、預期與觀察到的行為、已知條件以及驗收檢查。審查簡報，然後明確將其轉交至您在正確儲存庫中設定的 Claude Code 或 Codex 任務。

需求： 具體的症狀與初始狀態；後續的交接才需要設定好的編程工具。 成果： 可重現的回報與有明確界限的任務，而非假定的根本原因或已驗證的修復。

擷取您實際能觀察到的內容

「版面跑版了」會讓接手的人必須自行重構您的情境。一份有用的語音回報會保留頁面、操作、可見結果與條件。Cue 讓您在眼前開啟相關應用程式時開始說明；有價值的產出是可重現的簡報，而非語氣篤定的程式碼推測。

  1. 保持受影響的頁面或應用程式狀態可見。在已知情況下記下 URL 或畫面名稱、應用程式版本、作業系統與瀏覽器。將無法取得的詳細資訊標記為未知，而不是從先前的報告中套用。
  2. 如果您想將口述內容直接插入問題草稿中，請將焦點移至其文字欄位並使用 Cue Dictation。如果您需要結構化報告，請使用 Cue Agent 並明確標明相關畫面或提供簡短描述。
  3. 按順序記錄步驟，包括初始狀態。明確區分「我見過一次」與「我重現了三次」。如果您實際進行過比對，請註明能正常運作的對照組。
  4. 要求產生回報草稿。在目標專案、佐證與範圍明確之前，請勿授權儲存庫編輯。

可見畫面上下文不包括隱藏的瀏覽器記錄、原始碼或每個分頁。如果螢幕截圖有所幫助，請擷取真實狀態，移除私人資訊並謹慎附加。在任務中親眼看見附件之前，請勿宣稱附件已存在。本教學不含產品螢幕截圖或錄製的測試執行。

練習：描述扭曲的預覽畫面而不猜測原因

這份虛構報告涉及一個一次性的範例網站，並非針對目前 Cue 網站的陳述。其尺寸與重現次數皆為練習事實；並未在瀏覽器中針對此範例進行實際測量。

來源 B-01： 在範例網站的影片預覽頁面上，提供的圖片尺寸為 1600 乘 900 像素。在視埠寬度為 390 像素時，開啟預覽會使圖片看起來被垂直拉長。在 1280 像素寬時，同一張圖片比例正常。練習報告指出窄螢幕視圖在三次嘗試中均出現異常。瀏覽器版本、作業系統與受影響的程式碼路徑皆未知。要求的修復僅限視覺效果；文字與下載行為必須保持不變。

提供 B-01 並向 Cue 提出要求：

將 B-01 轉化為包含摘要、環境、重現步驟、預期結果、觀察結果、未知項目與驗收檢查的錯誤回報草稿。保持觀察結果與可能原因分開。不要捏造 CSS 選擇器、檔案路徑、螢幕截圖、根本原因或測試結果。納入 390 像素與 1280 像素的情況。將工作範圍限定在預覽的顯示比例與溢位問題。僅產出草稿；不要提交 issue 或編輯程式碼。

說明性簡報，非錄製的 Cue 結果：

摘要： 影片預覽在 390 像素視埠下呈現垂直拉伸。
環境： 範例網站；瀏覽器版本與作業系統未知。
步驟： 開啟預覽頁面，將視埠寬度設定為 390 像素，顯示提供的 1600 × 900 圖片，並檢查其比例。在 1280 像素下重複此操作。
預期： 在這兩種寬度下，預覽均保留圖片的 16:9 比例，且不產生頁面層級的水平溢位。
B-01 中觀察到的現象： 在 390 像素下回報的三次嘗試中皆呈現拉伸；在 1280 像素下比例正常。
未知： 相關組件、CSS 規則與根本原因。
範圍： 僅限視覺預覽；保持文字、定價與下載行為不變。
驗收檢查:在 390 像素下，渲染後的預覽與原始 16:9 比例誤差在百分之一以內，且頁面回報無水平溢出；在 1280 像素下，兩者同樣維持成立；下載連結、價格文字與預覽說明與變更前完全一致（逐字節相符）；涵蓋這兩種寬度的瀏覽器檢查在修正前失敗，在修正後通過。

1600 × 900 的來源寬高比為 16:9。這項算術運算是很有用的核對方式，但並非算繪尺寸的證明。在選擇修復方案之前，要求編程 Agent 檢查實際的圖片與排版。「可能是 flexbox 問題」只有在有證據佐證時才能列在假設中，不能列在已確認的原因中。

在交接前校對步驟與驗收檢查

口述回報即使內容有誤，讀起來往往依然流暢。在傳遞過程中最容易受損的部分，恰恰是寫程式 Agent 所依賴的核心：步驟順序、數值，以及你親眼所見與主觀推論之間的差異。在草稿變成別人的任務之前，請對照原始事實重新審視。這只需花費一分鐘，卻能消除因回報模糊而衍生的大多數反覆溝通。

重現步驟

  • 每個步驟僅包含一個操作，並依執行順序排列。「在 390 像素下開啟預覽頁面並檢查圖片」是兩個步驟，這會掩蓋究竟是哪一步失敗。請將它們分開。
  • 明確指名初始狀態。已登入或已登出、哪種帳號類型、哪個頁面、先前已開啟了什麼。只有在你的特定起始條件下才能運作的重現過程，並不具備可重現性。
  • 使用確切數值，而非形容詞。是 390 像素，不是「狹窄的視窗」；是 1600 × 900，不是「大圖」；是嘗試三次，不是「通常」。請對照原始事實檢查每個數字，因為口述的數字最容易遺漏或出錯。
  • 未知事項維持未知。如果未記錄瀏覽器版本，草稿必須標註為未知，而不是挪用上一份回報的版本。校對草稿時，請特別挑出那些缺乏依據便憑空出現的事實。
  • 確保其他人也能跟著操作。請以從未見過該錯誤的視角閱讀這些步驟。任何你需要開口詢問的地方，都代表遺漏了步驟。

驗收檢查

  • 不在現場的人也能客觀觀察。「預覽看起來正常」不是合格的檢查。「渲染後的預覽在 390 與 1280 像素下均維持 16:9 的原始比例，且頁面回報無水平溢出」才是合格的檢查。
  • 緊扣回報的症狀。每一項檢查今天都應當因為你回報的原因而失敗。一項目前就已經通過的檢查，無法證明任何關於此缺陷的修復情況。
  • 至少包含一項反向檢查。明確指出什麼絕對不能改變——下載連結、價格文字、圖片說明。影響範圍擴大是微小修正中最常見的失敗模式，除非你要求對其進行檢查，否則往往難以察覺。
  • 明確指出何者可算作證據。實際執行檢查的輸出結果、變更的檔案、對比的螢幕截圖。單純一句聲稱修正有效的文字並非證據，無關元件的測試通過同樣不是證據。
  • 切勿為了獲得通過結果而放寬檢查標準。如果某項檢查無法通過，那是關於修正本身的具體資訊，而不是重寫需求的藉口。

同一個 B-01 步驟提供兩種版本，差異便一目了然。不佳：「我把視窗縮小，預覽看起來被拉伸了，可能是 flexbox 的問題。」這把視區大小、操作以及對原因的猜測混雜在一起，提供給 Agent 的是待證實的假設，而非待重現的缺陷。校對後：「將視區設定為 390 像素。開啟預覽頁面。顯示所提供的 1600 × 900 圖片。觀察結果：圖片高度超出其 16:9 的原始比例。重複三次。原因未知。」第二個版本可以被重現與證偽；第一個版本則不行。

如果你是以口述方式完成回報，請閱讀輸入的文字本身，切勿盲目相信自己說過什麼——數字顛倒或遺漏「不」字，在流暢的句子中都很難單憑記憶察覺。識別碼與版本號值得逐字元對照原始資料核對，而不是對照你原本想說的內容。

明確將簡報交給 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 像素下的圖片比例與溢位新增瀏覽器迴歸檢查，確認其在觀察到的缺陷下會失敗，並進行最小幅度的相關修復。
界限： 請勿變更文字、定價、下載、正式環境設定或無關的組件。除非另行獲得授權，否則請勿提交 commit、提交 issue 或進行部署。
傳回： 限縮範圍後的 diff、實際執行的指令、其結果以及任何剩餘的不確定性。

不同的 Agent 不會自動接收先前任務的歷史紀錄、檔案或權限。請附上簡報以及您獲准分享的特定來源或螢幕截圖。儲存庫檔案應來自選定的專案，而非語音提示中猜測的路徑。憑證、工作階段權杖和無關的客戶記錄均不應出現在重現步驟中。

Anthropic 的 Claude Code 最佳實踐 建議提供 Agent 檢查其工作成果的方法。在此處，具體的驗收檢查比要求它「讓頁面更好」更有用。該指引並不能證明已安裝 Cue 連接器或此練習已經實際執行。

審查修復成果，而非僅僅是說明

  • 事前： Agent 是否在正確的專案中重現了回報的行為？如果沒有，它應該傳回它嘗試過的內容並詢問缺失的環境資訊。
  • Diff 與測試： 檢查變更的檔案與實際的測試輸出。建議的指令不等於已執行的指令；無關組件測試通過不等於通過迴歸檢查。
  • 視覺成果： 比較真實預覽在兩種寬度下的表現。確認其保留了來源寬高比，且不會產生頁面層級的水平捲動。請檢查圖片本身，而不只是其外部卡片。
  • 範圍： 確認無關的文案、價格或下載行為均未變更。如果修補程式涉及共用的版面規則，請一併檢查使用該規則的其他部分。
  • 發佈： 請區分本機編輯、已提交的程式碼、已合併的變更與已部署的頁面。在獲得授權的部署完成後，於公開頁面上驗證相同的情境。

對於撰寫練習而言，成功意味著報告具有可重現性並誠實交代其未知之處。完成實際的修復需要上述獨立的儲存庫與瀏覽器檢查。請勿將說明性的報告當作真實的客戶事件發佈。

當 Agent 無法安全完成工作時

Agent 無法重現錯誤

一次新增一項缺失的事實：確切的頁面、視埠、瀏覽器版本、初始狀態或遮蔽處理後的真實螢幕截圖。詢問它測試了什麼。切勿僅為了獲得綠燈通過的結果而放寬驗收條件。

提議的修復變更了不相關的行為

暫停工作並指出範圍界限。要求提供範圍更小的修補程式或對相依性的說明。在採取進一步行動之前審查目前的 diff；停止任務並非還原操作。

重試可能會重複部分操作

先檢查儲存庫、問題草稿或部署狀態。僅繼續執行未完成的部分。新任務應接收簡短且經核對的狀態摘要，而非盲目重複所有事情的指示。

若要提供更豐富的背景資訊，請先將您的 會議記錄轉化為連結來源的行動項，然後僅附加與此錯誤相關的決策與限制條件。如果回報內容源自螢幕上已有的文字，在信任該草稿之前，請先檢查 Agent 實際接收到了什麼。

使用 Cue 親自嘗試

使用您設定的快速鍵，並在 Cue Settings 中確認使用中的模式。可用的應用程式上下文與操作取決於權限、版本與帳號。在提供機密資料前請閱讀 隱私權政策 (English) ；本指南不保證所有處理都會保留在您的裝置上。

取得適用於您電腦的 Cue · 目前方案 (English)

需要協助或發現錯誤？ 聯絡 Cue 支援團隊 (English) 或傳送電子郵件至 eli@sophoninc.com。請附上您的 Cue 版本、平台、模式與遮蔽處理後的範例。請勿傳送密碼、權杖或不公開的會議內容。