Flutter

【文章翻譯】Jaime’s build context: Prompt engineering as infrastructure

【文章內容使用 Gemini 2.5 Flash 自動翻譯產生】

總結

在代理式人工智慧時代，專案規模擴展的瓶頸已從程式碼量轉移到程式碼完整性。若要在人工智慧所允許的速度下前進，同時不引入系統性摩擦，我們必須停止將人工智慧視為魔杖，而應將其視為需要完美校準軌道的高效能引擎。

  • 縮小差距：工程團隊正在分裂——一端是傳統主義者，另一端是高速的代理式超級使用者。對於生產應用程式，您的基礎架構必須連接兩者，創建一個共享空間，讓傳統的嚴謹性和代理式速度不僅共存，而且積極地相互強化。
  • 傾向於可重現的系統：代理程式的好壞取決於其回饋迴路。如果您的測試不可重現，並且您的 CI 缺乏高訊號回饋迴路，那麼您的代理程式將會盲目運行。
  • 將提示視為基礎架構：停止將您最好的 AI 指令視為當會話結束時就會消失的臨時聊天一次性內容。相反，將這些自動化工作流程指令移到版本控制檔案中，將您的個人部落知識轉化為可執行文件，確保每個團隊成員都能在整個專案中可靠地觸發相同的高完整性結果。
  • 轉向基於技能的架構：成功意味著將您經過驗證的工作流程晉升為共享技能。透過從單個提示轉向專案範圍的技能，您為整個團隊提供了一個標準的、高完整性的劇本，代理程式可以自動執行。

最近，我一直在反思，對於新一批貢獻者來說，擴展開源專案的真正意義是什麼。我們正在進入一個代理式人工智慧可以如此快速地生成程式碼的時代，以至於純粹的數量不再是瓶頸；相反，真正的挑戰是確保這種湧入不會損害我們的程式碼庫，或我們作為隊友的共同價值觀。許多團隊正在分裂成啞鈴形狀：一端是傳統的手動編碼，另一端是高速的代理式超級使用者。

對於大型應用程式來說，我們的基礎設施必須作為連接這兩個極端的手柄，創造一個共享空間，讓傳統的嚴謹性和代理式速度不僅共存，而且積極地相互強化。為了有效擴展，我們必須透過將我們的工作流程建立在可重現軟體開發的基礎上來堅持基礎。為了在這些工具允許的速度下前進，而不會陷入技術債務或難以閱讀的程式碼庫，我們的環境必須提供明確、高訊號的回饋迴路。

在這種代理式情境下，原始碼健康狀況嚴格以通過測試、確定性覆蓋率指標和乾淨的分析來衡量。如果缺少這些基本要素，就像要求高效能引擎在黑暗中以極快的速度行駛一樣。如果環境尚未準備好，感覺需要抵制這些新工具是完全合理且通常是負責任的。

這裡的目標不是為了速度而將工具強加於專案；而是建立數位感測器，使我們能夠安全地採用新的速度。更重要的是，這種轉變是關於讓我們的隊友一起參與。基礎設施不應該是將「AI 超級使用者」與團隊其他成員分開的障礙；它應該是我們所有人都感到自信的共同點。在代理式時代成為一名好隊友意味著確保儘管我們的儲存庫可能移動得更快，但我們的文化仍然支持。我們建立這些系統是為了讓每個人都能自信地前進，確保「代理式速度」對整個團隊來說都是一項勝利，而不僅僅是現有功能軟體產品的新風險。

然而，這些數位感測器的可靠性取決於它們所處的環境。這就是為什麼我們必須將信任建立在 CI 系統中。在真正可重現的工作流程中，CI 是唯一重要的現實版本；它是缺乏人類直覺的代理程式的最終仲裁者。如果變更未能通過自動化閘門，它實際上就不存在。透過將 CI 視為高訊號回饋迴路，我們消除了手動驗證的人為瓶頸，並將其替換為可重現的閘門。這種絕對的真相來源使我們能夠更負責任地擴展——使代理程式能夠快速失敗、迭代，並最終成功，而不會損害專案的完整性或團隊的安心。

請求

一次性的提示成功只是僥倖。真正的規模化來自於創造一個飛輪：每次您或隊友回到儲存庫時，代理程式都應該比上次更有能力，因為知識債務已預付到共享的提示儲存庫中。您正在建立一個不會被困在單一開發人員腦中的共享機構記憶。

