使用 Agent 模式建置您的第一個應用程式
本指南是該系列的總結演練，將涵蓋的所有內容串聯起來。你將從零開始使用「代理優先開發」（agent-first development）建構一個網址縮短器，並使用 FastAPI 作為 API、Python 的 sqlite3 作為資料庫、簡單的 HTML 前端，以及本系列稍早提到的 base62 編碼器。
你將會看到模型選擇器、規劃代理、自動駕駛、檔案變更檢視、工作階段分歧以及代理除錯日誌如何共同運作。
選擇合適的模型
對於跨越多個檔案的專案（包含資料庫結構、API 路由、前端以及它們之間的整合），請將思考強度（Thinking effort）設為「高」。模型在編寫程式碼之前，會更深入地思考各個部分如何相互配合。
開啟一個新的聊天工作階段，點擊模型選擇器，並將思考強度設為「高」。
使用規劃代理（Plan agent）進行規劃
對於包含多個動態部分的專案，請從使用規劃代理開始。它會強制代理在編寫程式碼之前，先產出一份結構化的大綱並提出設計問題。
切換到規劃代理，並使用如下詳細的提示詞：
Build a URL shortener with FastAPI, Python's built-in sqlite3, and a simple HTML frontend served by FastAPI StaticFiles. Use uv for project management with Python 3.13. Use the existing base62 encoder in main.py to generate short codes from the database row ID. The API needs two endpoints. POST /shorten accepts a JSON body with a url field and returns the short code. GET /{code} redirects to the original URL. The frontend is a single index.html with a form to submit URLs and a section that displays the shortened link. Keep it minimal.
此提示詞指明了框架、資料庫方法、確切的端點、專案管理工具，並引用了現有的程式碼。具體的提示詞能為規劃代理提供明確的界限。
審閱規劃
預期規劃會將工作拆分為多個階段，例如使用 uv 進行專案設定、將 base62 編碼器提取到獨立模組中、建構 sqlite3 資料庫層、串接 API 端點、建立 HTML 前端以及驗證。
它還可能在「進一步考量」部分提出設計問題，例如是否保留 CLI、重複的網址是否應獲得相同的縮短碼，以及在縮短前是否需驗證網址。在開始實作之前，請直接解決這些問題。
直接回答問題，例如：
Drop the CLI, we don't need it anymore. New short code each time and yes add URL validation.
三個明確的答案，沒有歧義。在編寫任何程式碼之前，先解決設計問題。
移交給代理模式（Agent mode）
審閱規劃後，你可以選擇以下三種選項之一。
| 選項 | 功能說明 |
|---|---|
| 開始實作 | 以預設核准模式開始建構。 |
| 使用自動駕駛開始 | 以自動駕駛模式開始建構。 |
| 在編輯器中開啟 | 將規劃儲存為檔案以供手動參考。 |
對於已經過審閱、範圍明確的規劃，自動駕駛通常是正確的選擇。
觀察自動駕駛（Autopilot）運作
即使在自動駕駛模式下，每一個動作都會在聊天面板中顯示為工具呼叫。
典型的建構順序如下所示。
- 建立待辦事項清單以追蹤進度。
- 執行
uv add fastapi uvicorn[standard]來安裝依賴項。 - 將
main.py更名為base62.py，並僅保留編碼與解碼邏輯。 - 同時建立
database.py、app.py、static/index.html以及.gitignore。 - 在背景啟動伺服器。
- 執行驗證指令碼來測試端點的端對端功能。
自動駕駛在多步驟設定期間表現出色，因為代理可以在不中斷核准的情況下安裝依賴項、建立檔案、啟動服務並驗證結果。驗證步驟非常重要。強大的代理執行過程不會止步於寫入檔案，它會在標記任務完成前，完成應用程式的端對端驗證。
檢查上下文視窗（Context window）
在工作階段中途開啟上下文視窗指標，並與早期的單檔案工作階段進行比較。
- 系統（工具定義與指令）保持大致不變。
- 隨著規劃訊息、工具結果與伺服器日誌的累積，使用者上下文會逐漸增加。
如果預算已滿，執行 /compact 來總結對話歷史，或是開啟一個新的工作階段並引用前一個工作階段以取得上下文。
審閱已變更的檔案
建構完成後，「已變更的檔案」列會顯示代理建立或修改的每一個檔案。
仔細審閱每個檔案。
base62.py：已從原始檔案中乾淨地提取出編碼與解碼邏輯。app.py：包含POST /shorten、GET /{code}與GET /的 FastAPI 應用程式。database.py：用於儲存與查詢網址的sqlite3輔助工具。static/index.html：表單、結果區塊與 JavaScript。
使用箭頭控制項來瀏覽編輯內容。在需要時撤銷個別變更，或在一切看起來正確時選擇全部保留 (Keep All)。
對運作中的應用程式進行迭代
一旦核心應用程式運作正常，請使用針對性的後續提示詞進行迭代。
Add a lookup section to the frontend and a GET /lookup/{code} endpoint that returns the original URL as JSON instead of redirecting. The frontend should have a second form where I paste a short code and see the original URL displayed below it.
代理應該只更新相關檔案，而不是重建整個專案。
使用分歧（Forking）來進行不同的方向探索
在加入查詢功能後，在探索測試套件之前，先對工作階段進行分歧 (Fork)。
在分歧的工作階段中使用類似這樣的提示詞：
Add a test suite using pytest. Test the base62 encode/decode functions and the API endpoints including /lookup/{code}, using FastAPI TestClient. Use uv to add pytest and httpx as dev dependencies.
原始工作階段在「代理工作階段 (Agent Sessions)」側邊欄中保持不變。這形成了兩個分支：一個用於功能開發，另一個用於測試。
在實務上，這是分歧功能的強力應用。它將關注點分開：一個對話分支進行功能開發，另一個進行測試，且兩者皆從相同的已知良好檢查點開始。
讀取代理除錯日誌（Agent Debug Logs）
自動駕駛執行完畢後，開啟代理除錯日誌。
- 日誌檢視畫面會顯示事件順序、自訂載入、LLM 請求、工具呼叫、終端指令、並行檔案建立以及驗證過程。
- 摘要檢視會顯示模型回合、工具呼叫、Token 與事件的總數。
- 「代理流程圖」將工作階段的結構視覺化。
分歧後擁有了兩個工作階段，你可以並排比較它們的日誌。
你也可以附加一個除錯快照並直接提問，例如：#debugEventsSnapshot 這個工作階段進行了多少次工具呼叫？
你建構的成果
你透過代理優先開發模式建構了一個可運作的網址縮短器。
- 針對多檔案專案使用具備高思考強度的模型選擇器。
- 使用規劃代理在編碼前規劃架構。
- 使用自動駕駛在不中斷的情況下建構應用程式。
- 使用代理除錯日誌來檢查發生的狀況。
- 使用上下文視窗指標來監控預算。
- 使用「已變更的檔案」檢視來審閱並接受編輯內容。
- 使用後續提示詞來擴充應用程式。
- 透過分歧功能建立測試套件分支，而不遺失現有功能開發成果。
你的挑戰
建構我們在本系列中完成的網址縮短器，利用我們使用過的提示詞（或自行發想！），然後對其進行擴充。
點子
- 自訂縮網址後綴，讓使用者可以選擇自己的短碼。
- 設定過期日期，自動停用舊連結。
- 建立一個分析頁面，依據點擊次數顯示熱門網址。
使用規劃代理來定義工作範圍，使用代理模式來進行建構，並檢查你的代理除錯日誌以了解代理的執行動作。
完成後，開啟上下文視窗指標並查看工作階段統計數據，以了解開發過程如何影響你的上下文預算。
這就是代理優先開發的基礎。載體、模型、上下文、工具、提示詞。五件事，協同運作。練習得越多，你的成果就越好。
敬請期待後續介紹 MCP、自訂指令與技能，以及更進階代理模式的內容。祝編碼愉快！