こんにちは、とまだです。

AI代理人已經開始使用了，但您是否曾經感到「雖然能生成可運作的程式碼，但品質讓人擔心...」？

我最開始也是這樣。

使用 Claude Code、Cursor、Codex 時，確實能迅速生成程式碼。
但是，您會擔心這些程式碼真的算是「好程式碼」嗎？

正如 Zenn 上的這篇文章所引起的關注，許多人似乎都在關心程式碼的品質。

因此，這裡介紹一個用於 AI 驅動開發中書寫更好程式碼的「共通規則檔案」！

所謂的「規則檔案」，是指為了讓 AI 寫出更高品質程式碼而編寫的指示檔案。
雖然在 Claude Code 等中稱為「記憶檔案」，但為了使其一目了然，我們稱之為「規則檔案」。

而且，這不是為每個專案單獨創建的，可以通用使用，從而提高撰寫程式碼的效率。
這次將介紹能讓 AI 寫出更高品質程式碼的「共通規則檔案」。

為了讓初學者也能理解，我會細心解釋！

忙碌人士的重點摘要

• 製作告訴 AI 「好程式碼」標準的設定檔案
• 一次設定後，所有專案自動適用
• 程式碼品質將一直由 AI 採納
• 介紹在 Claude Code、Codex、Cursor 上的設定方法
  • 其他 AI 代理人也應該能同樣設定

閱讀此文章的優勢

• 學會如何製作用於 AI 驅動開發的「共通規則檔案」
• 介紹設定方法，可立即實踐
• 寫程式碼時無需擔心安全性或可維護性
• 初學者也能編寫可長期使用的程式碼

那麼，我們馬上進入正題吧！

為什麼 AI 代理人需要「規則」

程式設計中的「好程式碼」意義深遠

剛開始學習程式設計時，我認為「能運行就好」。

然而在實際的開發現場，程式能運行只是最基本的要求。

以烹飪為例。
如果是在家為自己做的料理，「能吃就好」也許可以。
但如果是在餐廳供應的料理，情況就不同了。
不僅要考慮口味，還要考慮外觀、營養均衡、食材安全、成本、烹飪時間等等。

程式設計也是如此。
如果是業餘的程式碼，「能運行就好」就行，但工作中使用的程式碼就不一樣了。
可讀性、易於維護、錯誤處理、處理速度等，皆要求具備各種品質。

AI 不知道「應該重視什麼」

事實上，AI 代理人具備編寫「好程式碼」的能力。

然而，如果我們不給出任何指示，AI 就會優先編寫「至少能運行的程式碼」。

這是為什麼呢？
因為 AI 無法理解「這個專案中應該重視什麼」。

舉個例子，想像一下以下情境。

• 建立原型時 → 重視速度即可
• 交付給客戶時 → 品質和安全性最重要
• 大型服務時 → 性能和擴展性很重要

AI 並無法理解這些背景。
因此，我們需要作為「規則」來教導它。

共通規則檔案是什麼

自動化優秀前輩工程師的建議

共通規則檔案是寫給 AI 的「開發指導」文件。

可以想像是優秀的前輩工程師時刻在您身邊，給出以下幾種建議：
「這個錯誤處理，你寫好了嗎？」
「安全性沒有問題吧？」
「有考慮到後來閱讀的人嗎？」

這些建議將自動由 AI 考慮進去。

一旦設定便可持續使用

共通規則檔案的優點在於，一旦設定後，無需每次開始新專案時重新設定。

專案有特別規則的時候可以新增，但基本的品質規則可以共用使用。

設定方法（5分鐘完成！）

設定方法非常簡單。
由於各 AI 代理人的方法不同，這裡分別說明。

只需按後述的規則複製並粘貼即可。

Claude Code 的情況

Claude Code 是一個從終端使用的 AI 代理人。
設定步驟如下。

1. 創建設定用的資料夾和檔案

打開終端（命令提示字元或 PowerShell），依次執行以下命令。

