前言

前面幾天，我們開始練習使用 AI 開發程式，也學會透過 Spec → Plan → Implement，將需求整理成規格、規劃實作步驟，再交給 AI 逐步完成。

不過，當專案開始累積更多功能，只交代任務需求可能還不夠。假設今天要新增一支搜尋筆記的 API，AI 除了要知道搜尋條件，還需要了解目前的路由如何安排、資料庫怎麼查詢，以及專案原本的錯誤處理方式。如果每次都要重新解釋這些資訊，開發過程就會變得很瑣碎。

更麻煩的是，AI 即使產生了可以執行的程式碼，也不代表它符合專案原本的設計。當它不了解現有的架構與規範，就可能為了完成眼前的任務，採用另一套寫法，讓後續維護變得更加困難。

因此，除了讓 AI 知道這次要做什麼，我們也需要讓它理解專案原本的設計，並在不同任務中延續既有的開發方式。

Prompt 與 Context，分別在做什麼？

使用 AI 寫程式時，我們經常會提到 Prompt 與 Context。Prompt 是這次交給 AI 的任務與要求，Context 則是 AI 執行任務時能取得的背景資訊。

以新增筆記搜尋 API 為例，我們可以先在 Prompt 中描述需求：

請新增一支搜尋筆記的 API，讓使用者可以
透過關鍵字查詢自己的筆記。

請沿用現有的路由設計、資料庫操作方式
與錯誤處理規範。

這段 Prompt 已經說明功能需求與幾項限制，但 AI 還需要知道什麼叫做「現有的路由設計」，也需要知道專案原本如何操作資料庫。這些資訊就屬於 Context。

例如，專案可能使用 Express 處理 API 路由、透過 Service 集中處理業務邏輯，再使用 TypeORM 查詢 PostgreSQL。如果 AI 能參考現有的 Router、Service 與資料模型，就比較容易理解新功能應該如何接進系統。

要提供這些資訊，不一定得把所有內容寫進 Prompt。我們可以直接補充背景、提供相關檔案，也可以讓具備檔案操作能力的 Coding Agent 主動探索專案。

當某些背景資訊會在不同任務中反覆使用，就可以進一步整理成專案指引，減少重複交代的成本。這裡可以先區分三個概念：Prompt 負責交代當次任務，Context 是執行任務時能取得的資訊，而 Project Instructions 則是整理長期適用的背景與規範的一種方式。當工具讀取專案指引後，其中的內容就能成為 AI 執行任務時參考的資訊。

先讓 AI 認識目前的專案

在建立專案指引之前，可以先讓 AI 檢查現有專案，了解目前有哪些檔案、使用哪些技術，以及各個部分如何合作。這個步驟也能幫助我們確認，AI 是否真的理解目前的程式碼，而不是直接根據有限的描述開始修改。

例如，可以先交代 Coding Agent：

請先探索目前的專案，不要修改任何檔案。

請檢查目錄結構、package.json、主要程式碼
與測試設定，並整理以下資訊：

1. 專案使用哪些技術？
2. 主要目錄與檔案各自負責什麼？
3. API 請求會經過哪些處理流程？
4. 資料庫操作集中在哪裡？
5. 如何啟動專案與執行測試？

請根據實際檔案回答，不確定的地方請明確標示。

透過這個指令，AI 可以先從專案目錄與程式碼中整理出初步的理解。以 Express API 為例，我們可能會發現 Router 負責接收請求，Service 集中處理業務邏輯，而資料庫操作則透過 TypeORM 完成。除此之外，也需要確認專案有哪些開發指令，以及目前是否已經建立自動化測試。

這些資訊涉及 Project Structure、Architecture、Coding Convention、Commands 與 Testing。實際使用時，不必為每個名詞建立獨立文件，重點是確認 AI 是否掌握了專案的目錄分工、主要執行流程、既有規範與驗證方式。

不過，AI 整理出的內容仍然需要檢查。例如，它可能只根據檔名推測某個檔案的用途，或將目前的程式碼寫法誤認為團隊刻意制定的規範。如果發現描述不正確，就應該先修正，再將確認過的資訊整理成指引。

