Vibe Coding：8 個超簡單工具加強你的 Python 專案

前言

你是否也曾體驗過 Vibe Coding 的魅力？ 完全不需介入，LLM就像自動導航的飛機一樣，幫你開發、除錯甚至是撰寫文件，這真是太棒了！ 我只需要坐在椅子上就有人幫我工作 哈哈哈！

但，美好的表象下是否潛藏著危機？想像一下這個場景：

現在，你是一個 Vibe Coder，你用充滿著熱情、願景的文字去告訴 LLM 你的偉大計劃以及未來的藍圖。LLM 似乎也像你心靈伴侶一樣，全力回應你的期待。

但突然，你的 LLM 一直給予你新功能跟程式碼，你快要跟不上了，你彷彿坐在一輛隨時會失控的雲霄飛車上。你按下了"STOP"，希望一切都能等你搞清楚後再繼續，但你心裡最害怕的事情終於發生了，原本該顯示的畫面卻不顯示了、原本該運作的功能卻沒有用了。而且你不知道怎麼把事情導回正軌...

經過一個下午的 Vibe Debugging 後，一切回歸正軌了，感謝 LLM 的努力，你心滿意足的輸入 git push，並且把專案發上 X、Threads、Linkedin，向這個世界宣佈你的最新創舉。你也如期獲得了很多鼓勵跟聲浪，你心滿意足的去睡了。

而隔天醒來，你突然發現你專案所使用的 Supabase 資料庫，裡面的資料都不見了！並且你的付費 API 用量突然暴增！這時你才發覺你把自己的金鑰都上傳了。現在你面臨著 12 萬元的帳單....

這段故事並非危言聳聽，而是已經發生過的 Vibe Coder 悲劇 😅

別擔心！這篇文章正是為了解決這些問題而生。專為 Vibe Coding 的初學者設計，特別是那些除了用 LLM 開發作品外，還希望可以讓作品能夠在未來繼續支持修改或擴充功能的人。你可能不是軟體開發相關從業人員，不知道除了寫程式碼外，還需要哪些設定或是工具來補助你開發，那這篇就是寫給你的。

我們將以一個簡單的 Flask 待辦清單應用程式（使用 SQLite 資料庫）為例，介紹在 Vibe Coding 的前、中、後期可以運用的 8 個工具與方法論，讓你的專案有更堅固的基礎，避開上述的種種陷阱。本篇文章不會教你怎麼去寫程式碼，也不會真的讓你做出個 TODO APP 出來，而是介紹開發過程中可以使用的基本工具或是技巧。

以下是專案開發流程所使用到的工具：

---
config:
  look: handDrawn
  layout: dagre
---

flowchart TD
    A[前期：初始化
 .gitignore
 git init
 uv 環境與套件
 Ruff Linter&Formatter] --> B[中期：開發與協作
Git 版本控制
Git Workflow分支管理
Dotenv 金鑰管理]
    B --> C[後期：完善與分享
Readme 專案文件
Mermaid 流程視覺化]
style A fill:#FFE0B2
style B fill:#BBDEFB
style C fill:#FFCDD2

本篇涵蓋工具與方法論

國外可能會稱這些為 Python 開發的 Essential Knowledge，但它們是 Python 開發的全部嗎？

可差得遠了！

但今天我們的主軸是 Vibe Coding 對吧？

我們可不想花一堆時間去學資料結構、系統設計、時間複雜度、TDD、Pythonic、Clean Code，我們只想要快速開發個原型拿去社群網路炫耀、申請政府補助或是給老闆交差。我們只想快速開發原型、展示成果，同時又希望能避免常見的開發陷阱。

下面是我認為，學習成本低但卻能大量穩固你專案的工具