# 創建資料夾
mkdir -p ~/.claude

# 創建檔案
touch ~/.claude/CLAUDE.md

在 Windows 系統上，請在 PowerShell 中執行以下命令。

# 創建資料夾
New-Item -Path "$HOME\.claude" -ItemType Directory -Force

# 創建檔案
New-Item -Path "$HOME\.claude\CLAUDE.md" -ItemType File -Force

2. 打開檔案並粘貼規則

需要打開創建的檔案。

如果使用 VS Code，可以用以下命令來打開。

code ~/.claude/CLAUDE.md

如果在 VS Code 中不能使用 code 命令，請按照以下步驟啟用它。

1. 打開 VS Code
2. 按下 Command+Shift+P（Mac）或 Ctrl+Shift+P（Windows）
3. 選擇「Shell Command: Install 'code' command in PATH」

或者，也可以直接尋找并打開檔案。
不過，以如 .claude 開頭的資料夾通常是隱藏的，因此需要展現隱藏檔案的設定。
（這裡不贅述，但可搜尋「隱藏資料夾 顯示」了解設定方法）

Codex 的情況

Codex 也遵循相同的步驟。

# 創建資料夾
mkdir -p ~/.codex

# 創建檔案
touch ~/.codex/AGENTS.md

# 用 VS Code 打開
code ~/.codex/AGENTS.md

Cursor 的情況

Cursor 是基於 VS Code 的編輯器，可以通過 GUI（圖形操作）來設定。

1. 打開 Cursor
2. 進入設定畫面（點擊齒輪圖示）
3. 選擇「Rules & Memories」
4. 點擊「User Rules」的「Add Rule」按鈕
5. 粘貼規則並保存

這樣設定就完成了！

實際可用的規則檔案（複製粘貼即可）

接下來，讓我介紹實際上我創建的規則檔案。
只需直接複製粘貼，即可讓 AI 時刻關注程式碼的品質！

# AI 驅動開發 共通指南

## 開發的基本理念
- 不只是寫能運行的程式碼，還要始終意識到品質、可維護性和安全性
- 根據專案的階段（原型、MVP、生產環境）取得適當平衡
- 發現問題時不要放置，必須處理或明確記錄
- 男童兵規則：以比發現時更好的狀態留下程式碼

## 錯誤處理原則
- 即使是看似不相關的錯誤也必須解決
- 不要抑制錯誤（如 @ts-ignore、try-catch 直接忽略），要修正根本原因
- 盡早檢測錯誤，提供明確的錯誤訊息
- 錯誤情況必須在測試中覆蓋
- 考慮到外部 API 或網路通信可能會失敗

## 程式碼品質的標準
- DRY 原則：避免重複，維護單一可相信的信息來源
- 用有意義的變數名稱、函數名稱來清楚表達意圖
- 在專案全體內維持一致的編碼風格
- 即使是小問題也別放置，發現後立刻修正（Broken Windows 理論）
- 評註要解釋「為什麼」，「什麼」用程式碼表達

## 測試規範
- 不要跳過測試，如有問題必須修正
- 測試行為而非實作細節
- 避免測試間的依賴，能隨意執行
- 測試要快速，並始終返回相同結果
- 覆蓋率是指標，應優先重視高質量的測試

## 可維護性與重構
- 增加功能的同時考慮改善現有程式碼
- 大規模更改分割成小步驟
- 積極刪除未使用的程式碼
- 定期更新依賴項（保持安全性和相容性）
- 技術負債要明確記錄於評註或文件中

## 安全性考量
- API 金鑰、密碼等使用環境變數管理（禁止硬編碼）
- 驗證所有外部輸入
- 以最低限度權限運作（最小權限原則）
- 避免不必要的依賴項
- 定期執行安全性稽核工具

## 性能意識
- 基於測量而非猜測進行優化
- 從初期開始考慮可擴展性
- 在需要時才延遲資源加載
- 清晰的快取過期與無效化策略
- 避免 N+1 問題與過度取資料