將專案知識整理成指引

經過前面的探索，我們已經對專案有初步的認識。接下來，可以把會在不同任務中反覆使用的資訊整理成 Project Instructions，也就是專案指引。

專案指引通常以 Markdown 檔案保存，內容可以包括專案用途、主要目錄的職責、程式碼撰寫規範、常用指令，以及修改程式碼前後需要注意的事項。

以下以目前的筆記 API 架構為例，示範一份簡單的指引。實際內容仍應依照專案設計調整，不能直接把範例中的規則套用到所有專案。

# Project Overview

這是一個使用 Express、TypeORM
與 PostgreSQL 開發的筆記 API。

## Architecture

- routes 負責 API 路由。
- services 負責業務邏輯。
- 資料庫操作沿用既有的資料存取方式。

## Coding Convention

- 使用 ES Modules。
- 沿用現有的錯誤處理方式。
- 新增功能時優先沿用既有架構。

## Development Workflow

- 修改前先檢查相關程式碼。
- 避免修改與任務無關的檔案。
- 完成後執行專案中適用的測試。
- 回報修改內容與測試結果。
- 若有規範無法遵守，請說明原因。

這份指引把原本需要反覆交代的專案資訊集中起來。除了說明專案如何運作，也補充了 AI 執行任務時應遵守的工作流程，讓它不只知道專案有哪些規則，也知道修改前後需要做哪些事情。

指引不需要一開始就寫得很完整。可以先整理最重要的規範，再依照開發過程中遇到的問題逐步補充。比起一次寫出冗長的文件，更重要的是確保內容正確，而且真的能幫助 AI 做出一致的決定。

AGENTS.md 與 CLAUDE.md，需要自己撰寫嗎？

常見的專案指引檔包括 AGENTS.md 與 CLAUDE.md。它們都可以用來保存專案背景與工作規範，但主要對應的工具與讀取方式有所不同。

AGENTS.md 是 Codex 等 Coding Agent 支援的指引檔格式，可以用來說明專案架構、程式碼慣例、常用指令與工作流程。CLAUDE.md 則是 Claude Code 使用的專案指引檔，也能記錄相同類型的資訊。

選擇哪一種格式，主要取決於使用的工具。如果主要使用 Codex，可以先採用 AGENTS.md；如果主要使用 Claude Code，則可以建立 CLAUDE.md。若同時使用不同工具，就需要確認各自的載入規則，不必為了檔案數量而重複維護相同內容。

這些檔案通常可以放在專案根目錄，讓工具依照自己的規則讀取。有些工具也支援在特定子目錄放置更細部的指引，讓不同模組使用不同規範。不過，檔案名稱與所在位置都必須符合工具的要求，不能假設建立任何一份 Markdown 檔案後，所有 Coding Agent 都會自動讀取。

至於檔案內容，不一定要自己從頭撰寫。開發者可以手動整理，也可以請 AI 先探索現有專案，再協助建立初稿。例如，使用 Claude Code 時，可以透過 /init 協助分析專案並產生 CLAUDE.md；使用其他工具時，也可以透過 Prompt 要求 AI 根據實際檔案整理指引。

例如：

請先檢查目前專案的目錄結構、package.json、
主要程式碼與測試設定。

根據實際內容建立 AGENTS.md，整理：
- 專案用途與技術架構
- 主要目錄的職責
- 程式碼撰寫規範
- 常用開發與測試指令
- 修改程式碼前後需要注意的事項

請勿自行假設不存在的功能或規則。
完成後，列出需要我確認的內容。

AI 產生初稿後，仍然需要由開發者檢查。有些程式碼寫法可能只是目前的實作結果，不一定是團隊刻意制定的規則；有些指令也可能因為環境不同而無法使用。因此，確認內容是否符合實際情況，再決定哪些規範值得長期保留，才是建立指引時最重要的工作。

這裡也要注意，專案指引不等於完整的 Context。指引適合保存長期有效的背景與規範，但當 AI 要修改特定功能時，仍然需要閱讀相關程式碼，取得當次任務所需的細節。

如何讓 AI 按照指引執行？

