🔧 阿川の電商水電行
題言
AI編碼工具的發展迅速變化，像是 GitHub Copilot、Claude Code、Cursor 和 Codex 等，不斷有新工具推出，現有工具也在持續更新。
本文將記錄我截至 2025 年 11 月的 AI 編碼週期快照。
撰寫本文的背景
- 回顧：AI 工具的變化非常迅速，留下當前的快照可以後續回顧時會更加有趣。
- 整理思路：將現行的做法寫下來，可以幫助理清自己的思路。
- 反饋：透過獲得他人的反饋，可以進一步改善。
本文所涵蓋的範圍
主要介紹在個人開發中，如何利用 AI 編碼工具的實際開發週期。將不僅僅使用工具，還會分享在保持品質的情況下有效率地推進開發的方法。
開發環境：構建安全的 AI 編碼環境
在利用 AI 編碼工具之前，首先要整備一個安全且高效的開發環境。
目前我主要使用 Devcontainer 進行開發。
有關 Devcontainer 環境構建的詳細說明，請參考以下文章：
最近，Claude Code 和 Codex 等工具已導入 Sandbox 環境，但因尚未完全跟上，因此仍主要使用 Devcontainer，未來也考慮遷移到 Sandbox 環境。（部分情況下已使用 Sandbox。）
遷移到 Sandbox 可能帶來的好處：
- 無需啟動 Docker，無需擔心本機資源的使用。
- 不需要 devcontainer 的配置。
- 可以直接使用本地設定 (~/.claude/ 下的 commands、agents、skills 等)。
未來我將檢驗並更新開發環境。
AI 編碼週期概述
我的開發週期由以下五個階段組成：
- 計劃：在 GitHub Issue 上進行設計和文檔化。
- 實作：利用 Slash Command/Agent 進行實作。
- 審核：進行多層次的 AI 審核。
- 解決審核：自動化處理審核意見。
- 品質保證：不過度依賴 AI 的機制。
階段 1：計劃 - 在 GitHub Issue 上進行設計
使用 AI 創建 Issue
在開發開始之前，先利用 AI 在 GitHub Issue 上創建問題。像是 Jira 等票務管理工具也可以用相同的方式進行。
AI 將調查並撰寫以下內容：
- 從現有代碼中調查相關部分
- 確定問題發生的區域。
- 相關代碼的結構分析。
- 收集一般性信息
- 最佳實踐。
- 類似問題的解決方法。
- 相關的函式庫或框架信息。
- 確定問題根源
- 為何會發生這個問題。
- 根本原因是什麼。
- 實作方針的建議
- 如何解決這個問題。
- 若有多個選擇的話進行比較。
計劃文檔的好處
這種做法幾乎與所謂的「計劃」階段相同，但透過在 GitHub Issue 等平台上記錄，帶來以下好處：
- 計劃文檔化：以便於後續查閱的形式留下記錄。
- 上下文整理：可以清晰整理在實作階段中需要使用的上下文。
- 團隊共享：與其他成員共享變得簡單。
- 討論平台：可以在 Issue 上進行討論。
人工審核
查看 AI 創建的 Issue，確認是否與自己的思路一致。如有需要，進行修改或補充。
階段 2：實作 - 利用 Slash Command/Agent
確定實作方針後，即可進行實作。
事前準備：創建自訂 Slash Command
為了提高實作效率，事先準備以下自訂 Slash Command：
/resolve-gh-issue：讀取 GitHub Issue 並創建 PR。
詳細內容請見這裡。
實作過程
/resolve-gh-issue #111僅需指定 Issue 號碼，AI 將執行以下操作：
- 讀取 Issue 的內容。
- 根據實作方針編寫代碼。
- 添加必要的測試。
- 創建 PR。
這種方法使得在實作階段中無需每次重複長篇上下文說明。
階段 3：審核 - 多層次的 AI 審核
實作完成後，使用多個工具進行審核。
本地審核
許多 AI 編碼工具都有審核指令，因此可使用本地的審核指令進行審核。（實際上我並不常用）
/reviewGitHub PR 審核
在 GitHub PR 上，利用多個 AI 工具進行審核：
- GitHub Copilot
- Claude Code GitHub Actions
- Gemini Review：透過
/gemini review指令執行（個人推薦✅️） - Codex（個人推薦✅️）
使用多個工具並不是目的，但若多個 AI 提出類似建議，我就會考慮修正，並檢討不同建議中的解決方案。
若已訂閱 ChatGPT Plus（20 美元），現在的審核可在所有的 PR 上免費進行，性價比非常高。可以設定對所有庫的 PR 進行審核。每月僅 20 美元就能讓所有 PR 獲得審核，對於個人開發而言，真是最佳的禮物。
參考：https://developers.openai.com/codex/cloud/code-review/
/gemini review 可以免費使用且反應準確，對我很有幫助。
參考：https://developers.google.com/gemini-code-assist/docs/review-github-code
審核觀點的事前定義
為能有效利用 AI 工具，事先定義審核觀點非常重要。
.github/copilot-instructions.md 的範例如下：
# 代碼審查準則
## 是否遵循潔淨架構的原則？
### 依賴關係的方向
- [ ] 內層（Domain/UseCase）是否未在外層（Infrastructure/Presentation）中導入？
- [ ] Repository 實作（Infrastructure）是否實現了 Domain 層的介面（反之則否）？
- [ ] UseCase 是否依賴於介面而非具體類？
- [ ] 是否透過 DI 容器或建構子注入進行依賴注入？透過具體的設計觀點，讓 AI 能更有效地進行審核。
需要根據每個專案來進行自訂。
一般來說，像是「是否遵循潔淨架構的原則」這種抽象的檢查項目不如以下這樣具體：
## 依賴關係的方向
- [ ] 內層（Domain/UseCase）是否未在外層（Infrastructure/Presentation）中導入？
- [ ] Repository 實作（Infrastructure）是否實現了 Domain 層的介面（反之則否）？
- [ ] UseCase 是否依賴於介面而非具體類？
- [ ] 是否透過 DI 容器或建構子注入進行依賴注入？具體可操作的檢查清單更能提高審核的精準度。
這方面也可以請 Claude 協助整理，使得涵蓋範圍更廣。
階段 4：解決審核 - 審核意見的自動化處理
在收到 AI 或人工審核的意見後，需挑選出需要處理的部分。
檢查多條審核意見
/check-gh-review-comments <pr number>使用此指令將現有的審核意見進行歸類，明確篩選出待處理的有效意見。
- valid：有效。
- outdated：代碼已更新，過期意見。
- fixed：已處理。
詳細資訊請參見這裡。
解決審核意見
/resolve-gh-review-comment <GitHub review comment URL>此命令將自動修正指定的審核意見。
在 AI 進行審核時，經常會附帶如何修改的建議，因此一旦決定修正，就可以交由 AI 處理。
詳細內容請參考這裡。
人工判斷
並非所有 AI 工具的審核意見都自動解決：
- 通過審核意見。
- 判斷是否需要修正。
- 僅對必要的部分交由 AI 解決。
此過程可以在保證品質的同時高效地推進開發。
階段 5：品質保證 - 不過度依賴 AI 的機制
AGENTS.md/CLAUDE.md 的限制
在專案根目錄中可放置 AGENTS.md 或 CLAUDE.md 等檔案以撰寫對 AI 的指示。然而，這些指示有時會：
- 被遺忘：在冗長的對話中可能會被忽視。
- 解釋模糊：人類無法清楚理解的內容，AI 也無法理解。
- 上下文限制：儘管寫了大量指示，但並非所有都能考慮。
因此，徹底做到這一點幾乎是不可能的。（至少截至 2025 年 11 月現在如此。）
為此，利用傳統的靜態解析、腳本、linter 和格式化工具等顯得尤為重要。
自動化工具的整備
在多個人員共同管理代碼的情況下，不能僅依賴 LLM，還需要整備以下工具：
pre-commit
通過pre-commit 可以提高每次提交的質量。
然而，AI 編碼工具有時會避開 pre-commit，因此設定對策也十分重要。
我設定了如何完全防止 AI 代理使用 git commit --no-verify中提到的方法，以防止 AI 編碼工具的規避。
Lint & Test
這部分不必多言，必須根據各專案的語言或框架具備適合的 lint 和測試環境。
CI/CD 中的品質檢查
（此處無新內容，就不多說了）但必須整備 GitHub Actions 等。
- Lint
- 測試
- 安全掃描
- 覆蓋率檢查
每次針對新專案進行設置，無論是請 AI 編碼工具協助創建，時間都會加長，且每個庫的設置也會不一致。因此，根據語言製作GitHub 模板庫，在專案開始時始終應用所需設置。
自訂 Lint 腳本
最近我所做的事情，就是把在 CLAUDE.md 或 AGENTS.md 中寫的但未能徹底執行的規則，通過腳本或自訂 lint 整合進自動檢查中。
例如，在 AI 審核工具的提示範例中，即使寫了以下規則，AI 不會每次都仔細檢查：
- [ ] 內層（Domain/UseCase）是否未在外層（Infrastructure/Presentation）中導入？因此，透過將這種觀點納入腳本或自訂 lint 規則，檢查「在 domain 定義的目錄下的代碼是否導入 infra 包」並整合入 CI，可以減少 AI 的審核負擔。
透過讓 AI 編碼工具生成這些腳本和自訂 lint 規則，可以強化規則的執行，維持一致的代碼品質。
AI 的審核觀點將限縮到無法自動檢查的部分，自然會提高 AI 審核的準確性。
AI 與自動化工具的區分運用
- AI：設計審核、邏輯的合理性檢查、改進建議等。
- 自動化工具：進行格式化、基本錯誤檢查，並加上自訂 lint 規則或腳本，將設計審核和以往默認執行的檢查語言化、工具化，逐步透過自動檢查進行覆蓋。
此組合能有效提高質量，同時推進開發。
總結
透過這個 AI 編碼週期，我認為我可以享受到以下好處：
- 設計品質的提升：在計劃階段進行充分的考量。
- 實作速度的提升：透過 Slash Command 提高效率。
- 審核品質的提升：利用多個 AI 工具進行多角度的審核。
- 可維護性的提升：不僅依賴 LLM，而是透過自動化工具貫徹規則，提升代碼品質。
未來我希望持續改善開發週期。
近期會探討是否能更有效利用以下工具：
- Sandbox 環境
- Coder 等遠端開發環境
- Codex/Claude Code on the web
- Cursor
另外，期待在半年或一年後，再次撰寫 AI 編碼開發週期時，能夠看到截然不同的結果。
原文出處：https://qiita.com/nakamasato/items/ce77984e361ed877f66b
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