• gitignore：避免上傳敏感或無用檔案到網路上，你整個專案的防呆裝置
• Git：負責版本控制，輕鬆管理程式碼
• uv：快速管理 Python 套件與虛擬環境
• Ruff：讓程式碼符合 Python 規範格式，並且速度很快
• Git Workflow：分支管理的方法論，讓你可以切分穩定跟開發的程式碼
• Dotenv：安全管理 API 密鑰與資料庫憑證
• Readme：為專案寫一份清晰的說明文件
• Mermaid：用流程圖展示專案邏輯

相較於手動管理檔案或版本，這些工具能讓你的專案更規範、協作更順暢。我們接下來文章會以開發專案的前期、中期、後期來區分，並且告訴你什麼工具適合在什麼時機使用！

前期：專案初始化

好的開始是成功的一半，對吧？為了避免像前言故事中那樣，一開始就陷入混亂導致後續的災難（例如金鑰不小心上傳），我們在專案啟動時就該建立起版本控制、套件與環境管理以及基礎安全防護。這些步驟花不到你五分鐘，卻能為你的 Vibe Coding 旅程打下堅實的基礎。

gitignore：你的專案防呆裝置

.gitignore 是一個檔案，他的功能就是告訴 Git，在每次暫存(add)、提交(commit)、推送時(push)時，Git 會檢查.gitignore檔案並且會忽略裡面檔案或資料夾，例如虛擬環境或密鑰檔案。

假設你不希望把 venv/ 或 .env 推到 GitHub。

範例：

#your_project/.gitignore

venv/
.env

這樣你就安全了！ 但你需要一個一個輸入到.gitignore裡面嗎？

當然不用！你只需要去 gitignore.io 網站，輸入你專案會用到的語言或是框架，這個網站自動會生成 gitignore 文件，你只需要複製並新增到你專案裡面就好！

git init：讓你的專案引入存檔機制

接著你可以在專案資料夾中初始化 Git 儲存庫，開始追蹤你專案的程式碼版本。

git init

執行後，專案資料夾會多一個 .git/ 目錄，啟動版本控制。

uv : Python 虛擬環境與套件管理的首選

對於 Python 開發者來說，uv 跟等等會提到的 ruff 可是偉大的工具之一，而這兩項工具都出自同一個公司 Astral，他們的產品都離不開簡單、快速跟實用三個核心，目標是要開發出 Python 唯一首選工具，很有野心，但目前我覺得這個目標並不是不無可能。

uv 的特色就是他包辦 Python 環境管理、套件管理，而且非常容易使用跟快速，詳情可以去我很喜歡的部落格 Python 套件管理器 uv 介紹——與 Poetry 比較 ，這邊只提供常見指令。

安裝 uv：
在 Cursor 或 Vscode 的內建終端機中，輸入以下指令安裝 uv（詳見 官方 Repo）：

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安裝完成後，初始化專案與虛擬環境：

uv init todo-app
#Initialized project `todo-app` at `/home/user/todo-app`
cd todo-app #進到todo-app資料夾中
uv venv --python 3.12 #在專案資料夾中創造Python虛擬環境

這會給你創造一個 Project Based 的 python 3.12 虛擬環境。

如果你想要先安裝幾個 Dependency 的話，例如 flask

uv add flask #安裝flask
uv remove flask #移除flask

假設你寫了一個簡單的 hello_world.py，並且你想要執行它

uv run hello_world.py

Ruff：Python Linter 跟 Formatter 的最佳工具

如果你有寫過論文，你一定有一段痛苦的時期是在調整論文的格式符合學校的標準，例如引用文獻的標準、每段開頭要空幾格之類的。但你知道程式碼也有相關的規定嗎？導入模組編排順序、程式碼縮進要幾格、每列最多幾個字都有個標準，叫做 PEP8。

而 Ruff 會自動進行靜態語法檢查 (Linter) 以及調整你的 Python 程式碼，使其符合 PEP8 格式。因此這些你不用自己檢查，只需要 Ruff 就可以自動幫你完成。

有關 Ruff 的更多介紹 ，歡迎去看一個很棒的文章介紹 Python 開發：Ruff Linter、Formatter 介紹 + 設定教學 。下面只會介紹安裝跟啟用Ruff 的方法