為了讓您團隊中的任何開發人員都能重複使用此功能，您需要一個提示指令函式庫，充當可執行文件。雖然許多團隊急於創建全域「config」和「rules」檔案，但我發現這些通常會導致結果不一致——代理程式可能會「忘記」規則或將其錯誤地應用於錯誤的情境。作為具有科學頭腦的工程師，我們應該更喜歡消除變數。透過控制特定任務的確切提示，您可以確保代理程式擁有該特定任務在您的儲存庫中所需的確切內容。以有意的方式在專案中這樣做有助於個人和團隊對這些新工具建立真正的信心。

進入代理技能

2025 年末，Anthropic 推出了 Agent Skills ——一個開放標準，旨在為 AI 代理提供專業的模組化專業知識。技能不僅僅是通用工具，它還將指令和資源打包在一起，以確保複雜任務的一致執行。這正在迅速發展；截至 2026 年初，許多工具已經開始支援此標準，以實現跨平台可移植性。

  • 彈性：您可以將技能與許多代理程式搭配使用，包括 Antigravity、Cursor、Claude Code Gemini CLI 和 VS Code，因為它們是 開放標準。
  • 共享知識：技能可以輕鬆地與協作者共享，或儲存到使用者資料夾中以供跨專案使用。
  • 可重複的工作流程：技能透過清晰的程序步驟指導代理程式，確保代理程式一致地執行複雜的多步驟任務。
  • 其他資源：技能可以包含腳本、範本或除了指令之外的其他資料。
  • 即時存取：當技能首次載入時，只有中繼資料會載入到代理程式的上下文中。這意味著只有在需要時才會將特定指令添加到上下文中，從而節省了令牌。
  • 維護程式碼品質：這些技能的建構可以用作一組工具，幫助貢獻者獲得正確的上下文，以根據您的最佳實踐組合出更高品質的 PR、測試和文件。

當前支援技能的主要工具文件

請參閱您的工具文件以了解在哪裡添加這些檔案。

有效技能的構成

為了確保您的技能函式庫仍然是「機器人的操作手冊」，而不僅僅是建議清單，此集合中的每個提示都遵循一套嚴格的最佳實踐：

  • 已知良好狀態：在代理程式接觸任何程式碼之前，它必須驗證現有的測試是否通過且分析器是否乾淨。如果基礎破裂，代理程式會在其上構建之前修復基礎。
  • 可操作的驗證：將指令錨定在 flutter test --coverage 或 dart fix --apply 等命令中，以向代理程式提供自我修正所需的確定性回饋。
  • 有限的範圍設定：為了確保代理程式保持高度的上下文和專注，提示的設計具有明確的界限——針對特定函數、檔案或覆蓋率差距。這確保代理程式專注於單一目標，防止範圍蔓延並確保輸出易於審查。
  • 報告和審查迴路：代理程式的工作以結構化摘要結束，而不是提交。透過要求代理程式解釋其變更並提供建議的提交訊息，而不是實際推送程式碼，我們將人類工程師保留在最終決策者的角色中。

範例技能：準備當前工作以供 PR

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
---
name: pr-prep
description: Prepare current work for PR
---
## 準備當前工作以供 PR：驗證測試通過並清理

**目標：** 使用 `flutter test` 驗證當前測試套件狀態，清理任何臨時修改，並加強活動檔案的測試覆蓋率。

**指令：**
1.  **基準：**
    *   執行 `dart fix --apply` 以應用自動修復。
    *   執行 `flutter analyze` 以確保沒有分析問題。
    *   執行 `flutter test` 以建立當前通過狀態。
    *   執行 `flutter test integration_test/app_test.dart` 以驗證整合完整性。
2.  **修復失敗：** 如果有任何測試失敗或分析錯誤，請調查並解決它們。優先修復程式碼而不是刪除測試。
3.  **清理：** 審查任何當前修改的檔案（執行 `git status` 或檢查差異）。移除任何：
    *   `print` / `debugPrint` 語句。
    *   未使用的導入。
    *   註釋掉的程式碼塊。
    *   應替換為正確解決方案的臨時「駭客」修復。
4.  **驗證和擴展：**
    *   對於您修改或清理的檔案，檢查其單元測試是否缺少明顯的邊緣情況。添加測試以涵蓋這些情況。
    *   再次執行 `flutter analyze` 以確保程式碼乾淨。
    *   再次執行 `flutter test` 以確保清理沒有破壞任何東西。
    *   根據需要重複此步驟。
