翻譯 ｜ 一套完整的 AI 程式設計助手工作流程

credit: https://www.youtube.com/watch?v=SS5DYx6mPw8

這篇指南整理了一套可重複使用的結構化流程，教你怎麼和 AI 程式設計助手配合寫出生產等級的程式碼。文中會以用 Python 搭建 Supabase MCP 伺服器為例，但這套方法論適用於任何 AI 輔助開發的場景。

1. 黃金法則

先說幾條核心原則，後面的全域規則和提示詞都是圍繞它們展開的：

• 用 Markdown 檔案管理專案（README.md、PLANNING.md、TASK.md）。
• 單一檔案不超過 500 行，太大就拆成模組。
• 對話別拉太長，上下文一多品質就下降，記得及時開新對話。
• 別在一則訊息裡塞太多事，一次一個任務效果最好。
• 早測試、勤測試，每個新函式都配上單元測試。
• 提問要具體，給的上下文越多，AI 的回答越可靠。附上範例更好。
• 文件和註解隨手寫，別想著「回頭再補」。
• 環境變數自己設定。API 金鑰別交給 LLM，千萬別。

2. 規劃與任務管理

動手寫程式之前，先和 LLM 聊聊，把專案的大致範圍和任務理清楚。整體規劃寫進 PLANNING.md，具體任務記在 TASK.md。專案推進過程中，讓 AI 助手持續更新這兩個檔案。

PLANNING.md

• 用途：記錄專案願景、架構設計、技術選型、限制條件等高層資訊。
• 提示詞範例：「參照 PLANNING.md 裡的架構和決策來寫程式碼。」
• 每次開新對話都先讓 LLM 讀一遍這個檔案。

TASK.md

• 用途：追蹤目前任務、待辦事項和子任務。
• 內容包括：目前進行中的工作清單、里程碑，以及過程中發現的問題。
• 提示詞範例：「更新 TASK.md，把 XYZ 標為完成，再加一條新任務 ABC。」
• 也可以在全域規則裡讓 LLM 自動維護任務清單。

3. 全域規則（AI IDE 設定）

全域規則是讓 AI 助手遵守黃金法則最有效的方式。全域規則對所有專案生效，專案規則只作用於目前的工作區。主流 AI IDE 都支援這兩種規則：

• Cursor：https://docs.cursor.com/context/rules-for-ai
• Windsurf：https://docs.windsurf.com/windsurf/cascade/memories
• Cline：https://docs.cline.bot/prompting/prompt-engineering-guide
• Roo Code：設定方式和 Cline 一樣

下面是一套範例規則（以 Supabase MCP 伺服器為例），可以直接拿來當模板：

專案感知與上下文

• 每次新對話都先讀 PLANNING.md，了解專案的架構、目標、程式碼風格和限制。
• 開始新任務前先看 TASK.md，如果目前的任務沒記錄，就加一條簡要描述和日期。
• 嚴格遵循 PLANNING.md 中的命名規範、目錄結構和架構模式。

程式碼結構與模組化

• 任何檔案都不要超過 500 行。 快到上限了就拆成子模組。
• 依功能或職責把程式碼組織成獨立模組。
• 匯入語句保持清晰一致，套件內優先用相對匯入。

測試與可靠性

• 每個新功能都要寫 Pytest 單元測試（函式、類別、路由等）。
• 改了商業邏輯之後，檢查現有測試是否需要同步更新。
• 測試放在 /tests 目錄下，目錄結構與主程式碼保持一致。
  • 每個功能至少涵蓋：
    • 1 個正常案例
    • 1 個邊界情況
    • 1 個異常情況

任務完成

• 做完一個任務就立刻在 TASK.md 裡標記完成。
• 開發過程中發現的新問題或子任務，記到 TASK.md 的「過程中發現」一欄。

程式碼風格與慣例

• 主要語言用 Python。

• 遵循 PEP8，用型別註記，用 black 格式化。

• 資料驗證用 pydantic。

• API 用 FastAPI，ORM 用 SQLAlchemy 或 SQLModel（視需求選擇）。

• 每個函式都寫 docstring，採用 Google 風格：

  def example():
      """
      简要说明。
  
      Args:
          param1 (type): 参数描述。
  
      Returns:
          type: 返回值描述。
      """
  

文件與可讀性

• 加了新功能、改了相依套件或設定流程時，同步更新 README.md。
• 為不直觀的程式碼加註解，確保中階開發者能看懂。
• 遇到複雜邏輯，用 # 原因： 行內註解說明為什麼這麼寫，而不只是描述做了什麼。

AI 行為準則

• 拿不準就問，不要自己腦補缺少的上下文。
• 不要編造不存在的函式庫或函式——只用經過驗證的 Python 套件。
• 引用檔案路徑或模組名稱之前，先確認它真的存在。
• 不要擅自刪除或覆蓋既有程式碼，除非我明確要求或者它在 TASK.md 的任務裡。

4. 設定 MCP

MCP 能讓 AI 助手直接和外部服務互動，例如：