安裝與執行：
Vscode or Cursor打開插件->搜尋Ruff ->安裝

VSCode 設定存擋自動格式化：
在 VSCode（或 Cursor IDE）中，按下Ctrl + Shift + P

輸入Preference: Open User Setting(Json)編輯 settings.json：

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}

這樣儲存程式碼時，Ruff 會自動觸發格式化程式碼。

建立完這些基本的設定之後，你以經可以有一個良好的基礎去 Vibe Coding 了。

延伸閱讀

Ruff extension for Visual Studio Code

中期：開發與協作

進入開發中期，專案的功能會像前言故事中描述的那樣，在 LLM 的協助下快速增加。這時，如果沒有良好的習慣，很容易就會遇到程式碼版本混亂或是不小心洩漏重要資訊的問題。因此，在這個階段，掌握 Git 的進階用法、採用合適的 Git Workflow，以及使用 Dotenv 來避免直接遺留金鑰、IP、密碼等敏感資料在程式碼中就變得十分重要，確保你的金鑰不會洩漏，你辛苦開發的程式碼不會消失。

Git：你的時光機與安全網

Git 就像是遊戲的存檔點。你對專案做的每一項有意義的修改，都可以建立一個「存檔」（commit）。這樣一來，如果不小心改壞了，或者想回到之前的某個狀態，Git 就能幫你「讀檔」回到過去。下面列出幾個常見情境

基本流程：add -> commit

a.git add <檔案> 或 git add .（挑選要打包的修改）

• 行為：git add 指令會將你指定的檔案變更，從你的「工作目錄」（Working Directory，你實際修改檔案的地方）放到「暫存區」（Staging Area）。這個暫存區就像一個購物籃，讓你先把確認要「結帳」（commit）的商品放進去。
• 時機：
  • 當你完成了一個小功能、修正了一個錯誤，或進行了一組邏輯上相關的修改時。
  • 建議將相關的修改放在同一次 commit 中，例如，你修改了三個檔案來完成一個新功能，就應該把這三個檔案的變更一起 add。

範例：

# 只將 specific_file.py 的修改加入暫存區
git add specific_file.py

# 將目前資料夾下所有已修改或新增的檔案（不包含 .gitignore 中指定的檔案）加入暫存區
git add .

b. git commit -m "你的存檔描述"（確認存檔）

• 行為：git commit 會將目前「暫存區」裡的所有變更，正式打包成一個新的「版本紀錄點」（commit），並儲存到你的本地 Git 儲存庫（Repository）中。-m "..." 後面是你對這個版本的描述，這個描述非常重要，應該清楚說明這次提交做了什麼修改。
• 時機：
  • 當你已經將所有相關的變更都 add 到暫存區後。
  • 一個好的 commit 通常代表一個完整且獨立的變更單位（例如：一個新功能、一個錯誤修復、一次文件更新）。

範例：

git commit -m "實現使用者登入API端點"

Vibe Commit

如果你用Cursor的話，你可以到git頁籤中點選一個按鈕，讓LLM自動幫你寫Commit Message，然後提交。

詳細介紹 ：AI Commit Message

「啊！改錯了/我反悔了！」—— 如何拋棄修改 (Discarding Changes)

開發過程中，如果你不小心改壞東西的時候。Git 提供了幾種方式讓你反悔：

a.拋棄「工作目錄中」尚未暫存的修改 (Discarding unstaged changes in working directory)

• 情境：你修改了某個檔案（例如 app.py），但這些修改還沒用 git add 加到暫存區。你突然發現這些修改是錯的，想直接 還原到上次 commit 後的狀態（或是上次 add 之後，如果你 add 過又改了）。
• 指令：git restore <檔案名稱>

範例：

# 拋棄 app.py 在工作目錄中的所有修改
git restore app.py
# 或者
git checkout -- app.py

b. 將已「暫存」的修改移出暫存區 (Unstaging changes)