建立指引只是第一步，接下來還需要讓 AI 在實際開發時讀取、理解並遵守這些規範。單純在檔案中寫下要求，並不能保證每次產生的程式碼都符合預期。

以新增搜尋筆記 API 為例，第一步是確認 Coding Agent 有讀取適用的指引檔。可以先要求它整理這次任務需要遵守的架構規範、相關檔案與測試方式。如果找不到指引檔，就應該明確告知，而不是假設它已經讀取。

接著，不要急著讓 AI 修改程式碼，而是先要求它提出實作計畫：

請依照專案指引新增搜尋筆記 API。

開始修改前，請先讀取適用的指引檔，
並檢查相關的 Router、Service 與資料模型。

請提出實作計畫，說明：
1. 預計修改哪些檔案。
2. 如何沿用現有的架構與錯誤處理方式。
3. 如何確保使用者只能查詢自己的筆記。
4. 完成後應執行哪些測試。

請先提出計畫，不要修改任何檔案。

收到計畫後，開發者可以檢查 AI 是否真的理解規範。例如，如果它打算直接在 Router 中撰寫資料庫查詢，就可以先要求它調整計畫，改為沿用專案原本的 Service 分層。確認計畫沒有問題後，再下達第二個指令，讓 AI 開始實作。

這裡的關鍵是分開進行規劃與實作。若只在同一段 Prompt 中要求 AI「先提出計畫，確認後再執行」，它不一定會真的停下來等待開發者核准。分成兩次交辦，才能確保開發者有機會檢查計畫，再決定是否繼續。

這個流程延續了前一天介紹的 Spec → Plan → Implement。先確認需求與實作計畫，再開始修改，可以讓開發者在過程中保有檢查與調整的機會。若使用的工具支援人工核准或權限限制，也可以搭配使用，避免高風險操作在未確認的情況下執行。

當 AI 不遵守規範時，該怎麼辦？

即使 AI 已經讀取指引，也提出了合理的計畫，仍然可能在實作時偏離規範。因此，完成修改後，還需要檢查實際程式碼與功能結果。

以搜尋筆記 API 為例，可以先確認資料庫查詢是否沿用既有的 Service 或資料存取層，再透過測試檢查關鍵字搜尋、錯誤處理與使用者資料範圍是否符合需求。如果專案尚未建立相關測試，也可以補上對應的測試案例。

如果發現 AI 直接在 Router 中操作資料庫，就不應該只要求它「再檢查一次」。可以先確認問題出在哪裡：是指引沒有明確說明架構規範、AI 沒有讀取適用的指引，還是實作時沒有遵守已經知道的規則？

根據原因，再決定下一步怎麼處理。如果指引寫得太模糊，可以補充更明確的要求；如果 AI 沒有讀取指引，就要檢查工具的載入方式；如果規範很重要，而且經常被違反，就可以考慮加入自動化檢查。

這裡需要區分兩件事：要求 AI 自我檢查，可以幫助它發現問題，但不能保證一定找得到；透過工具驗證，則可以針對特定規則或行為提供更可靠的檢查。

例如，ESLint 可以檢查部分程式碼規則，卻不一定能判斷所有架構問題；自動化測試可以驗證特定行為，也無法保證涵蓋所有情境。如果要確認資料庫操作是否遵守分層設計，就可能需要額外的架構檢查或人工 Review。

同樣地，權限與執行限制也不能只寫在指引裡就算完成。如果某些操作不應該由 AI 自行執行，就需要搭配工具本身的權限設定或其他限制機制。

當某項問題反覆出現時，也不代表一定要繼續增加指引內容。先確認問題的根源，再決定要修改 Prompt、補充專案指引，還是增加自動化檢查，才能避免指引越寫越長，卻沒有真正改善開發流程。

結語

專案指引能讓 AI 延續既有的開發規範，但真正可靠的開發流程，還需要搭配計畫確認、測試與程式碼檢查。

當每次開發累積的經驗，都能轉化成後續任務可以參考的資訊，AI 就更有機會融入日常工作。從一次次的指令走向持續協作，關鍵不在於不斷增加規則，而是讓專案資訊、實作流程與驗證機制彼此配合。