• 操作檔案系統（讀寫、重構、跨檔案編輯）
• 用 Brave 搜尋網頁（查文件特別好用）
• 操作 Git（切分支、看 diff、提交程式碼）
• 接入記憶儲存等其他工具（例如 Qdrant）

想找更多 MCP 伺服器？網路上有彙整了大量 MCP 伺服器的清單，附安裝說明。

各 IDE 的 MCP 設定文件：

• Cursor：https://docs.cursor.com/context/model-context-protocol
• Windsurf：https://docs.windsurf.com/windsurf/cascade/mcp
• Cline：https://docs.cline.bot/mcp/mcp-overview
• Roo Code：https://docs.roocode.com/features/mcp/using-mcp-in-roo

搭配 Git MCP 的提示詞範例：

现在代码状态不错，帮我 git commit 保存一下。

5. 專案的第一條提示詞

開局的第一條提示詞至關重要。哪怕 PLANNING.md 寫得再詳細、TASK.md 整理得再清楚、全域規則設定得再完善，第一條提示依然要盡可能具體——告訴 LLM 你要做什麼，以及可以參考哪些文件。

具體到你的專案會有所不同，但最好的做法是：給一個類似的參考範例。bolt.new、v0、Archon 裡那些效果最好的提示詞，無一例外都附帶了範例。如果你用到了特定的工具、框架或 API，通常還需要額外提供相關文件。

提供參考資料有三種方式：

1. 用 AI IDE 內建的文件索引功能。例如在 Windsurf 裡輸入 @mcp 再按 Tab，就是在告訴它去搜 MCP 文件。
2. 讓 LLM 透過 Brave 等 MCP 伺服器自行上網找。例如：「幫我搜一下其他 Python MCP 伺服器的實作方式。」
3. 直接在提示詞裡貼上範例程式碼或文件片段。

以建立 Supabase MCP 伺服器為例的起手提示詞：

参考 @docs:model-context-protocol-docs 和 @docs:supabase-docs，用 Python + FastMCP 写一个与 Supabase 数据库交互的 MCP 服务器。传输方式用 Stdio，需要支持以下操作：

- 读取表中的行
- 创建记录（支持单条和批量）
- 更新记录（支持单条和批量）
- 删除记录（支持单条和批量）

每个工具的描述要写清楚，让 LLM 能准确判断什么时候该用哪个工具。
环境变量需要 Supabase 项目 URL 和 Service Role Key。

先读一下这个 README 了解 Python MCP SDK 的用法：
https://github.com/modelcontextprotocol/python-sdk/tree/main

写完之后更新 README.md 和 TASK.md。

對了，對話拉長了記得及時開新的。如果你發現 LLM 開始讓你抓狂，那就是該重開的訊號了。

6. 後續開發：一次只做一件事

初始提示之後的修改和迭代，盡量一次只給一個任務，除非是很簡單的改動。雖然一口氣丟一堆需求給 LLM 很誘人，但任務越聚焦，輸出品質越穩定。

好的提示詞：

给“列出记录”的函数加一个过滤参数。

不好的提示詞：

给列出记录加个过滤功能。另外创建记录那个函数报错说找不到 API Key。还有，README.md 里关于怎么用这个服务器的文档写得太简单了，帮我补充一下。

想要穩定的輸出，關鍵是讓 LLM 每次盡量只改一個檔案。

改完之後別忘了讓 LLM 同步更新 README.md、PLANNING.md 和 TASK.md。

7. 每個功能都要測

可以在全域規則裡要求 LLM 實作功能後自動寫測試，也可以自己手動跟一步「幫我寫個測試」。盡早發現 bug 能避免問題滾雪球，這一步非常重要。

寫單元測試確實有點煩，LLM 寫的測試也不總是完美的，但盡量讓它把每個功能都涵蓋到。真的卡在某個測試上推不動了，跳過也行——先保住主流程。

測試的幾個最佳實踐：

• 測試檔案統一放在 tests/ 目錄下。
• 對資料庫、LLM 等外部服務的呼叫一律用 mock，不要真的去請求。
• 每個函式至少涵蓋：一個正常情境、一個預期內的失敗（驗證錯誤處理）、一個邊界情況。

8. Docker 部署（以 Supabase MCP 為例）

這一步算是選配，而且比較看個人偏好，但還是想分享一下我的習慣。當專案準備上線或需要分享給別人的時候，我一般會用 Docker（或 Podman）把它容器化。

LLM 處理 Docker 相關的東西非常可靠，所以這是我目前覺得最省心的打包方式。而且現在幾乎所有雲端平台（Render、Railway、Coolify、DigitalOcean、Cloudflare、Netlify……）都支援跑 Docker 容器。我的 AI Agent、API 服務和 MCP 伺服器全部容器化部署。

Dockerfile 範例：

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 拷贝 MCP 服务器代码
COPY . .

CMD ["python", "server.py"]

建置指令：

docker build -t mcp/supabase .

讓 LLM 幫你產生的提示詞：

帮这个 MCP 服务器写一个基于 requirements.txt 的 Dockerfile，然后告诉我怎么构建镜像。