• 情境：你已經用 git add app.py 把 app.py 的修改加到暫存區了，但後來想想，這個修改還不夠完善，或者不應該包含在下一次的 commit 中。你想把它從暫存區「拿出來」，但保留你在工作目錄中做的修改，以便後續調整。
• 指令：git restore --staged <檔案名稱>

範例：

# 將 app.py 從暫存區移除，但保留工作目錄中的修改
git restore --staged app.py

執行後，app.py 的修改就不會包含在下一次 git commit 的內容中了，但檔案本身的修改內容依然存在於你的工作目錄。

c. 拋棄所有「未 commit」的修改，回到上次 commit 的狀態 (危險操作！)

• 情境：你把專案改得一團亂，或者做了一些實驗性的修改後，決定完全放棄這些尚未 commit 的變動（包括工作目錄和暫存區的），直接讓整個專案回到上一次成功 commit 時的乾淨狀態。
• 指令：git reset --hard HEAD

範例：

git reset --hard HEAD

其他重要指令

• git status：讓使用者隨時了解目前工作目錄和暫存區的狀態，這是最常用的 Git 指令之一，非常有助於釐清狀況。
• git log：查看提交歷史，了解專案的演進過程。
• git clone ：從遠端下載一個專案副本開始工作。
• git push：將本地的 commit 推送到遠端儲存庫。
• git pull：從遠端儲存庫拉取最新的變更並合併到本地。

Git Workflow：讓你的專案可以在副本下安心開發

恭喜你已經成功掌握了 Git 的基本存檔與讀檔技巧！這相當於學會了軟體工程中版本控制的一半精髓。你現在知道在特定情境下該使用哪些指令來保護你的工作成果。但版本控制還有一個非常重要的課題，那就是分支 (Branch) 管理。

想像一下這個情境：你是一位設計師，每個月都要為公司製作一份重要的產品發表簡報。

你手上有一份上個月完美定稿的簡報 (last_month_final.ppt)。這份簡報是經過驗證、可以隨時拿出來展示的穩定版本。

現在，你需要為這個月的新產品製作一份全新的簡報。你當然不希望從零開始，很多基礎架構、公司 Logo、風格範本都跟上個月一樣。

如果你直接打開 last_month_final.ppt 開始修改，會發生什麼事？

• 萬一你改到一半，老闆突然說：「嘿，我需要看一下上個月的簡報最終版，馬上就要！」你就麻煩了，因為你的檔案已經被改得面目全非，很難立刻還原。
• 或者，你改了幾天後發現新的方向是錯的，想回到上個月的簡報狀態，卻發現原始的內容已經被覆蓋，難以追溯。

這時候，你會怎麼做？你會先複製一份 last_month_final.ppt，例如命名為 this_month_draft_v1.ppt 然後，你所有的修改、新增、刪除投影片，都在這個 this_month_draft_v1.ppt 副本上進行。

這樣有什麼好處？

• 獨立工作空間：在這個「副本」上，你可以隨心所欲地嘗試各種新的設計、加入新的產品圖片、調整內容順序，完全不用擔心會影響到那份原始的 last_month_final.ppt。
• 隨時切換：如果老闆臨時要看上個月的簡報，你只需要打開 last_month_final.ppt 就能立即給他。你的「副本」工作完全不受干擾。
• 整合與定稿 (如同 merge)：當你對 this_month_draft_v1.ppt 的修改感到滿意，並且經過審核後，你就可以將這些修改「合併」回你的主要簡報流程中，或許會把它另存為 this_month_final.ppt，或者更新你的主要簡報範本。 (這類似於 git checkout develop 然後 git merge feature/new-product-slides)

所以若把上面概念套用在 Git Workflow，那會是怎麼樣？

首先最核心的 Git Branch 會有「main」、「develop」、「feature」

想像 main 分支就是你那份完美定稿的 last_month_final.ppt。而 develop 分支則是 main 的一個副本，準備作為這個月簡報的基礎。