## 可靠性確保
- 正確設置超時處理
- 實現重試機制（考慮指數回退）
- 利用電路斷路器模式
- 養成對暫時性故障的抗壓性
- 透過適當的記錄和指標確保可觀察性

## 專案上下文的理解
- 取得商業需求與技術需求的平衡
- 判斷目前階段所需的品質水平
- 即使有時間限制，也要維持最低限度品質標準
- 根據團隊整體的技術水平選擇實現

## 認識權衡
- 不可能做到所有事都完美（沒有銀彈）
- 在限制中找到最佳的平衡
- 當是原型時優先簡潔，正式時則堅固
- 清楚記錄妥協點及其原因

## Git 運作的基本
- 使用慣例性提交格式（feat:, fix:, docs:, test:, refactor:, chore:）
- 提交需原子化，專注於單一變更
- 以英文撰寫明確且具解釋性的提交訊息
- 避免直接提交到 main/master 分支

## 程式碼審查的態度
- 將審查評論視為建設性的改善建議
- 聚焦在程式碼而非個人
- 清楚解釋變更的原因與影響
- 歡迎反饋作為學習機會

## 偵錯的最佳實踐
- 確立能確保問題重現的步驟
- 使用二分搜尋法縮小問題範圍
- 從最近的變更著手調查
- 利用除錯器、分析器等適當工具
- 記錄調查結果與解決方案，並分享知識

## 依賴管理
- 僅添加真正必要的依賴
- 一定提交 package-lock.json 等鎖定檔案
- 在添加新依賴前檢查許可證、大小、維護狀態
- 為了安全性修補和錯誤修正，定期更新

## 文件標準
- 在 README 中明確記載專案概述、設定、使用方法
- 文件需與程式碼同步更新
- 優先示範實例
- 重要設計決策用 ADR (Architecture Decision Records) 記錄

## 持續改進
- 將所學應用到下個專案
- 定期進行反思，改善過程
- 適當評估並採納新工具、新方法
- 將知識文件化以便於團隊或未來的開發者使用

8 個品質查核點（初學者解說）

我們將對規則檔案中包含的品質觀點進行初學者易於理解的解說。

1. 錯誤處理（對錯誤的應對）

程式發生錯誤時，該如何處理。

以自動販賣機作為例子更為直觀。
當錢被卡住時，良好的自動販賣機會顯示「錢卡住了，請呼叫工作人員」。
而差的自動販賣機則會直接卡住。

程式也應如此。
當出現問題時，需要適當通知使用者，安全地決定繼續還是停止處理。

通過給 AI 設定規則，讓它自動撰寫能處理網絡錯誤、檔案讀取錯誤的程式碼。

2. 安全性（保持安全）

就像忘記鎖門會讓任何人都能進入，程式同樣需要安全措施。

具體措施包括：

• 不將密碼顯示於畫面
• 對個人資料進行加密
• 阻擋惡意輸入
• 隱藏 API 金鑰（使用服務的鑰匙）

AI 將會自動考慮這些並撰寫對應的程式碼。

3. 可維護性（創建方便修正與改善的程式碼）

程式一旦寫好並非一了百了。
未來需要加入功能或修復 bugs。

就像整理房間一樣。
整齊歸類便於迅速找到需要的東西，混亂則會浪費時間。

整齊的程式碼特徵如下：

• 變數名稱清晰（如不是 a 而是 userName 等）
• 有功能分別的檔案
• 通過註解解釋意圖
• 無重複程式碼

4. 測試性（容易進行測試）

購買新家電時，您總會先確認其運作吧。
程式也應如此，必須設計成便於確保正常運作（測試）。

易測試的程式碼具備以下特徵：

• 功能小而易於拆分
• 不過度依賴外部服務
• 輸入與輸出明確
• 預測行為一致

5. 性能（處理速度）

程式的處理速度非常重要。

在收銀台結帳時，若能將多個商品統一結帳會更迅速，而非分開收銀。

程式亦然，選擇有效率的處理方式至關重要：