5.  **報告和審查：**
    *   總結清理狀態（例如，「測試通過，已移除 3 個 debug print」）。
    *   **行動：** 要求使用者仔細審查變更，以確保沒有意外刪除預期的程式碼。
    *   **不要提交或推送。**
    *   提供建議的 Git 提交訊息（例如，「準備 PR：修復測試並移除 debug 程式碼」）。

範例技能：單檔測試覆蓋率

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
---
name: single-file-test-coverage
description: Write a new test or modify an existing test
---
## 單檔測試覆蓋率改進

**目標：** 撰寫新的單一測試檔案，或修改現有檔案，以改善特定目標類別的覆蓋率。

**指令：**
1.  **識別目標：** 選擇 `lib/` 中具有低或無測試覆蓋率且適合單元測試的單一原始碼檔案 (Dart)（例如，實用程式類別、邏輯輔助函數）。
3.  **建立基準：**
    *   執行 `flutter analyze` 以確保有效性。
    *   執行 `flutter test` 以確保專案穩定。
    *   執行 `flutter test --coverage` 並檢查 `coverage/lcov.info`。
4.  **實作/更新測試：** 在 `test/` 中建立新的測試檔案或更新現有檔案。專注於：
    *   邊緣情況（空輸入、空字串、邊界值）。
    *   分支覆蓋率（確保 if/else 路徑已執行）。
    *   必要時模擬依賴項（使用 `mockito` 或 `mocktail`）。
5.  **驗證與迭代：**
    *   執行測試以確保它們通過。
    *   執行 `flutter analyze` 以確保沒有回歸。
    *   如果覆蓋率仍然很低，**請迭代幾次**：分析遺漏的行/分支並添加有針對性的測試案例。
5.  **報告與審查：**
    *   總結已修復/覆蓋的內容並報告覆蓋率進度（例如，`X% -> Y%` for `<filename>`）。
    *   **行動：** 要求使用者仔細審查新的測試。
    *   **不要提交或推送。**
    *   提供建議的 Git 提交訊息（例如，「改進 [類別名稱] 的測試覆蓋率」）。

範例技能：遷移到現代 Dart 功能

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
---
name: migrate-to-modern-dart-features
description: Migrate to modern Dart features (Dart 3+)
---
## 遷移到現代 Dart 功能

**目標：** 透過遷移到現代 Dart 功能（Dart 3+）來優化一致性和簡潔性。

**可遷移的候選者：**
*   `if-else` 鏈 -> `switch` 表達式。
*   具有手動 `==`/`hashCode` 的資料類別 -> `Records` 或 `equatable`（或類別修飾符）。
*   空檢查 -> 模式匹配。

**指令：**
1.  **基準：** 執行 `flutter test` 和 `flutter analyze`。
2.  **選擇目標：** 識別 *單一* 遷移機會。
3.  **限制：** 將變更保持極小（**最多 50 行**）。
4.  **遷移：** 重構以使用新功能。
5.  **驗證：**
    *   執行 `flutter analyze`。
    *   執行 `flutter test` 以確保沒有回歸。
6.  **報告和審查：**
    *   總結遷移。
    *   **行動：** 要求使用者仔細審查變更。
    *   **測試位置：** 明確說明使用者應該去應用程式中的哪個位置手動測試變更（例如，「應用程式打開後點擊底部按鈕」）。
    *   **不要提交或推送。**
    *   提供建議的 Git 提交訊息（例如，「重構：在 [類別名稱] 中使用 switch 表達式」）。

總結

代理時代的長遠目標不在於您今天產生的程式碼量；而在於負責任地設計明日儲存庫的基礎設施和文化期望。透過建立啞鈴的把手，確保我們的工具運行速度更快時，它們仍然植根於我們共同的價值觀和技術嚴謹性。

在不久的將來，代理將從反應式助理轉變為主動貢獻者——在您睡覺時檢查您的儲存庫並解決問題。透過強化您的高訊號回饋迴路並在版本控制的技能套件中記錄您的工作流程，您不僅節省了時間；您還在訓練未來的代理程式尊重您的特定架構、願景和標準。最重要的是，您正在確保隨著開發引擎的加速，您的整個團隊都擁有數位感測器和共享知識，可以帶著集體信心和更強大、更有彈性的工程文化向前邁進。

Jaime 的建構上下文：提示工程即基礎設施 最初發佈在 Flutter 上的 Medium，人們在那裡透過突出顯示和回應這個故事來繼續討論。