當我們要開始製作本月的簡報時（也就是開發新功能），我們不會直接修改 develop（如同不直接修改 last_month_final.ppt 的副本）。我們會從 develop 再建立一個新的分支，例如 feature/new-product-slides。 然後在feature上面進行開發，等到開發完成後，再把 feature/new-product-slides 合併回develop

a. 創造新的featue分支並進行開發：

從 develop 分支建立並切換到新的 feature/new-product-slides 分支：

git checkout -b feature/new-product-slides

切換到 develop 分支 (確保我們從正確的基礎開始)：

git checkout develop

現在，你就在 feature/new-product-slides 上進行所有修改了。

b. 完成開發與合併 (如同簡報定稿並整合)：

當 feature/new-product-slides 分支 上的內容都修改完成(commit)，並且審核通過後，就需要將這些變更合併回主要的開發流程中。

Git 指令範例：

首先，切換回 develop 分支 (準備將修改好的內容合併進來)：

git checkout develop

將 feature/new-product-slides 分支的變更合併到 develop 分支：

git merge feature/new-product-slides

透過這樣的分支與合併流程，你的主要簡報 (develop 分支) 就能夠持續整合最新的修改，同時原始的 main 分支 (最原始的 last_month_final.ppt) 仍然保持穩定，不受開發過程中的變動影響。

而當你在develop上開發完一個階段後，並且也經過測試，你要怎麼把develop併回去main?

git checkout main
git merge develop

上述是單人開發的情況，若是在團隊中進行開發，每次 merge 前務必先git pull，檢查你的本地程式碼是否跟雲端上的程式碼有差異(過時)，並且在必要的時候去進行 rebase 的動作。 詳細可以參考延伸閱讀

延伸閱讀
Git Workflow: A Complete Guide for Managing Your Codebase Effectively

Dotenv：保護資料庫憑證

還記得我們開頭的故事嗎？發生了線上服務被串改以及付費的 API 被惡意使用，導致你要付天價的帳單。但為什麼會發生這種事？

原因就是你在程式碼當中存放了你呼叫的資料庫、LLM、付費服務的 Credential，並且不小心把這類的資訊上傳到 Github 或網路上。那要怎麼避免呢？

其實很簡單

• 在.gitignore 中加入.env
• 金鑰、密碼、IP 網址、帳號通通存放在.env中
• 在程式碼中只使用python dotenv來去載入機密資訊在程式執行週期

假設你今天的專案需要連接到 SQLite 資料庫。

1. 安裝 dependency

uv add python-dotenv

1. 創造 .env 檔案：

DATABASE_URL=sqlite:///todo.db
DB_KEY=your-secret-key

1. 載入環境變數：

from dotenv import load_dotenv
import os

load_dotenv() #把.env內容讀入環境變數中
DATABASE_URL = os.getenv("DATABASE_URL") #從.env中讀取DATABASE_URL
DB_KEY = os.getenv("DB_KEY") #從.env中讀取DB_KEY

這樣就可以了

若不小心 push 憑證：

先把 API 金鑰撤銷或是密碼改掉!!!
然後參考 不小心把帳號密碼放在 Git 裡了，想把它刪掉…

後期：撰寫說明文件，未來的你會感謝你自己

README 文件 : 給未來的自己一份情書

你永遠都不會知道將來是否需要回頭修改你的專案，或是其他人需要接手。相信我，幾個月後的程式碼，對你來說可能會像高中微積分一樣陌生。這時，一份清晰的 README 文件就是你的救星，你會非常感謝過去的自己留下了這份指引。

「但是，寫文件好麻煩啊...」

別擔心！在這個 LLM 盛行的時代，文件撰寫當然也可以請 AI 代勞。你可以提供專案的概要、主要功能、使用的技術等資訊給 LLM，讓它為你生成一份 README 初稿。

利用 LLM 生成 README 的提示詞範例：