• 避免不必要的處理
• 儘量減少資料庫的訪問
• 僅在需要時執行重操作
• 利用快取（暫存記憶體）

6. 可靠性（穩定運作）

當列車延誤時，好的鐵路公司會提供替代運輸的建議。
程式也應有應對問題的替代選項。

提高可靠性的方法：

• 錯誤發生時自動重試
• 停止服務時選用其他服務
• 進行資料備份
• 異常情況則警報出現

7. 可觀察性（容易理解狀況）

如同用體溫計測量體溫，程式要能隨時了解「當前狀況」。

具體可採取以下措施：

• 保留日誌（記錄）
• 記錄錯誤的詳細信息
• 計算處理時間
• 追蹤使用者行為（注意隱私）

當出現問題時，有這些信息將便於確定原因。

8. 可擴展性（擴張能力）

小店如果人氣急增，該怎麼辦？
通常會增設座位或擴建店面。

程式亦是如此，必須設計能夠應對用戶增長的體系：

• 精心設計資料庫
• 讓伺服器可增加的架構
• 設計可並行處理的程式
• 不必要的功能應留到後期補充設計

常見問題

Q: 程式設計初學者也能使用嗎？

當然，這對初學者尤為推薦！

有了共通規則檔案，AI 將在編碼時解釋「為什麼這种實現是好的」。
透過實踐，您可以自然學習如何撰寫好程式碼。

起初，生成的程式碼意義您不理解也無妨。
如詢問 AI「請解釋這段程式碼的錯誤處理部分」，它將耐心解釋。

Q: 所有專案都可以用同樣規則嗎？

基本的規則是可以共用的。
但您也可以為每個專案創建 CLAUDE.md 或 AGENTS.md，進行個性化定義。

例如，在 React 專案中可添加組件配置規則，
或在 TypeScript 中加入型別定義編碼規範等。

Q: 規則太多會讓 AI 混淆嗎？

如果規則過於繁多，有可能讓 AI 感到困惑，但這次所介紹的規則量應不成問題。

此外，規則檔案中會包含「根據專案階段取的適當平衡」指示，因此 AI 能根據情況自行判斷。

不過，若將來再附加越多內容而漸長時，可將 Claude 或 ChatGPT 等傳遞提示與規則檔案進行「內容壓縮」。

這裏提供一個示例提示。這是我常用的：

# 背景
這是針對 AI 的規則檔案。
AI 在進行編碼時，始終參考此規則檔案。

...（這裡放置規則檔案的內容）

# 當前的問題

規則檔案目前變得相當冗長。
如果這樣下去，整體的上下文將變得冗長，性能可能會下降。

# 指令

請在保持原始內容的同時，壓縮和整理內容。

Q: 如何確認已設定的規則？

只需詢問 AI「請告訴我目前設定的規則」，即可確認應用的規則。

若在生成程式碼時請求「為什麼這個實現？」AI 將解釋考慮了哪些規則。

這本身也能成為學習的契機，請務必試試看！

總結

在 AI 驅動開發中，AI 代理人是我們強而有力的夥伴。

但是，夥伴需要知道「預期他能執行什麼工作」。
共通規則檔案則是明確傳達這種期待的手段。

一旦設定，AI 將始終編寫以品質為重的程式碼。

從「可以運行的程式碼」轉變為「好的程式碼」。
開發將更加自信地推進。

設定的時間只需五分鐘即可完成。
希望您立刻試試看！

能編寫更好的程式碼將會讓開發樂趣無窮，也會讓未來的自己及其他開發者感到愉悅。

如有任何問題或洽詢，請隨時在下方留言或這裡聯繫我！

此外，為了已開始進行 AI 驅動開發的人，我今天創建了可以進行問題討論與交流的 Discord 社群。
（即使只是瀏覽也能學習，歡迎隨意參加）

讓我們一起享受 AI 驅動開發的樂趣吧！

原文出處：https://qiita.com/tomada/items/df5d3e0f611860bc2740