為我的 Python Flask 待辦事項專案 (使用 uv, SQLite, Python 3.12) 撰寫一份 README.md。
需包含：專案簡介、功能、安裝步驟 (含 uv 指令、`.env` 範例)、執行指令及 API 端點。
請使用清晰的 Markdown 格式。

輸出範例:

# 待辦清單應用程式

一個簡單的 Flask 應用程式，支援任務創造、查詢與刪除，使用 SQLite 資料庫。

## 安裝

1. 克隆儲存庫：`git clone <repo-url>`
2. 初始化虛擬環境：`uv venv --python 3.12`
3. 安裝依賴：`uv add flask python-dotenv`
4. 設置環境變數：創造 `.env`（參考 `.env.example`）
5. 運行應用程式：`flask run`

## 使用

- 創造任務：`POST /tasks`
- 查詢任務：`GET /tasks`
- 刪除任務：`DELETE /tasks/<id>`

Mermaid：視覺化你的專案邏輯

文字再多，有時也不如一張圖來得清晰明瞭。特別是在解釋複雜的流程或系統架構時，流程圖是絕佳的輔助工具。這時候，Mermaid 就派上用場了！它讓你可以用簡單的文字語法來描述圖表，然後自動生成流程圖、序列圖、甘特圖等等。「畫流程圖？聽起來又是一個大工程...」Vibe Coder 可能又會這麼想。別擔心，如同 README，Mermaid 圖表也能請 AI 助手代勞！利用 LLM 生成 Mermaid 流程圖的提示詞範例：假設你想為你的 Flask 待辦事項應用程式的主要 API 互動流程製作一張圖：

請使用 Mermaid 的 flowchart TD 語法，為一個 Flask 待辦事項應用程式生成一個流程圖。
流程應包含：使用者發送請求 (POST/GET/DELETE 到 /tasks)，Flask 處理請求，SQLite 資料庫操作 (INSERT/SELECT/DELETE)，最後回傳成功訊息。
請盡量簡潔明瞭地呈現核心互動。

Mermaid 範例：下面這張圖就是一個很好的範例，展示了待辦事項 API 的核心流程：

---
config:
  look: handDrawn
  layout: dagre
---
flowchart TD
    A[使用者發送請求] --> B{請求類型}
    B -->|POST /tasks 創造任務| C[Flask 處理請求]
    B -->|GET /tasks 查詢任務| C
    B -->|DELETE /tasks/id 刪除任務| C
    C --> D[連接到 SQLite 資料庫]
    D --> E{資料庫操作}
    E -->|INSERT INTO tasks| F[執行 SQL 語句]
    E -->|SELECT FROM tasks| F
    E -->|DELETE FROM tasks| F
    F --> I[回傳成功/結果訊息給使用者]

這張流程圖清晰地展示了從使用者請求到資料庫操作，再到最終回應的完整路徑，能讓其他開發者或未來的你快速理解 API 的運作方式。

那實際語法如何？

flowchart TD
A[使用者發送請求] --> B{請求類型}
B -->|POST /tasks 創造任務| C[Flask 處理請求]
B -->|GET /tasks 查詢任務| C
B -->|DELETE /tasks/ 刪除任務| C
C --> D[連接到 SQLite 資料庫]
D --> E{資料庫操作}
E -->|INSERT INTO tasks| F[執行 SQL 語句]
E -->|SELECT FROM tasks| F
E -->|DELETE FROM tasks| F
F --> I[回傳成功/結果訊息給使用者]

延伸閱讀

快速上手Mermaid流程图

結語

透過這 8 個關鍵工具的學習與實踐，您的 Python 專案將不僅充滿 "Vibe"，更能兼具專業性與安全性！從此告別程式碼管理的混亂與敏感資訊外洩的擔憂。無論是透過 Git 與 Git Workflow 建立穩固的版本控制，還是利用 Dotenv 與 .gitignore 保護您的重要憑證，這些工具都將是您開發旅程中的得力助手。現在就開始將它們應用到您的專案中，打造出更穩健、更可靠、更令人安心的精彩作品吧！