Codex CLI 教學手冊

Enterprise Codex CLI Architecture & Engineering Handbook 把 Codex CLI 當成 AI Software Engineering Agent 導入 Web 開發、Legacy 逆向工程、Framework 升版、Testing、Code Review、DevSecOps 與 CI/CD 的完整實作手冊

文件資訊

v1.1 改版摘要（2026-09-06）

本次改版以「對照官方文件站與 Repository 逐章覆核」為原則，補齊下列 v1.0 未涵蓋或涵蓋不足的官方能力：

⚠️ v1.0 讀者請特別注意兩處術語變更

1. Guardian → Auto-review：設定值的正規寫法已改為 auto_review，guardian_subagent 降為 legacy alias。2026 上半年的社群文章大量使用 Guardian 一詞。
2. 模型退場：gpt-5.4 與 gpt-5.4-mini 已於 2026-08-31 從「以 ChatGPT 登入的 Codex」退場，gpt-5.2 / gpt-5.3-codex 已淘汰。若設定檔或 CI 仍釘選這些模型，請立即更新。

本手冊與《OpenAI Codex生態系教學手冊》的分工

同目錄下已有一份《OpenAI Codex生態系教學手冊.md》（v1.5，2026-06-30）。兩份文件定位不同、不互相取代：

本手冊為單一自足文件，讀者不需搭配任何其他檔案即可完成全部教學。第 2 章仍會完整交代生態系全貌，僅在純產品面細節（Sites、Chrome、Appshots）改列延伸閱讀，避免重複。

可信度標示制度（請務必先讀）

Codex CLI 迭代極快，且官方文件站近期整站搬遷、部分能力仍標示為實驗性。為避免讀者把「本手冊的企業實務建議」誤讀成「官方規範」，本手冊在每個小節標題後標註來源等級：

另外，凡涉及版本行為差異之處，一律以下列格式標註：

⚠️ Version Note

說明哪個版本之前 / 之後行為不同。

三個必須先知道的版本差異

在讀任何舊教學、舊部落格文章之前，先記住這三件事：

⚠️ Version Note 1：官方文件已整站搬遷

developers.openai.com/codex/* 目前會 308 轉址到 learn.chatgpt.com/docs/*，且兩種路徑形式並存：多數功能頁不含 /codex/ 前綴（例如 AGENTS.md 位於 learn.chatgpt.com/docs/agent-configuration/agents-md、Auto-review 位於 learn.chatgpt.com/docs/sandboxing/auto-review），少數頁面則含前綴（例如 learn.chatgpt.com/docs/codex/cli）。同一頁不保證兩種形式都通——加錯前綴會直接回 404。 遇到 404 時，先試著加上或去掉 /codex/ 再判定該頁不存在。 同時，GitHub Repository 的 docs/ 目錄已精簡為 contributing.md、install.md、open-source-fund.md 三個檔案——文件主體已移到官網。網路上大量教學仍指向舊網址，內容也多半停在舊版。

⚠️ Version Note 2：Linux sandbox 是 Bubblewrap，不是 Landlock

目前官方文件所述的 Linux / WSL2 沙箱實作為 Bubblewrap（bwrap） 的 user namespace 隔離。早期版本文件與大量二手文章仍寫 Landlock/seccomp，兩者的錯誤訊息與疑難排解方式完全不同（見第 32 章）。

⚠️ Version Note 3：Windows 已有原生 sandbox，不再「必須用 WSL」

官方 sandboxing 文件明列 Windows 原生沙箱（PowerShell） 為受支援的實作，README 也提供 install.ps1 的原生安裝路徑。 但 Repository 內的 docs/install.md 仍寫「Windows 11 via WSL2」——那份文件是「從原始碼建置」的開發者指引，講的是開發 Codex 本身的環境需求，不是一般使用者的安裝需求。兩者不衝突，但極容易誤讀。詳見第 5 章 與第 36 章。

目錄

全書共 50 章、456 個小節，依主題歸為 8 個部。 以下為完整的章級與小節目錄，每一個項目都可直接點擊跳至本文對應位置。 為維持目錄可讀性，目錄項目省略了各小節標題末端的來源等級標記（【Official】/【建議】/【Experimental】/【Community】）——標記本身仍完整保留在本文的小節標題上。

依角色的建議入口【建議】：

第一部　概念與架構（第 1–4 章）

• 1. Codex CLI Overview

  • 1.1 Codex CLI 是什麼
  • 1.2 它解決什麼問題
  • 1.3 Coding Agent 是什麼
  • 1.4 AI Coding Assistant 與 AI Coding Agent 的差異
  • 1.5 Codex CLI 與一般 Chatbot 的差異
  • 1.6 Codex CLI 與傳統 IDE Assistant 的差異
  • 1.7 核心價值
  • 1.8 適合與不適合的工作
  • 1.9 整體運作圖
  • 1.10 本章實務案例
  • 1.11 本章注意事項

• 2. Codex Ecosystem

  • 2.1 Codex 不只是一個 CLI
  • 2.2 各入口的定位與選用
  • 2.3 完整能力對照表
  • 2.4 Codex CLI 與 Codex Cloud 的關係
  • 2.5 Codex SDK 概觀
  • 2.6 GitHub Action 概觀
  • 2.7 延伸閱讀：生態系的其他成員
  • 2.8 第三方整合與新興介面
  • 2.9 本章實務案例
  • 2.10 本章注意事項

• 3. Codex CLI Architecture

  • 3.1 什麼是 Agent Harness
  • 3.2 分層架構
  • 3.3 一次完整的 Agent Turn
  • 3.4 核心概念逐一說明
  • 3.5 為什麼 Codex CLI 不是單純的 LLM Chat Interface
  • 3.6 本章實務案例
  • 3.7 本章注意事項

• 4. Agent Loop

  • 4.1 Agent Loop 是什麼
  • 4.2 九個階段逐一說明
  • 4.3 Agent Loop 與 Prompt → Response 的根本差異
  • 4.4 影響 Loop 效率的六個因素
  • 4.5 一個真實的 Loop 展開範例
  • 4.6 本章實務案例
  • 4.7 本章注意事項

第二部　安裝與設定（第 5–9 章）

• 5. Installation

  • 5.1 安裝方式總覽
  • 5.2 macOS / Linux 安裝
  • 5.3 Windows 安裝
  • 5.4 從原始碼建置
  • 5.5 安裝相關環境變數
  • 5.6 更新與版本管理
  • 5.7 PATH 與安裝驗證
  • 5.8 Shell 自動補全
  • 5.9 安裝疑難排解
  • 5.10 本章實務案例
  • 5.11 本章注意事項

• 6. Authentication

  • 6.1 兩種認證身分
  • 6.2 Sign in with ChatGPT（推薦）
  • 6.3 Device Code 流程（無瀏覽器環境）
  • 6.4 API Key 認證
  • 6.5 Access Token（Business / Enterprise）
  • 6.6 認證相關環境變數
  • 6.7 企業網路與 TLS 攔截
  • 6.8 限制認證方式（企業管控）
  • 6.9 認證方式比較
  • 6.10 憑證安全紅線
  • 6.11 本章實務案例
  • 6.12 本章注意事項

• 7. Configuration

  • 7.1 設定的五個層級與優先順序
  • 7.2 設定檔位置速查
  • 7.3 最小可用設定
  • 7.4 模型與推理設定
  • 7.5 Fast Mode 與服務層級（service_tier）
  • 7.6 Approval 與 Sandbox 設定
  • 7.7 Permission Profiles
  • 7.8 Profiles（具名設定層）
  • 7.9 Features 旗標
  • 7.10 Web Search 設定
  • 7.11 Hooks（生命週期攔截）
  • 7.12 MCP 設定
  • 7.13 Skills 與 Plugins 設定
  • 7.14 Model Providers（自訂供應者 / 企業代理）
  • 7.15 歷史、遙測與稽核
  • 7.16 企業受管設定 requirements.toml
  • 7.17 專案層設定範例
  • 7.18 設定除錯
  • 7.19 本章實務案例
  • 7.20 本章注意事項

• 8. AGENTS.md

  • 8.1 AGENTS.md 是什麼
  • 8.2 為什麼它是最高投報率的一件事
  • 8.3 檔案探索與優先順序
  • 8.4 驗證有沒有被讀到
  • 8.5 覆寫機制 AGENTS.override.md
  • 8.6 相關設定
  • 8.7 階層式配置的企業範例
  • 8.8 根目錄 AGENTS.md 完整範本
  • 8.9 子目錄 AGENTS.md 範例
  • 8.10 寫好 AGENTS.md 的七個原則
  • 8.11 AGENTS.md 反面教材
  • 8.12 本章實務案例
  • 8.13 本章注意事項

• 9. Codex CLI Basic Usage

  • 9.1 第一次執行
  • 9.2 帶著 prompt 啟動
  • 9.3 全域旗標
  • 9.4 互動式 Slash Commands
  • 9.5 Session 管理
  • 9.6 非互動模式 codex exec
  • 9.7 腳本化使用
  • 9.8 常用維運指令
  • 9.9 Plugins
  • 9.10 每個常用指令的完整說明
  • 9.11 一天的典型工作流
  • 9.12 Git Worktree 與平行 Session
  • 9.13 本章實務案例
  • 9.14 本章注意事項

第三部　使用方法（第 10–11 章）

• 10. Prompt Engineering for Codex

  • 10.1 為什麼「Fix this bug」不夠
  • 10.2 企業級 Prompt Template
  • 10.3 Prompt 的七個原則
  • 10.4 Prompt 範本庫（十種任務類型）
  • 10.5 Prompt 的常見錯誤
  • 10.6 迭代式 Prompt 策略
  • 10.7 本章實務案例
  • 10.8 本章注意事項

• 11. Repository Understanding

  • 11.1 為什麼「理解」要單獨成為一個階段
  • 11.2 理解的七個層次
  • 11.3 標準的理解流程
  • 11.4 大型 Repository 的處理策略
  • 11.5 把理解結果沉澱下來
  • 11.6 驗證 Agent 的理解是否正確
  • 11.7 本章實務案例
  • 11.8 本章注意事項

第四部　工程實務（第 12–18 章）

• 12. Web Application Development

  • 12.1 完整開發流程
  • 12.2 技術棧設定
  • 12.3 後端開發
  • 12.4 前端開發
  • 12.5 資料庫
  • 12.6 端到端範例：從需求到 PR
  • 12.7 本章實務案例
  • 12.8 本章注意事項

• 13. Reverse Engineering

  • 13.1 逆向工程的目標
  • 13.2 逆向工程 Workflow
  • 13.3 階段 ①：Inventory（盤點）
  • 13.4 階段 ②：Dependency Analysis（依賴分析）
  • 13.5 階段 ③：Architecture Discovery（架構發現）
  • 13.6 階段 ④：Business Flow Discovery（業務流程還原）
  • 13.7 各技術類型的專用 Prompt
  • 13.8 階段 ⑦：Risk Analysis（風險分析）
  • 13.9 階段 ⑨：Modernization Plan（現代化計畫）
  • 13.10 逆向工程的品質控管
  • 13.11 本章實務案例
  • 13.12 本章注意事項

• 14. Framework Upgrade

  • 14.1 最重要的一條規則
  • 14.2 標準升版流程
  • 14.3 階段 ①：現況分析
  • 14.4 階段 ②：Migration Plan
  • 14.5 階段 ④：測試安全網
  • 14.6 階段 ⑥：分批執行
  • 14.7 各技術棧的升版要點
  • 14.8 Migration Report
  • 14.9 本章實務案例
  • 14.10 本章注意事項

• 15. Legacy Modernization

  • 15.1 現代化的八個階段
  • 15.2 Strangler Fig Pattern
  • 15.3 常見的現代化路徑
  • 15.4 Modular Monolith：投報率最高的中間站
  • 15.5 UI 現代化：JSP → SPA
  • 15.6 資料庫遷移
  • 15.7 本章實務案例
  • 15.8 本章注意事項

• 16. Testing

  • 16.1 為什麼測試對 Agent 特別重要
  • 16.2 Codex 的測試工作流
  • 16.3 各類測試與 Codex 的搭配
  • 16.4 Characterization Test：Legacy 專案的起手式
  • 16.5 整合測試與 Testcontainers
  • 16.6 E2E 測試
  • 16.7 測試品質的檢查
  • 16.8 本章實務案例
  • 16.9 本章注意事項

• 17. Git Workflow

  • 17.1 Git 是 Agent 的安全網
  • 17.2 標準工作流
  • 17.3 必須寫進 AGENTS.md 的 Git 規則
  • 17.4 審查 diff 的方法
  • 17.5 Commit 訊息
  • 17.6 分支策略
  • 17.7 處理衝突
  • 17.8 大型變更的處理
  • 17.9 本章實務案例
  • 17.10 本章注意事項

• 18. Code Review

  • 18.1 兩層 Review 模型
  • 18.2 codex review 指令
  • 18.3 企業級 Code Review Prompt
  • 18.4 專項 Review Prompt
  • 18.5 Review 結果的處理
  • 18.6 本章實務案例
  • 18.7 本章注意事項

第五部　安全與擴充（第 19–23 章）

• 19. Security

  • 19.1 威脅模型：Agent 帶來哪些新風險
  • 19.2 Prompt Injection
  • 19.3 不受信任的 Repository
  • 19.4 憑證與敏感資料保護
  • 19.5 供應鏈安全
  • 19.6 MCP 與 Plugin 的安全
  • 19.7 安全流程總覽
  • 19.8 安全檢查清單
  • 19.9 本章實務案例
  • 19.10 本章注意事項

• 20. Sandbox / Approval / Permission

  • 20.1 三個獨立但互補的機制
  • 20.2 Sandbox 三種模式
  • 20.3 Approval 三種政策
  • 20.4 Auto-review：把核准交給審查者 Agent
  • 20.5 Permission Profiles
  • 20.6 安全矩陣
  • 20.7 Rules / execpolicy
  • 20.8 選用決策樹
  • 20.9 Session 中途切換權限
  • 20.10 企業強制設定
  • 20.11 本章實務案例
  • 20.12 本章注意事項

• 21. MCP

  • 21.1 MCP 是什麼
  • 21.2 新增 MCP Server
  • 21.3 兩種傳輸方式
  • 21.4 認證
  • 21.5 工具核准模式
  • 21.6 MCP Server Instructions
  • 21.7 企業使用案例
  • 21.8 WebMCP / Site Tools：網站自己提供工具
  • 21.9 什麼時候不該用 MCP
  • 21.10 本章實務案例
  • 21.11 本章注意事項

• 22. AI Agent Team

  • 22.1 Subagents
  • 22.2 定義 Subagent
  • 22.3 呼叫方式
  • 22.4 企業 Agent Team 設計
  • 22.5 Agent 定義範本
  • 22.6 平行探索的實際用法
  • 22.7 Agent 協作的限制
  • 22.8 本章實務案例
  • 22.9 本章注意事項

• 23. Spec-Driven Development

  • 23.1 為什麼需要 Spec-Driven
  • 23.2 規格該包含什麼
  • 23.3 用 Codex 協助產生規格
  • 23.4 規格 → AGENTS.md → 實作的串接
  • 23.5 與 GitHub Spec Kit 等工具整合
  • 23.6 本章實務案例
  • 23.7 本章注意事項

第六部　企業導入（第 24–30 章）

• 24. Enterprise Development Workflow

  • 24.1 完整的企業工作流
  • 24.2 職責分工矩陣
  • 24.3 每個階段的具體做法
  • 24.4 Definition of Done
  • 24.5 本章實務案例
  • 24.6 本章注意事項

• 25. AI-assisted SDLC

  • 25.1 全生命週期地圖
  • 25.2 逐階段詳解
  • 25.3 生產環境的紅線
  • 25.4 自動化程度總表
  • 25.5 本章實務案例
  • 25.6 本章注意事項

• 26. DevSecOps

  • 26.1 完整的 DevSecOps 流程
  • 26.2 Shift Left：把安全左移到 Agent 這一層
  • 26.3 CI 中的安全掃描
  • 26.4 工具鏈整合
  • 26.5 用 Codex 分析掃描結果
  • 26.6 本章實務案例
  • 26.7 本章注意事項

• 27. CI/CD

  • 27.1 Codex 在 CI/CD 中的四種用法
  • 27.2 CI 中的基本用法
  • 27.3 用法 ①：分析 Build / Test 失敗
  • 27.4 用法 ②：PR 自動審查
  • 27.5 用法 ③：產生 Patch（權責分離）
  • 27.6 用法 ④：產生 Release Notes
  • 27.7 其他 CI 平台
  • 27.8 CI 中的成本控制
  • 27.9 本章實務案例
  • 27.10 本章注意事項

• 28. Enterprise Governance

  • 28.1 Enterprise Codex CLI Operating Model
  • 28.2 治理的九個核心問題
  • 28.3 Developer Policy
  • 28.4 Security Policy
  • 28.5 Audit Policy
  • 28.6 Data Protection Policy
  • 28.7 Production Policy
  • 28.8 治理成熟度模型
  • 28.9 本章實務案例
  • 28.10 本章注意事項

• 29. Team Adoption

  • 29.1 五階段導入計畫
  • 29.2 各階段的目標與檢核點
  • 29.3 度量指標
  • 29.4 常見的導入阻力與因應
  • 29.5 本章實務案例
  • 29.6 本章注意事項

• 30. Coding Standards

  • 30.1 傳統 Coding Standard 的困境
  • 30.2 三層結構
  • 30.3 完整的企業 Coding Standard（AGENTS.md 版）
  • 30.4 對應的 ArchUnit 強制
  • 30.5 本章實務案例
  • 30.6 本章注意事項

第七部　實戰與最佳化（第 31–34 章）

• 31. Practical Recipes

  • 31.1 Recipe 01：分析陌生 Repository
  • 31.2 Recipe 02：修 Bug
  • 31.3 Recipe 03：新增 REST API
  • 31.4 Recipe 04：新增 Vue 頁面
  • 31.5 Recipe 05：新增 Spring Service
  • 31.6 Recipe 06：新增 Unit Test
  • 31.7 Recipe 07：Refactoring
  • 31.8 Recipe 08：SQL 優化
  • 31.9 Recipe 09：Security Review
  • 31.10 Recipe 10：Performance Optimization
  • 31.11 Recipe 11：Framework Upgrade（分批執行）
  • 31.12 Recipe 12：Java 版本升級
  • 31.13 Recipe 13：Spring Boot 升級
  • 31.14 Recipe 14：Legacy 逆向工程
  • 31.15 Recipe 15：建立 Architecture Document
  • 31.16 Recipe 16：建立 API Document
  • 31.17 Recipe 17：建立 Test Plan
  • 31.18 Recipe 18：修 Build Error
  • 31.19 Recipe 19：修 CI Failure
  • 31.20 Recipe 20：Code Review
  • 31.21 Recipe 快速索引
  • 31.22 本章注意事項

• 32. Troubleshooting

  • 32.1 排查第一站
  • 32.2 問題速查表
  • 32.3 Sandbox 相關的深入排查
  • 32.4 「Agent 卡住」的處理
  • 32.5 「Agent 做了錯誤修改」的處理
  • 32.6 本章實務案例
  • 32.7 本章注意事項

• 33. Performance / Token / Context Optimization

  • 33.1 成本的來源
  • 33.2 好 Prompt vs 壞 Prompt 的成本差異
  • 33.3 十個具體的優化手法
  • 33.4 大型 Repository 的策略
  • 33.5 Session、壓縮（Compaction）與 Context 生命週期
  • 33.6 減少工具呼叫
  • 33.7 成本監控
  • 33.8 本章實務案例
  • 33.9 本章注意事項

• 34. Codex CLI vs Other AI Coding Agents

  • 34.1 主要工具概觀
  • 34.2 能力面向比較
  • 34.3 選型考量
  • 34.4 AGENTS.md 是跨工具的共通資產
  • 34.5 本章實務案例
  • 34.6 本章注意事項

第八部　情境、參考與附錄（第 35–50 章）

• 35. Codex CLI + VS Code

  • 35.1 推薦的工作模式
  • 35.2 實用設定
  • 35.3 /ide 指令
  • 35.4 審查 diff 的最佳流程
  • 35.5 本章注意事項

• 36. Codex CLI + Windows

  • 36.1 Windows 的三種執行環境
  • 36.2 原生 Windows 安裝
  • 36.3 原生 Windows Sandbox 的兩種模式
  • 36.4 PATH 與環境變數
  • 36.5 Windows 專屬的注意事項
  • 36.6 AGENTS.md 的 Windows 適配
  • 36.7 Windows 疑難排解
  • 36.8 本章實務案例
  • 36.9 本章注意事項

• 37. Codex CLI + Java Enterprise

  • 37.1 目標技術棧
  • 37.2 Java 專案的 AGENTS.md 核心區段
  • 37.3 Java 專案的完整驗證器組合
  • 37.4 完整的 Java Workflow
  • 37.5 Kafka / Redis / 容器的注意事項
  • 37.6 本章注意事項

• 38. Codex CLI + Vue Enterprise

  • 38.1 目標技術棧
  • 38.2 前端的驗證器困境
  • 38.3 前端 AGENTS.md 核心區段
  • 38.4 嚴格的 TypeScript 與 ESLint 設定
  • 38.5 元件測試的重點
  • 38.6 Micro Frontend 的注意事項
  • 38.7 本章注意事項

• 39. Codex CLI + Legacy Banking System

  • 39.1 典型的 Legacy Banking 技術棧
  • 39.2 銀行系統的特殊約束
  • 39.3 完整的現代化路徑
  • 39.4 各階段的關鍵 Prompt 要點
  • 39.5 銀行環境的操作流程
  • 39.6 本章注意事項

• 40. Complete Enterprise Case Study

  • 40.1 專案背景
  • 40.2 整體歷程
  • 40.3 逐階段詳解
  • 40.4 專案總結數據
  • 40.5 關鍵成功因素
  • 40.6 若沒有 Codex 會如何
  • 40.7 本章注意事項

• 41. Best Practices

  • 41.1 任務設計（1-8）
  • 41.2 安全與權限（9-16）
  • 41.3 版本控制（17-21）
  • 41.4 驗證與品質（22-28）
  • 41.5 知識沉澱（29-33）
  • 41.6 團隊與治理（34-36）

• 42. Anti-Patterns

  • 42.1 任務設計類
  • 42.2 安全類
  • 42.3 品質類
  • 42.4 流程與治理類

• 43. Learning Roadmap

  • 43.1 五個層級
  • 43.2 各層級的能力指標
  • 43.3 30 / 60 / 90 天學習計畫
  • 43.4 學習資源優先序

• 44. Team Training

  • 44.1 七天訓練課程
  • 44.2 Day 1：Codex CLI Fundamentals
  • 44.3 Day 2：Prompt + Repository Understanding
  • 44.4 Day 3：Web Development
  • 44.5 Day 4：Reverse Engineering
  • 44.6 Day 5：Framework Migration
  • 44.7 Day 6：Testing + Security
  • 44.8 Day 7：Enterprise AI SDLC
  • 44.9 整體評量

• 45. Enterprise Checklist

  • 45.1 Installation Checklist
  • 45.2 Configuration Checklist
  • 45.3 Security Checklist
  • 45.4 Repository Checklist
  • 45.5 AI Agent Checklist（每次任務）
  • 45.6 Development Checklist
  • 45.7 Testing Checklist
  • 45.8 Code Review Checklist
  • 45.9 Production Checklist
  • 45.10 Governance Checklist

• 46. Command Reference

  • 46.1 主要指令
  • 46.2 設定與認證
  • 46.3 診斷與維運
  • 46.4 全域旗標
  • 46.5 codex exec 專屬旗標
  • 46.6 Slash Commands（TUI 內）

• 47. Configuration Reference

  • 47.1 設定層級與優先順序
  • 47.2 模型與推理
  • 47.3 沙箱與核准
  • 47.4 網路與搜尋
  • 47.5 Features 旗標
  • 47.6 Agents / Subagents
  • 47.7 MCP
  • 47.8 專案文件與 AGENTS.md
  • 47.9 Hooks
  • 47.10 Model Providers
  • 47.11 Shell 環境政策
  • 47.12 歷史與遙測
  • 47.13 環境變數
  • 47.14 完整範例設定

• 48. Prompt Library

  • 48.1 01-analysis.md — 現況分析
  • 48.2 02-feature.md — 功能開發
  • 48.3 03-bugfix.md — Bug 修正
  • 48.4 04-refactoring.md — 重構
  • 48.5 05-testing.md — 測試
  • 48.6 06-review.md — Code Review
  • 48.7 07-security.md — 安全審查
  • 48.8 08-performance.md — 效能優化
  • 48.9 09-migration.md — 升版遷移
  • 48.10 10-reverse-engineering.md — 逆向工程
  • 48.11 11-documentation.md — 文件產出
  • 48.12 12-architecture.md — 架構分析與設計
  • 48.13 13-devops.md — DevOps / CI

• 49. Architecture Diagrams

  • 49.1 Codex CLI 整體架構
  • 49.2 Agent Loop
  • 49.3 Tool Calling 序列
  • 49.4 Sandbox 三層防護
  • 49.5 Approval 決策流程
  • 49.6 MCP 架構
  • 49.7 企業 Operating Model
  • 49.8 AI-assisted SDLC
  • 49.9 逆向工程流程
  • 49.10 Framework Migration 流程
  • 49.11 CI/CD 整合
  • 49.12 Multi-Agent 架構

• 50. Final Reference

  • 50.1 Quick Start
  • 50.2 Command Cheat Sheet
  • 50.3 Prompt Cheat Sheet
  • 50.4 Security Checklist（精簡版）
  • 50.5 Enterprise Checklist（精簡版）
  • 50.6 Troubleshooting Cheat Sheet
  • 50.7 Learning Roadmap（精簡版）
  • 50.8 七條核心原則
  • 50.9 Official References

1. Codex CLI Overview

1.1 Codex CLI 是什麼【Official】

Codex CLI 是 OpenAI 開發的開源 AI Coding Agent，以 Rust 撰寫，在開發者本機的 Terminal 中執行。

它不是「一個會回答程式問題的聊天視窗」。它是一個具備工具使用能力的軟體工程代理人：它可以自己讀取你的 Repository、自己決定要看哪些檔案、自己執行 shell 指令、自己跑測試、自己看錯誤訊息、自己修正，然後把改動留在你的 working tree 讓你 review。

用一句話定位：

Codex CLI 是一個「Agent Harness」——把大型語言模型包裝成能在真實檔案系統與真實命令列上工作的軟體工程師。

Source: OpenAI Codex 官方 Repository https://github.com/openai/codex

授權為 Apache-2.0，任何人都可以閱讀原始碼、稽核其行為、自行建置。這對企業導入是關鍵優勢：你可以驗證它到底做了什麼，而不是只能相信廠商的說明。

1.2 它解決什麼問題【建議】

傳統開發流程中，工程師大量時間並不是花在「想出解法」，而是花在下列這些可被機械化、但過去無法自動化的環節：

關鍵差異在於 feedback loop 的位置。聊天式工具的迴圈在「人」身上——人貼程式碼、人看回答、人複製貼上、人執行、人再貼錯誤。Codex CLI 把迴圈收進 Agent 內部，人只在**起點（意圖）與終點（審查）**介入。

1.3 Coding Agent 是什麼【建議】

一個系統要稱得上 Coding Agent，至少要同時具備四項能力：

1. 感知（Perception）——能主動讀取檔案系統、搜尋程式碼、查看 git 狀態，而不是等人餵。
2. 行動（Action）——能執行指令、修改檔案，改變外部世界的狀態。
3. 觀察（Observation）——能取得行動的結果（stdout、stderr、exit code、測試報告），並據以調整。
4. 自主迴圈（Autonomous Loop）——能在沒有人逐步指示的情況下，重複「行動→觀察→修正」直到達成目標或放棄。

少了第 3、4 項，就只是「會產生程式碼的聊天機器人」。

flowchart LR
    subgraph CHAT["AI Coding Assistant（聊天式）"]
        direction TB
        H1["人"] --> P1["貼上程式碼"]
        P1 --> M1["模型產生回答"]
        M1 --> H2["人複製貼上"]
        H2 --> R1["人執行"]
        R1 --> E1["人看到錯誤"]
        E1 --> H1
    end

    subgraph AGENT["AI Coding Agent（Codex CLI）"]
        direction TB
        H3["人：說明意圖"] --> A1["Agent 自行讀取 Repository"]
        A1 --> A2["Agent 自行決策"]
        A2 --> A3["Agent 執行工具"]
        A3 --> A4["Agent 觀察結果"]
        A4 --> A5{"達成目標？"}
        A5 -->|"否"| A2
        A5 -->|"是"| H4["人：審查 diff"]
    end

    style CHAT fill:#4a2020,color:#fff
    style AGENT fill:#2d5016,color:#fff

1.4 AI Coding Assistant 與 AI Coding Agent 的差異【建議】

最後一列是企業最常忽略的一列。能力提升的同時，風險面也從「內容風險」擴大到「執行風險」。 這是本手冊第 19、20、28 章存在的理由。

1.5 Codex CLI 與一般 Chatbot 的差異【建議】

1.6 Codex CLI 與傳統 IDE Assistant 的差異【建議】

IDE Assistant（行內補全、選取後改寫）的優勢是低延遲、貼著游標，適合「我知道要寫什麼，幫我打快一點」。

Codex CLI 的優勢是跨檔案、跨工具、可驗證，適合「我知道要達成什麼，但要動的地方我還不確定」。

兩者不互斥。實務上最有效率的組合是：

• 寫單一函式、補型別、改變數名 → IDE Assistant
• 跨 20 個檔案的重構、升版、補測試、逆向分析 → Codex CLI

第 35 章會說明如何在 VS Code 中同時使用兩者。

1.7 核心價值【建議】

1. 可執行（Executable）——能跑 build、跑測試、跑 lint，輸出因此可被機器驗證，而非只能靠人肉閱讀。
2. 可稽核（Auditable）——所有變更都落在 git working tree，git diff 就是稽核介面。
3. 可控制（Controllable）——Sandbox 決定技術邊界，Approval 決定何時停下來問人。
4. 可規範（Governable）——AGENTS.md 把團隊規範餵給 Agent；config.toml 與 requirements.toml 讓管理者統一設定。
5. 可自動化（Automatable）——codex exec 讓同一套能力進入 CI/CD。
6. 開源（Open Source）——Apache-2.0，行為可稽核、可自行建置、可在企業內部審查。

1.8 適合與不適合的工作【建議】

非常適合：

不適合，或必須人主導：

📌 判準【建議】：問自己一個問題——「這件事有沒有一個機器可以判斷的成功標準？」 有（編譯通過、測試綠燈、lint 乾淨、效能數字改善），Codex CLI 就很強。沒有（「這個設計比較好」、「客戶應該是這個意思」），就是人的工作。

1.9 整體運作圖【建議】

flowchart TD
    DEV["Developer<br/>提供意圖與驗收標準"] --> CLI["Codex CLI<br/>Agent Harness"]
    CLI --> CTX["Context 組裝<br/>AGENTS.md + Repository + History"]
    CTX --> MODEL["AI Model<br/>Astra / 5.6 Sol / Terra / Luna"]
    MODEL --> LOOP["Agent Loop<br/>決策 → 行動 → 觀察"]
    LOOP --> TOOLS["Tools"]

    TOOLS --> FS["File System<br/>讀取 / 修改檔案"]
    TOOLS --> SH["Shell<br/>執行命令"]
    TOOLS --> GIT["Git<br/>status / diff / log"]
    TOOLS --> TEST["Test / Build<br/>mvn / npm / pytest"]
    TOOLS --> SEARCH["Search<br/>grep / 檔案搜尋"]
    TOOLS --> WEB["Web Search<br/>受 web_search 設定控制"]
    TOOLS --> MCP["MCP<br/>外部系統整合"]

    FS --> GATE
    SH --> GATE
    GIT --> GATE
    TEST --> GATE
    SEARCH --> GATE
    WEB --> GATE
    MCP --> GATE

    GATE["Sandbox + Approval + Rules<br/>技術邊界與人工關卡"] --> OBS["Observation<br/>stdout / stderr / exit code"]
    OBS --> LOOP
    LOOP --> DIFF["Working Tree Diff"]
    DIFF --> REVIEW["Human Review"]

    style DEV fill:#1e3a5f,color:#fff
    style GATE fill:#7a3b12,color:#fff
    style REVIEW fill:#2d5016,color:#fff
    style MODEL fill:#3d2b5f,color:#fff

這張圖有三個必須理解的重點：

1. 所有工具呼叫都會經過 Sandbox / Approval / Rules 這道關卡——不是只有「寫檔案」才受管，git、mvn、npm 這些衍生的子行程一樣受限（詳見第 20 章）。
2. Observation 會回流到 Agent Loop——這是 Agent 與 Chatbot 的根本差異。
3. 終點是 Human Review，不是 Production——這是本手冊反覆強調的紅線。

1.10 本章實務案例【建議】

情境：某銀行核心系統團隊接手一個 12 年歷史的 Java Web 專案，原開發人員均已離職，無架構文件、無單元測試，只有一份過時的 Word 規格書。

傳統做法：指派 2 名資深工程師花 3 週閱讀程式碼，產出一份不完整的架構說明，且知識僅存在該 2 人腦中。

用 Codex CLI 的做法：

關鍵在第 5 階段：工程師的角色從「考古學家」變成「審查者」。人的時間花在判斷對錯，而不是花在讀 12 年前的程式碼。這是 Codex CLI 在企業場景中最大的價值。

完整可執行的做法見第 13 章 與第 40 章。

1.11 本章注意事項

• ⚠️ 不要把 Codex CLI 當成「更聰明的補全工具」。它的能力邊界與風險模型都和補全工具完全不同，用同一套心態使用會出事。
• ⚠️ 第一次使用務必從 read-only 開始。先讓它「只讀不寫」，建立對它行為的信任感之後再開放寫入權限。
• ⚠️ 沒有版本控制就不要用。Codex CLI 的安全網是 git diff 與 git checkout。沒有 git，你沒有回復機制。
• ⚠️ Agent 的輸出永遠需要人審查。測試綠燈只代表「沒有違反已有的測試」，不代表「做對了」。
• 📌 官方文件連結請一律使用 learn.chatgpt.com/docs/*，舊的 developers.openai.com/codex/* 雖會轉址，但內容索引已不同。

2. Codex Ecosystem

2.1 Codex 不只是一個 CLI【Official】

Codex 是一個產品家族，CLI 只是其中一個入口。理解整個生態系，才知道什麼工作該用哪個入口。

flowchart TD
    CORE["OpenAI Codex<br/>共用同一組模型與 Agent 能力"]

    CORE --> CLI["Codex CLI<br/>Terminal"]
    CORE --> IDE["Codex IDE Extension<br/>VS Code / Cursor / Windsurf"]
    CORE --> APP["Codex App<br/>桌面應用程式"]
    CORE --> CLOUD["Codex Cloud<br/>chatgpt.com/codex"]
    CORE --> SDK["Codex SDK<br/>TypeScript / Python"]
    CORE --> GHA["GitHub Action<br/>openai/codex-action"]

    CLI --> LOCAL["本機 Repository<br/>本機 Shell"]
    IDE --> LOCAL
    APP --> LOCAL
    CLOUD --> REMOTE["雲端容器<br/>遠端 Repository"]
    SDK --> PROG["自建工具 / CI Pipeline"]
    GHA --> CI["GitHub Workflow"]

    CLI -.->|"共用設定"| CONF["$CODEX_HOME<br/>config.toml / AGENTS.md<br/>agents/ / rules/ / MCP"]
    IDE -.->|"共用設定"| CONF
    APP -.->|"共用設定"| CONF

    style CORE fill:#3d2b5f,color:#fff
    style CLI fill:#2d5016,color:#fff
    style CONF fill:#1e3a5f,color:#fff

📌 關鍵事實【Official】：ChatGPT 桌面應用程式、Codex CLI 與 IDE 擴充功能共用同一份 MCP 設定（同一個 Codex host）。也就是說，你在 ~/.codex/config.toml 設定的 MCP server，三個入口都吃得到。

Source: OpenAI 官方 MCP 文件 https://learn.chatgpt.com/docs/extend/mcp

2.2 各入口的定位與選用【建議】

2.3 完整能力對照表【Official / 建議】

標示：✅ 支援；➖ 不適用或無此概念；⚠️ 支援但有前提

企業選型建議【建議】：

• 預設主力用 CLI。它是能力最完整、最可腳本化、最可稽核的入口。
• IDE Extension 作為 diff 審查介面，而不是主要的任務發起處。
• CI 場景一律用 codex exec 或 GitHub Action，不要在 CI 裡跑互動式 TUI。
• Codex Cloud 只用於不碰內部資料的工作（例如 OSS 專案、公開文件）。涉及內網或客戶資料的一律留在本機。

2.4 Codex CLI 與 Codex Cloud 的關係【Official】

兩者不是「本機版 vs 雲端版」的替代關係，而是可以互通的：

典型用法：在通勤時用手機／網頁發起一個雲端任務，回到座位後用 codex apply 把結果拉回本機，在本機跑完整測試再決定要不要 commit。

⚠️ 安全提醒【建議】：codex apply 會把雲端產生的變更寫進你的本機工作區。套用前務必先 git status 確認工作區乾淨，套用後務必 git diff 逐行檢視。不要把它當成「自動同步」使用。

2.5 Codex SDK 概觀【Official】

當你需要把 Codex 嵌進自己的程式（內部平台、批次工具、自訂 CI 步驟）時使用 SDK。

TypeScript：套件 @openai/codex-sdk，需要 Node.js 18+。

npm install @openai/codex-sdk

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run("Make a plan to diagnose and fix the CI failures");

Python：套件 openai-codex，需要 Python 3.10+。

pip install openai-codex

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(model="gpt-5.6-terra")
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

兩者都支援對同一個 thread 重複呼叫 run() 以延續對話，也支援用 thread ID 恢復先前的 thread。Python SDK 另外提供 Sandbox preset 控制檔案系統存取層級。

Source: OpenAI 官方 Codex SDK 文件 https://learn.chatgpt.com/docs/codex-sdk

什麼時候用 SDK、什麼時候用 codex exec【建議】：

2.6 GitHub Action 概觀【Official】

官方提供 openai/codex-action@v1，讓 Codex 直接在 GitHub Workflow 中執行。

name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md

主要輸入參數：

Source: OpenAI 官方 GitHub Action 文件 https://learn.chatgpt.com/docs/github-action

第 27 章 會提供完整的 CI 樣板，包括「唯讀分析 job 產生 patch → 另一個具寫入權限的 job 套用 patch」這種權責分離的安全模式。

2.7 延伸閱讀：生態系的其他成員【Community】

以下能力屬於 Codex 產品家族，但不在本手冊（CLI 深度）的範圍內。需要時請參閱同目錄《OpenAI Codex生態系教學手冊》或官方文件：

⚠️ 這些能力更新頻率極高，本手冊不逐一收錄，避免提供過期資訊。請一律以 https://learn.chatgpt.com/docs 為準。

2.8 第三方整合與新興介面【Official】

除了前述的主要入口，Codex 生態系在 2026 年持續擴張。以下能力與 CLI 使用者的日常有直接關聯，或會影響企業的導入決策——列出以避免讀者低估生態系的邊界。

2.8.1 第三方平台整合【Official】

📌 對企業導入的意義【建議】：許多企業的第一個阻礙是「我們不用 GitHub」。GitLab 整合的存在讓 Codex 的 CI/CD 與 code review 能力不再綁定單一平台。第 27.7 節 的其他 CI 平台做法（GitLab CI、Jenkins、Azure DevOps）與此互補——即使沒有官方整合，codex exec 也永遠是可行的最低共同分母。

2.8.2 Browser 與 Computer Use【Official】

⚠️ 安全立場【建議】：Computer Use 與 Browser 把 Agent 的行動半徑從「檔案系統與命令列」擴大到「任何你登入過的網頁服務」。這是本手冊所有能力中攻擊面最大的一組。

企業建議：預設關閉；若要使用，必須搭配 approval_policy 的互動式核准（Computer Use 存取新網域屬於會被送審的請求類型，見第 20.4 節），且絕不在已登入生產系統管理後台的瀏覽器 profile 上使用。

2.8.3 其他值得知道的能力【Official】

🎯 本手冊的取捨【建議】：以上能力多數屬於「產品面」，與 CLI 的工程實作關聯較弱，本手冊僅列出定位。需要完整產品面說明者，請參閱同目錄的《OpenAI Codex生態系教學手冊》與官方文件站。但 Automations 與 Long-running work 例外——它們與企業的長跑任務直接相關，本手冊在第 9.12 節（worktree）與第 24 章（企業工作流）中以實作角度涵蓋。

2.8.4 功能成熟度分級【Official】

官方為所有功能定義了五個成熟度階段。這是企業選型時最該先看的一張表——它直接對應本手冊第 可信度標示制度 中的【Experimental】標記：

⚠️ 成熟度會變。 官方的功能成熟度頁面（/docs/feature-maturity）本身不提供固定的功能對照表，實際狀態需查各功能頁面與 Changelog。

企業建議【建議】：把「季度覆核各依賴功能的成熟度階段」寫進第 28 章 的稽核項目。任何被標為 Deprecated 的功能，應在下一季度前完成替換。

2.9 本章實務案例【建議】

情境：某團隊 15 人，同時有本機開發、PR 審查、夜間批次分析三種需求，不知道該怎麼配置。

建議配置：

flowchart LR
    subgraph LOCAL["本機（每位工程師）"]
        A["Codex CLI<br/>主力：重構 / 升版 / 測試"]
        B["IDE Extension<br/>輔助：diff 審查"]
    end

    subgraph CI["CI（GitHub Actions）"]
        C["codex-action<br/>PR 自動第一輪審查"]
        D["codex exec --json<br/>CI 失敗自動分析"]
    end

    subgraph PLATFORM["內部平台（平台組維護）"]
        E["Codex SDK<br/>批次逆向分析 / 文件產生"]
    end

    CONF["共用設定<br/>企業 requirements.toml<br/>+ 專案 AGENTS.md"]

    CONF --> A
    CONF --> B
    CONF --> C
    CONF --> D
    CONF --> E

    style CONF fill:#1e3a5f,color:#fff
    style LOCAL fill:#2d5016,color:#fff
    style CI fill:#7a3b12,color:#fff

配置要點：

1. 設定集中化——企業層級的強制設定放 requirements.toml（第 7 章），專案慣例放 AGENTS.md（第 8 章），三種入口共用同一套規範。
2. 權限分層——本機開發用 workspace-write，CI 審查用 read-only，只有專責的 apply job 才有寫入權。
3. 成本可見——SDK 的批次任務集中在平台組，方便統一觀測 token 用量（第 33 章）。

2.10 本章注意事項

• ⚠️ 不要在 CI 裡跑互動式 codex。TUI 需要終端機互動，在 CI 中會卡住或行為異常。一律使用 codex exec。
• ⚠️ Codex Cloud 執行在雲端容器中，無法存取你的內網、內部資料庫或私有套件庫。有這些需求的任務必須留在本機或自管 Runner。
• ⚠️ codex apply 會改動本機檔案。務必在乾淨的 working tree 上執行，並逐行審查。
• 📌 MCP 設定是三個本機入口共用的。在 CLI 加了一個有寫入能力的 MCP server，IDE 與 App 也會拿到——設定時要考慮到這一點。
• 📌 GitHub Action 的 safety-strategy 預設為 drop-sudo。不要為了讓某個步驟跑過就改成 unsafe，除非你在 Windows Runner 上且已理解其含意。

3. Codex CLI Architecture

3.1 什麼是 Agent Harness【建議】

大型語言模型本身只會做一件事：給定一段文字，產生下一段文字。它沒有記憶、不能讀檔、不能執行指令、不知道現在幾點。

Agent Harness（代理人外殼）就是把模型包裝成「能在真實世界工作的代理人」的那一層軟體。 它負責：

📌 關鍵理解【建議】：模型負責決策，Harness 負責執行與管控。 你在 config.toml 裡設定的每一項、在 AGENTS.md 裡寫的每一條規則，都是在調整 Harness 的行為——而不是在「說服模型」。這是所有企業治理手段的著力點。

3.2 分層架構【建議】

flowchart TD
    subgraph L1["① 介面層 Interface Layer"]
        TUI["TUI<br/>互動式終端機介面"]
        EXEC["codex exec<br/>非互動模式"]
        APPSRV["app-server<br/>供 IDE / App 連接"]
    end

    subgraph L2["② Harness 層 Agent Harness"]
        SESS["Session / State<br/>對話歷史、thread、恢復"]
        CTXB["Context Builder<br/>組裝送給模型的內容"]
        TOOLD["Tool Registry<br/>宣告可用工具"]
        LOOPC["Loop Controller<br/>決定何時繼續 / 停止"]
    end

    subgraph L3["③ 決策層 Model Layer"]
        MDL["Model Inference<br/>Astra / 5.6 Sol / Terra / Luna"]
        REASON["Reasoning Effort<br/>low → medium → high → xhigh → max → ultra"]
    end

    subgraph L4["④ 管控層 Policy Layer"]
        SB["Sandbox<br/>技術邊界"]
        AP["Approval<br/>人工關卡"]
        RL["Rules / execpolicy<br/>命令白名單"]
        HK["Hooks<br/>生命週期攔截"]
    end

    subgraph L5["⑤ 執行層 Execution Layer"]
        FSX["File System"]
        SHX["Shell / Subprocess"]
        NETX["Network<br/>預設關閉"]
        MCPX["MCP Client"]
    end

    L1 --> L2
    L2 --> L3
    L3 -->|"Tool Call"| L2
    L2 --> L4
    L4 -->|"允許"| L5
    L4 -->|"拒絕 / 詢問"| L2
    L5 -->|"Observation"| L2

    style L2 fill:#1e3a5f,color:#fff
    style L3 fill:#3d2b5f,color:#fff
    style L4 fill:#7a3b12,color:#fff
    style L5 fill:#4a2020,color:#fff

閱讀這張圖的三個重點：

1. 第 ③ 層（模型）沒有直接連到第 ⑤ 層（執行）。模型只能「請求」執行，實際執行必須穿過第 ④ 層管控。這是安全模型的基石。
2. Observation 回流到第 ② 層，由 Harness 決定要送多少內容回模型（這關係到 token 成本，見第 33 章）。
3. 第 ④ 層是企業唯一能可靠管控 Agent 的地方。Prompt 可以被繞過（prompt injection），Sandbox 不行。

3.3 一次完整的 Agent Turn【建議】

sequenceDiagram
    participant U as User
    participant H as Harness
    participant M as Model
    participant P as Policy（Sandbox/Approval/Rules）
    participant E as Execution

    U->>H: "把 UserService 的例外處理統一"
    H->>H: 讀取 AGENTS.md、組裝 context
    H->>M: system + AGENTS.md + 使用者訊息 + 工具清單
    M-->>H: Tool Call: 搜尋 UserService
    H->>P: 檢查：read 操作
    P-->>H: 允許（read-only 也允許）
    H->>E: 執行搜尋
    E-->>H: 檔案清單與片段
    H->>M: Observation（搜尋結果）
    M-->>H: Tool Call: 讀取 UserService.java
    H->>P: 檢查
    P-->>H: 允許
    H->>E: 讀取檔案
    E-->>H: 檔案內容
    H->>M: Observation
    M-->>H: Tool Call: 修改 UserService.java
    H->>P: 檢查：write 操作
    alt sandbox = read-only
        P-->>H: 拒絕 → 需要 approval
        H->>U: 請求核准
        U-->>H: 核准 / 拒絕
    else sandbox = workspace-write 且在 workspace 內
        P-->>H: 允許
    end
    H->>E: 寫入檔案
    E-->>H: 成功
    H->>M: Observation
    M-->>H: Tool Call: mvn -q test
    H->>P: 檢查：執行指令 + 可能需要網路
    P-->>H: 允許（但無網路）
    H->>E: 執行 mvn
    E-->>H: exit code 1 + 測試失敗訊息
    H->>M: Observation（失敗訊息）
    M-->>H: Tool Call: 修正測試中發現的問題
    Note over M,E: 迴圈直到測試通過
    M-->>H: 最終回覆：完成，說明改了什麼
    H->>U: 顯示摘要 + working tree diff

這張序列圖是理解 Codex CLI 的核心。請特別注意 mvn -q test 失敗後 Agent 自己繼續修正——這一步就是 Agent 與 Chatbot 的分水嶺。

3.4 核心概念逐一說明【Official / 建議】

Context【建議】

送給模型的完整輸入。在 Codex CLI 中大致由以下部分組成：

📌 Context 是有限資源。工具結果（尤其是大檔案內容與冗長的 build log）會迅速吃光預算。第 33 章專門處理這件事。

除錯用指令【Official】：codex debug prompt-input 可以把「模型實際看到的 prompt」以 JSON 印出來。當你懷疑 AGENTS.md 沒被讀到時，這是最直接的驗證方式。

Tool 與 Tool Call【建議】

Harness 向模型宣告一組可用工具（讀檔、寫檔、執行 shell、搜尋、web search、MCP 工具⋯⋯）。模型的輸出若是一個 Tool Call，就代表「我要用這個工具，參數是這些」。

實際執行的永遠是 Harness。模型從來沒有直接碰過你的檔案系統。

config.toml 中的 features.shell_tool 可控制是否啟用預設的 shell 執行工具。

Observation【建議】

工具執行後的結果（stdout、stderr、exit code、檔案內容、diff），經 Harness 整理後送回模型。

Observation 的品質直接決定 Agent 的能力上限。這也是為什麼「有測試的專案」Agent 表現遠好於「沒測試的專案」——測試提供了高品質的 Observation。

State 與 Session【Official】

Codex CLI 會保存 session（對話紀錄），支援：

保存行為由 history.persistence 控制（save-all 或 none），檔案大小上限由 history.max_bytes 控制。

⚠️ 企業提醒【建議】：session transcript 中可能包含程式碼、設定、甚至不慎貼入的敏感資訊。若在受規範的環境中使用，請評估 history.persistence = "none"，並將 $CODEX_HOME 納入端點資料保護範圍。詳見第 28 章。

codex exec --ephemeral 可以在非互動模式下完全不落地 session 檔案，適合 CI。

Approval【Official】

決定「Agent 在跨越邊界前，何時必須停下來問人」。三種政策：

另有 granular 形式可分別控制不同類別，以及 approvals_reviewer 可將部分核准交給自動審查者。完整說明見第 20 章。

Sandbox【Official】

決定「技術上允許做什麼」。三種模式：

📌 最重要的一句話【Official】：沙箱套用於「衍生出來的指令」，不只是內建的檔案操作。 也就是說 git、npm、mvn、pytest 這些子行程一樣繼承同一組邊界。

平台實作【Official】：

Source: OpenAI 官方 Sandboxing 文件 https://learn.chatgpt.com/docs/sandboxing

Network【Official】

預設關閉。 這是刻意的安全設計——沒有網路，就大幅降低了資料外洩與 prompt injection 導致的外連風險。

需要時可透過：

[sandbox_workspace_write]
network_access = true

或使用網路代理搭配網域白名單：

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

⚠️ 官方安全警告【Official】：「在 Codex 中啟用網路存取或網頁搜尋時請保持謹慎。Prompt injection 可能導致 Agent 抓取並遵循不受信任的指令。」

Source: https://learn.chatgpt.com/docs/agent-approvals-security

Filesystem 與 Command Execution【Official】

workspace-write 模式下，可寫範圍限於工作區。若需額外可寫目錄（例如 pyenv 的 shims、Maven 的 local repository），用：

[sandbox_workspace_write]
writable_roots = ["/Users/YOU/.pyenv/shims"]

指令執行的環境變數則由 [shell_environment_policy] 控制——這是防止金鑰外洩到子行程的重要機制：

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

📌 企業必做【建議】：把所有雲端憑證、資料庫密碼、內部 token 的環境變數 pattern 加入 filters 排除清單。這是成本極低、效益極高的一道防線。

3.5 為什麼 Codex CLI 不是單純的 LLM Chat Interface【建議】

這是本章最重要的一節。用五個具體差異說明：

第 2 點是所有企業風險的源頭，第 5 點是所有企業控制的答案。

換個角度看：

Chat Interface  =  Model
Codex CLI       =  Model  +  Tools  +  Loop  +  Policy  +  State

多出來的四項，每一項都同時是能力來源與風險來源。理解這個對稱性，就理解了本手冊後半所有治理章節的必要性。

3.6 本章實務案例【建議】

情境：某團隊導入 Codex CLI 兩週後，一位工程師回報「Agent 把我的 ~/.m2/settings.xml 改壞了」。

分析：

1. 該工程師使用 --sandbox danger-full-access（因為看到教學文章這樣寫，覺得比較「不會卡」）。
2. Agent 在排解 Maven 依賴問題時，判斷 settings.xml 的 mirror 設定有誤，直接修改。
3. 因為 danger-full-access 無沙箱、無核准，這個動作沒有任何關卡。
4. 該檔案不在 git 版控中，無法用 git checkout 回復。

根因：不是 Agent「失控」，而是架構的第 ④ 層被完全關閉。Agent 的行為在其權限範圍內完全合理。

修正措施：

這個案例的教訓【建議】：Agent 的安全性不是靠 prompt 寫得好，而是靠第 ④ 層的設定。任何「請不要修改我的設定檔」這類 prompt 指示，都可能被後續的推理過程覆蓋掉。只有 Sandbox 是硬邊界。

3.7 本章注意事項

• ⚠️ 模型不等於 Agent。換一個更強的模型不會讓不安全的設定變安全。
• ⚠️ Sandbox 管到子行程。你以為只是「跑個測試」，但測試腳本裡的 curl、docker、rm 一樣受同一組邊界規範——這是好事，別想辦法繞過它。
• ⚠️ 網路預設關閉是刻意的。開啟前先問：這個任務真的需要嗎？能不能改用離線的套件快取？
• ⚠️ danger-full-access 在任何日常開發情境都不應該是預設值。官方文件本身就標註 (not recommended)。
• 📌 想知道 Agent 到底看到了什麼，用 codex debug prompt-input；想知道它為什麼被擋，看第 20 章與第 32 章。
• 📌 [shell_environment_policy.filters] 是被嚴重低估的安全設定。第一天就該設好。

4. Agent Loop

4.1 Agent Loop 是什麼【建議】

Agent Loop 是 Codex CLI 的執行引擎：一個「模型決策 → 工具執行 → 觀察結果 → 再決策」的循環，持續到任務完成、失敗、或需要人介入。

一次使用者請求，可能觸發數十次這樣的循環。

flowchart TD
    REQ["User Request<br/>使用者的意圖"] --> UND["① Understand<br/>理解要達成什麼"]
    UND --> PLAN["② Plan<br/>拆解成可執行步驟"]
    PLAN --> INSP["③ Inspect<br/>讀檔、搜尋、查 git 狀態"]
    INSP --> REAS["④ Reason<br/>根據看到的內容推理"]
    REAS --> ACT["⑤ Act<br/>修改檔案 / 執行指令"]
    ACT --> POL{"Policy Gate<br/>Sandbox / Approval / Rules"}
    POL -->|"拒絕"| ASK["請求人工核准"]
    ASK -->|"核准"| OBS
    ASK -->|"駁回"| REAS
    POL -->|"允許"| OBS["⑥ Observe<br/>stdout / stderr / exit code"]
    OBS --> VAL["⑦ Validate<br/>build 過了嗎？測試綠了嗎？"]
    VAL --> CHK{"符合目標？"}
    CHK -->|"否"| CORR["⑧ Correct<br/>分析失敗原因"]
    CORR --> REAS
    CHK -->|"是"| DONE["⑨ Complete<br/>產出摘要與 diff"]
    DONE --> HUM["Human Review"]

    style REQ fill:#1e3a5f,color:#fff
    style POL fill:#7a3b12,color:#fff
    style VAL fill:#2d5016,color:#fff
    style HUM fill:#2d5016,color:#fff
    style CORR fill:#4a2020,color:#fff

4.2 九個階段逐一說明【建議】

① Understand（理解）

Agent 讀取你的 prompt、AGENTS.md、以及目前的工作目錄狀態，建立對「要達成什麼」的理解。

這一步失敗的典型症狀：Agent 做了一件你沒要求的事，或做的事只解決了問題的一半。

改善方式：把驗收標準寫清楚（第 10 章的 Prompt Template）。

② Plan（規劃）

Agent 在動手前先拆解步驟。互動模式下可用 /plan 明確要求它先出計畫再動手。

為什麼重要【建議】：先看計畫，是成本最低的糾錯時機。發現方向錯了，改一句話就好；等它改完 30 個檔案才發現，要重來。

📌 強烈建議的工作模式：任何超過「改一個檔案」規模的任務，都先要求 Agent 產出計畫並由你確認，再讓它執行。

③ Inspect（勘查）

Agent 主動搜尋與讀取。這一步佔用大量 token，也是 Agent 表現好壞的關鍵。

你可以幫它的事：在 prompt 中直接指出相關檔案路徑，可以省下大量摸索。

④ Reason（推理）

模型根據所見內容決定下一步。model_reasoning_effort 直接影響這一步的深度：

⑤ Act（行動）

實際修改檔案或執行指令。這是唯一會產生副作用的階段，也是唯一需要 Policy Gate 的階段。

⑥ Observe（觀察）

取得執行結果。品質層級由高到低：

這就是「先建立測試再改動」的技術理由——不是為了流程正確，而是為了提供高品質的 Observation 讓 Agent 能自我修正。

⑦ Validate（驗證）

Agent 判斷結果是否符合目標。判準來自兩處：

1. 你給的驗收標準（prompt 中明確寫的）
2. 可執行的驗證器（compile / test / lint / build）

沒有第 2 項時，Agent 只能靠第 1 項自我評估——這是不可靠的。

⑧ Correct（修正）

失敗時分析原因並回到 ④。這是 Agent 最有價值的能力，也是最消耗 token 的環節。

⚠️ 要注意「修正迴圈失控」：Agent 可能在同一個問題上反覆嘗試而沒有進展（見第 32 章「Agent Gets Stuck」）。發現這種情況時應中斷，補充資訊後重新開始，而不是讓它一直跑。

⑨ Complete（完成）

產出摘要與變更清單。此時任務尚未結束——還需要人審查。

4.3 Agent Loop 與 Prompt → Response 的根本差異【建議】

flowchart LR
    subgraph T["傳統：Prompt → Response"]
        direction LR
        P["Prompt"] --> R["Response"]
        R --> END1["結束"]
    end

    subgraph A["Agent Loop"]
        direction LR
        P2["Prompt"] --> D["Decide"]
        D --> X["Execute"]
        X --> O["Observe"]
        O --> V{"完成？"}
        V -->|"否"| D
        V -->|"是"| R2["Response + 檔案變更"]
    end

    style T fill:#4a2020,color:#fff
    style A fill:#2d5016,color:#fff

📌 成本觀念【建議】：Agent Loop 的成本與迴圈次數成正比，而迴圈次數與任務的模糊程度成正比。一個定義清楚的任務可能 5 次迴圈完成；同一件事講得含糊，可能跑 40 次還做錯。寫好 prompt 是最直接的成本控制手段（第 10、33 章）。

4.4 影響 Loop 效率的六個因素【建議】

4.5 一個真實的 Loop 展開範例【建議】

任務：「OrderService.cancelOrder() 在訂單已出貨時應該拋出 IllegalStateException，現在沒有。請修正並補測試。」

觀察重點：

• 第 7 輪與第 9 輪的失敗是正常且有價值的。沒有這兩次失敗，Agent 不會知道要加 import、不會發現既有測試被影響。
• 第 10 輪展現了 Agent 相對於「一次產生程式碼」的優勢：它發現了連鎖影響。
• 如果這個專案沒有測試，Agent 會停在第 6 輪，交出一份看起來正確但從未被驗證的程式碼，而且不會發現既有測試被破壞（因為根本沒有）。

4.6 本章實務案例【建議】

情境：同一個升版任務，兩位工程師的做法與結果。

工程師 A 的 prompt：

幫我把專案升到 Spring Boot 4。

結果：Agent 直接改 pom.xml 版本號 → build 失敗 → 修一個錯 → 又冒三個錯 → 反覆 40 餘輪 → context 用盡 → 最後留下一個編不過的專案與大量無法審查的 diff。

工程師 B 的 prompt（分三次）：

【第一次 — 唯讀分析】
以 read-only 模式分析本專案，產出 Spring Boot 3.x → 4.x 的升級評估：
1. 目前使用的 Spring Boot 版本與所有 Spring 相關依賴版本
2. 對照官方 Migration Guide，列出本專案實際會踩到的 Breaking Changes（只列實際用到的）
3. 第三方依賴的相容性風險
4. 建議的升級批次順序，每批的範圍與驗證方式
不要修改任何檔案。輸出到 docs/migration/spring-boot-4-assessment.md。

【第二次 — 建立安全網】
在動任何升級之前，先補齊 characterization test：
針對 assessment 文件中標示為「高風險」的 5 個模組，
為其現有行為建立測試（不是測「應該怎樣」，是測「現在就是這樣」）。
驗收：mvn -q test 全綠，且新增測試覆蓋這 5 個模組的主要對外行為。

【第三次 — 分批執行】
執行 assessment 文件中的第 1 批：僅升級 <批次範圍>。
每完成一個檔案就執行 mvn -q compile；全部完成後執行 mvn -q test。
若測試失敗，先分析是「行為真的改變」還是「測試需要調整」，說明後再修。
不要動第 2 批以後的範圍。

結果：三次任務各自的迴圈次數都在合理範圍，每次的 diff 都可以人工審查，且每一步都有驗證。

差異的本質：不是模型變聰明了，而是 B 把一個「迴圈次數不可控」的任務，拆成三個「迴圈次數可控且有驗證器」的任務。

4.7 本章注意事項

• ⚠️ 迴圈次數不可控 = 成本與品質都不可控。任何無法在心裡估出「大概幾輪能完成」的任務，都太大了，先拆。
• ⚠️ 沒有驗證器的任務，Agent 只能自我評估。自我評估不可靠。優先建立 compile / test / lint 三種驗證器。
• ⚠️ 看到 Agent 在原地打轉就中斷它。反覆嘗試同一個方向而沒進展，代表它缺少關鍵資訊——補資訊比讓它繼續試便宜得多。
• 📌 善用 /plan。先看計畫再執行，是投報率最高的一個習慣。
• 📌 失敗的 Observation 是資產，不是問題。一個會失敗的測試比沒有測試好一百倍。
• 📌 Reasoning effort 不是越高越好。機械性任務用 high 只是把錢和時間燒掉。

5. Installation

5.1 安裝方式總覽【Official】

Codex CLI 以 Rust 撰寫，發行為預先建置的原生執行檔。官方提供四種安裝途徑：

📌 企業選擇建議【建議】：

• 一般開發者 → install script。最少依賴、最快。
• 需要統一釘選版本的團隊 → npm。可在內部 registry 鏡像特定版本，避免每人版本不同。
• 需要完整供應鏈稽核的高度受規範環境 → 從原始碼建置，並在內部產出簽章後的二進位檔。

5.2 macOS / Linux 安裝【Official】

官方 install script（推薦）：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Homebrew（僅 macOS）：

brew install --cask codex

npm：

npm install -g @openai/codex

安裝後驗證：

codex --version
codex doctor

Source: OpenAI Codex 官方 Repository README https://github.com/openai/codex

5.3 Windows 安裝【Official】

官方 install script（推薦），在 PowerShell 中執行：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm：

npm install -g @openai/codex

⚠️ Version Note：Windows 不再「必須」使用 WSL

官方 sandboxing 文件已明列 Windows 原生沙箱（PowerShell） 為受支援的實作，README 也提供原生的 install.ps1 安裝路徑。

但 Repository 內的 docs/install.md 仍寫「macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2」——那份文件講的是「從原始碼建置 Codex 本身」的開發環境需求，不是一般使用者的安裝需求。兩者不衝突，但網路上大量文章把它誤引為「Windows 一定要用 WSL」。

實務建議見第 36 章：原生與 WSL2 各有適用情境，Java / .NET 專案多半用原生較順，需要大量 POSIX 工具鏈的專案用 WSL2 較順。

5.4 從原始碼建置【Official】

適用於需要稽核或修改 Codex 本身的情境。

系統需求（官方 docs/install.md）：

git clone https://github.com/openai/codex.git
cd codex/codex-rs
# 依官方 docs/install.md 安裝 Rust toolchain 與相依元件後
cargo run --bin codex -- "explain this codebase to me"

Source: https://github.com/openai/codex/blob/main/docs/install.md

5.5 安裝相關環境變數【Official】

這兩個變數對自動化佈署特別有用。企業可在 VDI 映像檔或開發機初始化腳本中這樣寫：

export CODEX_NON_INTERACTIVE=1
export CODEX_INSTALL_DIR=/opt/codex/bin
curl -fsSL https://chatgpt.com/codex/install.sh | sh

Source: https://learn.chatgpt.com/docs/config-file/environment-variables

5.6 更新與版本管理【Official】

# 檢查並套用更新（install script 安裝者）
codex update

# 確認目前版本
codex --version

# npm 安裝者
npm update -g @openai/codex

# 釘選特定版本（企業建議）
npm install -g @openai/codex@0.153.4

# Homebrew 安裝者
brew upgrade --cask codex

📌 企業版本策略【建議】：Codex CLI 迭代極快（0.153.x 系列在一週內就發了 4 個 patch），且行為可能隨版本變動。建議：

1. 企業指定一個「已驗證版本」，例如 0.153.4，寫進團隊 onboarding 文件。
2. 不要讓 CI 使用浮動版本。GitHub Action 用 codex-version 參數釘選；npm 安裝釘選確切版號。
3. 每月一次版本評估：由平台組在測試專案上驗證新版，確認 sandbox / approval 行為未變後再全隊升版。
4. 避免使用 alpha 通道（如 0.154.0-alpha.x）於日常工作。

5.7 PATH 與安裝驗證【建議】

安裝後若 codex 指令找不到，依序檢查：

# 1. 執行檔到底裝在哪
which codex          # macOS / Linux
where.exe codex      # Windows

# 2. PATH 內容
echo $PATH           # bash / zsh
$env:PATH -split ';' # PowerShell

# 3. 官方診斷工具（最直接）
codex doctor

codex doctor 會產出一份涵蓋安裝、設定、認證、執行環境的診斷報告，是排查安裝問題的第一站。

常見 PATH 問題：

5.8 Shell 自動補全【Official】

codex completion bash
codex completion zsh
codex completion fish
codex completion powershell

Zsh 的設定方式：

autoload -Uz compinit && compinit
eval "$(codex completion zsh)"

重開 shell 後即可使用 Tab 補全。

Source: https://learn.chatgpt.com/docs/cli-customization

5.9 安裝疑難排解【建議】

5.10 本章實務案例【建議】

情境：一個 20 人的 Java + Vue 團隊要導入 Codex CLI，開發機混合 Windows 11 與 macOS。

佈署方案：

flowchart TD
    PLAT["平台組"] --> VER["決定企業指定版本<br/>0.153.4"]
    VER --> BASE["建立企業基準設定<br/>/etc/codex/config.toml (macOS/Linux)<br/>+ requirements.toml"]
    BASE --> SCRIPT["撰寫一鍵安裝腳本"]

    SCRIPT --> WIN["Windows 開發機<br/>install.ps1 + 原生 sandbox"]
    SCRIPT --> MAC["macOS 開發機<br/>install.sh 或 brew cask"]

    WIN --> VERIFY["codex doctor<br/>+ codex --version 驗收"]
    MAC --> VERIFY
    VERIFY --> LOGIN["codex login<br/>企業 ChatGPT 工作區"]
    LOGIN --> SMOKE["冒煙測試<br/>在範例 repo 跑一個 read-only 任務"]

    style PLAT fill:#1e3a5f,color:#fff
    style VERIFY fill:#2d5016,color:#fff
    style SMOKE fill:#2d5016,color:#fff

一鍵安裝腳本（macOS / Linux）【建議】：

#!/usr/bin/env bash
set -euo pipefail

CODEX_PINNED_VERSION="0.153.4"

echo "==> 安裝 Codex CLI"
export CODEX_NON_INTERACTIVE=1
curl -fsSL https://chatgpt.com/codex/install.sh | sh

echo "==> 驗證版本"
ACTUAL="$(codex --version)"
echo "已安裝：${ACTUAL}（企業指定：${CODEX_PINNED_VERSION}）"

echo "==> 建立個人設定目錄"
mkdir -p "${HOME}/.codex"

echo "==> 執行診斷"
codex doctor

echo "==> 完成。請執行 'codex login' 以企業 ChatGPT 帳號登入。"

Windows 對應版本（PowerShell）【建議】：

$ErrorActionPreference = "Stop"
$PinnedVersion = "0.153.4"

Write-Host "==> 安裝 Codex CLI"
$env:CODEX_NON_INTERACTIVE = "1"
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Write-Host "==> 驗證版本"
codex --version

Write-Host "==> 建立個人設定目錄"
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null

Write-Host "==> 執行診斷"
codex doctor

Write-Host "==> 完成。請執行 'codex login' 以企業 ChatGPT 帳號登入。"

驗收標準【建議】：新人上機第一天結束前，必須通過以下三項：

□ codex --version 顯示企業指定版本
□ codex doctor 無 ERROR 等級問題
□ 能在範例 repo 以 read-only 模式完成一次分析任務

5.11 本章注意事項

• ⚠️ 不要同時用多種方式安裝。install script 與 npm 各裝一份，會出現「改了設定沒生效」這類極難排查的問題。
• ⚠️ 企業務必釘選版本。CLI 的 sandbox / approval 行為會隨版本演進，全隊版本不一致時，「在我機器上可以」會變成日常。
• ⚠️ docs/install.md 是建置文件，不是安裝文件。它列的 WSL2 需求針對的是「編譯 Codex」，不要拿它當一般安裝依據。
• 📌 codex doctor 是排查第一站。任何安裝、設定、認證問題，先跑它再說。
• 📌 CI 中一律釘選版本。GitHub Action 用 codex-version，容器映像檔用確切版號。
• 📌 安裝完成不等於可用。真正的驗收是「能完成一次 read-only 任務」。

6. Authentication

6.1 兩種認證身分【Official】

Codex CLI 支援以 ChatGPT 帳號、API key，或 access token 認證。

flowchart TD
    START["codex login"] --> Q{"選擇認證方式"}

    Q -->|"無參數（預設）"| OAUTH["瀏覽器 OAuth<br/>Sign in with ChatGPT"]
    Q -->|"--device-code"| DEV["Device code 流程<br/>無瀏覽器 / 遠端主機"]
    Q -->|"--with-api-key"| APIK["從 stdin 讀取 API key"]
    Q -->|"--with-access-token"| TOKEN["從 stdin 讀取 access token"]

    OAUTH --> CHAT["ChatGPT 身分<br/>Plus / Pro / Business / Edu / Enterprise"]
    DEV --> CHAT
    APIK --> API["OpenAI API 帳務身分"]
    TOKEN --> WS["ChatGPT 工作區身分<br/>Business / Enterprise"]

    CHAT --> USE1["日常開發<br/>互動式使用"]
    API --> USE2["自動化 / CI"]
    WS --> USE3["受信任的非互動本機自動化"]

    style CHAT fill:#2d5016,color:#fff
    style API fill:#7a3b12,color:#fff
    style WS fill:#1e3a5f,color:#fff

Source: OpenAI 官方 Authentication 文件 https://learn.chatgpt.com/docs/auth

6.2 Sign in with ChatGPT（推薦）【Official】

最單純的方式，直接執行：

codex login

不帶任何參數時，Codex 會開啟瀏覽器進行 ChatGPT OAuth 流程。適用方案：Plus、Pro、Business、Edu、Enterprise。

為什麼推薦這個方式【建議】：

1. 用量計入既有 ChatGPT 訂閱，不需另外管理 API 帳務。
2. 企業工作區可統一管理成員、稽核與政策。
3. 不需要在本機保存長期有效的 API key。

6.3 Device Code 流程（無瀏覽器環境）【Official】

在遠端主機、容器、或無法接受 localhost callback 的環境中：

codex login --device-code

此時 Codex 會顯示一組代碼，你在另一台有瀏覽器的裝置上完成授權即可。

典型使用情境【建議】：SSH 連進開發伺服器、在 Docker container 內、在沒有 GUI 的 Linux 主機上。

6.4 API Key 認證【Official】

適合自動化與 CI。正確的做法是從 stdin 讀取，不要寫在指令列：

printenv OPENAI_API_KEY | codex login --with-api-key

📌 為什麼要用 stdin【建議】：直接寫成 codex login --with-api-key sk-xxxx 會讓金鑰出現在 shell 歷史紀錄、ps 輸出、以及 CI log 中。用管線傳入可避免這三種洩漏路徑。

在 GUI 入口（ChatGPT 桌面應用、IDE 擴充）也可以在未登入畫面選擇 Sign in another way，輸入 API key 後繼續。

6.5 Access Token（Business / Enterprise）【Official】

Codex access token 是 ChatGPT 工作區憑證，範圍限縮於 Codex 權限，用來以工作區身分認證受信任的非互動式本機工作流程（包含 Codex CLI 與 app-server 自動化）。

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

⚠️ 目前僅支援 ChatGPT Business 與 Enterprise 工作區。

Source: https://learn.chatgpt.com/docs/enterprise/access-tokens

若需要非人類身分（機器人帳號）的 token，請使用 Service Accounts。這是企業自動化的正解——不要用某位工程師的個人帳號跑 CI。

6.6 認證相關環境變數【Official】

📌 Workload Identity Federation【Official】：後三個變數是企業自動化的最佳解。它讓 CI Runner / Kubernetes Pod 以其既有的工作負載身分（OIDC / SPIFFE）換取存取權，完全不需要在任何地方保存長期金鑰。若貴公司已有 OIDC 基礎建設（GitHub Actions OIDC、EKS IRSA、SPIFFE/SPIRE），優先採用這條路徑。

CI 中的最小可行寫法：

CODEX_API_KEY="${{ secrets.OPENAI_API_KEY }}" codex exec --json "分析測試失敗原因"

6.7 企業網路與 TLS 攔截【Official】

許多企業網路會做 TLS 攔截（SSL inspection）。此時需要指定 CA bundle：

export CODEX_CA_CERTIFICATE=/etc/ssl/certs/corporate-ca-bundle.pem

📌 若安裝或登入時出現憑證錯誤，九成是這個問題。把這一條寫進團隊的 onboarding 文件可以省下大量客服時間。

6.8 限制認證方式（企業管控）【Official】

企業可強制所有人使用同一種認證方式：

# /etc/codex/config.toml 或 requirements.toml
forced_login_method = "chatgpt"   # 或 "api"

使用時機【建議】：

• "chatgpt"——希望所有用量透過企業工作區集中管理與稽核，禁止員工用個人 API key。
• "api"——已有成熟的 API 金鑰治理與成本歸屬機制。

6.9 認證方式比較【建議】

6.10 憑證安全紅線【建議】

🚫 絕對禁止：把 API key 寫進 Git Repository。

這條規則沒有例外。包括但不限於：

必做的防護【建議】：

# 1. 確保 .gitignore 包含
.env
.env.*
*.pem
.codex/auth.json

# 2. 用 shell environment policy 阻止金鑰流入子行程

# ~/.codex/config.toml
[shell_environment_policy]
inherit = "core"

[shell_environment_policy.filters]
"*_API_KEY" = "exclude"
"*_SECRET*" = "exclude"
"*_TOKEN"   = "exclude"
"*_PASSWORD" = "exclude"
"AWS_*"     = "exclude"
"AZURE_*"   = "exclude"
"GCP_*"     = "exclude"
"DB_*"      = "exclude"

# 3. 建立 pre-commit secret scanning（例如 gitleaks / detect-secrets）

📌 萬一真的洩漏了【建議】：立刻撤銷金鑰（不是刪 commit）。Git 歷史可以被 fork、被 clone、被鏡像、被搜尋引擎索引；唯一可靠的補救是讓那把金鑰失效。

6.11 本章實務案例【建議】

情境：某企業要建立 Codex CLI 的認證標準，涵蓋開發者本機、CI、以及一個內部批次分析平台。

三層認證架構：

flowchart TD
    subgraph DEVL["① 開發者本機"]
        D1["codex login<br/>（瀏覽器 OAuth）"]
        D2["身分：企業 ChatGPT 工作區成員"]
        D3["管控：forced_login_method = chatgpt"]
        D1 --> D2 --> D3
    end

    subgraph CIL["② CI / CD"]
        C1["Workload Identity Federation<br/>OIDC，無長期金鑰"]
        C2["身分：Service Account"]
        C3["備援：Secret 中的 API key"]
        C1 --> C2 --> C3
    end

    subgraph PLATL["③ 內部批次平台"]
        P1["Codex Access Token<br/>或 Service Account"]
        P2["身分：平台專用非人類帳號"]
        P3["金鑰存於企業 Secret Manager"]
        P1 --> P2 --> P3
    end

    AUDIT["統一稽核<br/>誰在什麼時候用了什麼"]
    D3 --> AUDIT
    C3 --> AUDIT
    P3 --> AUDIT

    style DEVL fill:#2d5016,color:#fff
    style CIL fill:#7a3b12,color:#fff
    style PLATL fill:#1e3a5f,color:#fff
    style AUDIT fill:#3d2b5f,color:#fff

落實的具體措施：

這套架構的關鍵優點：沒有任何一個長期有效的個人金鑰散落在開發機或 CI 設定中。所有存取都可歸屬到一個可撤銷的身分。

6.12 本章注意事項

• 🚫 API key 絕不進 Repository。已進去的視為洩漏，唯一補救是撤銷。
• ⚠️ 不要用指令列參數傳金鑰，一律用 stdin 管線（printenv X | codex login --with-api-key）。
• ⚠️ 不要用個人帳號跑 CI。人一離職，整條 pipeline 就掛了；而且無法區分是人做的還是機器做的。
• ⚠️ Access token 目前僅限 Business / Enterprise 工作區，個人方案請用其他方式。
• 📌 企業網路憑證錯誤 → 先設 CODEX_CA_CERTIFICATE。
• 📌 有 OIDC 基礎建設就用 workload identity federation，這是唯一能做到「零長期金鑰」的方案。
• 📌 [shell_environment_policy.filters] 第一天就設好。它防的是「Agent 執行的子行程意外看到你的雲端憑證」，成本幾乎為零。

7. Configuration

7.1 設定的五個層級與優先順序【Official】

這是本章最重要的一張表。Codex CLI 的設定由多層疊加而成，後面的層級覆寫前面的：

flowchart TD
    L1["① 內建預設值<br/>Built-in defaults"] --> L2
    L2["② 系統設定<br/>/etc/codex/config.toml"] --> L3
    L3["③ 使用者設定<br/>~/.codex/config.toml"] --> L4
    L4["④ Profile 疊加<br/>~/.codex/&lt;name&gt;.config.toml"] --> L5
    L5["⑤ 專案設定<br/>.codex/config.toml（僅受信任專案）"] --> L6
    L6["⑥ CLI 旗標<br/>--config KEY=VALUE / --model / --sandbox"]

    MG["企業受管設定<br/>requirements.toml"] -.->|"強制約束<br/>下層無法違反"| L3
    MG -.-> L4
    MG -.-> L5
    MG -.-> L6

    style L6 fill:#2d5016,color:#fff
    style MG fill:#7a3b12,color:#fff

優先順序由高到低【Official】：

Source: OpenAI 官方 Config 文件 https://learn.chatgpt.com/docs/config-file/config-basic https://learn.chatgpt.com/docs/config-file/config-advanced

⚠️ 極重要的安全規則【Official】：不受信任的專案會完全略過 .codex/ 專案層設定（config、hooks、rules 都不載入），但仍保留使用者與系統層設定。這是防止「惡意 Repository 透過 .codex/config.toml 提權」的關鍵設計。

⚠️ 專案層無法覆寫的 key【Official】：openai_base_url、model_provider、model_providers、notify、profile，以及認證相關設定。也就是說，一個 Repository 無法把你的請求導向它自己的 endpoint。這是刻意的防護。

7.2 設定檔位置速查【Official】

$CODEX_HOME 預設為 ~/.codex，可用環境變數變更。

📌 相對路徑規則【Official】：專案設定中的相對路徑，是相對於包含該 config.toml 的 .codex/ 資料夾解析，不是相對於 Repository root。

7.3 最小可用設定【建議】

新手第一份 ~/.codex/config.toml，建議就這樣開始：

# ~/.codex/config.toml — 個人基礎設定

# 模型與推理強度
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"

# 安全預設：可在工作區內讀寫與執行，要跨界時停下來問
sandbox_mode   = "workspace-write"
approval_policy = "on-request"

# 網路預設關閉
[sandbox_workspace_write]
network_access = false

# 不讓敏感環境變數流入 Agent 執行的子行程
[shell_environment_policy]
inherit = "core"

[shell_environment_policy.filters]
"*_API_KEY"  = "exclude"
"*_SECRET*"  = "exclude"
"*_TOKEN"    = "exclude"
"*_PASSWORD" = "exclude"
"AWS_*"      = "exclude"
"AZURE_*"    = "exclude"
"GCP_*"      = "exclude"

這份設定的三個立場：預設安全、網路關閉、憑證不外流。之後再依需求逐項放寬，而不是一開始全開再逐項收緊。

7.4 模型與推理設定【Official】

目前的模型線【Official】：

⚠️ Version Note：模型淘汰時程

• GPT-5.4 與 GPT-5.4 Mini 已於 2026-08-31 從「以 ChatGPT 登入的 Codex」退場，官方建議分別遷移至 5.6-terra 與 5.6-luna。
• gpt-5.2 與 gpt-5.3-codex 已淘汰。
• 若你的 config.toml 或 CI 仍釘選這些模型，請立即更新。

Source: https://learn.chatgpt.com/docs/models

推理強度選用建議【建議】：

模型選用建議【建議】：

7.5 Fast Mode 與服務層級（service_tier）【Official】

除了「換模型」與「調推理強度」之外，Codex 還有第三個影響速度與成本的維度：服務層級（service tier）。它不改變模型的能力，只改變同一個模型的回應速度與計費倍率。

7.5.1 設定方式【Official】

# ~/.codex/config.toml
service_tier = "fast"

[features]
fast_mode = true

⚠️ 兩個開關都要設。 只設 service_tier 而沒有開 features.fast_mode，或反過來，都不會生效。這是 Codex 設定中少數「需要兩處一致」的項目，也是 /fast status 存在的原因——先用它確認，再懷疑其他事情。

7.5.2 速度與計費倍率【Official】

⚠️ Version Note：顯示倍率在 0.153.2 被修正

Codex CLI 0.153.2 修正了 Fast tier 的描述文字，把介面上顯示的加速倍率從「1.5x」改為「2x」。官方文件頁與 CLI 介面在這段期間曾出現不一致——以你手上版本的 /fast status 實際顯示為準，並在採購/成本估算時以 credit 倍率（2.5× / 2×）為計算基礎，而不是以加速倍率。

以 API Key 認證時規則不同【Official】：API Key 使用者不套用 ChatGPT credit 倍率，改為適用 API token 計價；對應的加速選項是 Priority processing，費率為標準 API 的 2×。

7.5.3 可用範圍【Official】

7.5.4 Fast Mode vs Codex-Spark：兩條不同的路【Official / 建議】

這兩者經常被混為一談，但它們是完全不同的機制：

7.5.5 企業成本策略【建議】

Fast Mode 的 2.5× 倍率意味著它不該是預設值。建議的分級策略：

📌 可稽核的做法【建議】：在企業層 /etc/codex/config.toml 中明確設定 service_tier = "standard" 與 [features] fast_mode = false 作為預設，讓 Fast Mode 成為開發者主動開啟的例外而非預設吃掉預算的常態。CI 的設定檔則永不開啟。

7.6 Approval 與 Sandbox 設定【Official】

approval_policy = "on-request"     # untrusted / on-request / never
sandbox_mode    = "workspace-write" # read-only / workspace-write / danger-full-access

[sandbox_workspace_write]
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false

Granular approval（細緻核准）【Official】：

approval_policy = { granular = {
  sandbox_approval   = true,
  request_permissions = false,
  skill_approval     = false
} }

自動審查者【Official】：

approvals_reviewer = "auto_review"   # 預設為 "user"

設為 auto_review 時，符合條件的核准請求會先交由自動審查者評估。官方說明其審查重點包含：資料外洩、憑證探測、持續性的安全弱化、破壞性操作。

⚠️ 企業使用 auto_review 的前提【建議】：它是降低摩擦的工具，不是取代人工審查的工具。建議只在低風險專案、且已有完整 CI 驗證的情況下啟用。管理者可用 allowed_approvals_reviewers（在 requirements.toml 中）限制其使用範圍。

完整說明見第 20 章。

7.7 Permission Profiles【Official】

除了 sandbox_mode 之外，Codex 提供權限設定檔概念，內建三個：

自訂 profile 可透過 [permissions.<profile-name>] 定義，內含更細緻的 network、filesystem、tool 設定。可用 default_permissions 指定預設使用哪一個。

Source: https://learn.chatgpt.com/docs/agent-approvals-security

7.8 Profiles（具名設定層）【Official】

Profile 讓你不用改檔案就能切換工作情境。

⚠️ Version Note：Profile 寫法已變更

自 0.134.0 起，不再支援在 config.toml 中使用 [profiles.<name>] 表格的舊寫法。 現行做法是獨立檔案：~/.codex/<profile-name>.config.toml，且檔案內只用頂層 key（不要再巢狀）。

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"

使用：

codex --profile deep-review

建議建立的四個 profile【建議】：

# ~/.codex/explore.config.toml — 唯讀探索
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
approval_policy = "untrusted"

# ~/.codex/dev.config.toml — 日常開發
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# ~/.codex/deep.config.toml — 困難問題
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# ~/.codex/ci.config.toml — CI 用（唯讀、無歷史）
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
approval_policy = "never"

codex --profile explore   # 分析陌生專案
codex --profile dev       # 日常開發
codex --profile deep      # 卡住的時候

📌 這四個 profile 是本手冊建議的團隊標準配置。把它們放進 onboarding 腳本，新人第一天就有正確的預設值。

7.9 Features 旗標【Official】

[features] 區段控制一組可開關的能力：

也可用指令持久化開關：

codex features            # 檢視與開關 feature flag

網路代理與網域白名單【Official】：

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

網域規則採allowlist-first邏輯，支援：

本機綁定（local binding）預設封鎖，需 allow_local_binding = true 才開放。

📌 企業建議【建議】：與其用 network_access = true 全開，不如用 features.network_proxy 搭配白名單。典型白名單：內部 artifact repository、內部 npm/Maven mirror、必要的官方文件站。不要把 * 放進白名單。

7.10 Web Search 設定【Official】

web_search = "cached"   # disabled / cached / indexed / live

⚠️ 官方安全說明【Official】：網頁搜尋預設使用快取（預先索引）結果，目的是「降低來自任意即時內容的 prompt injection 曝險」。

企業建議【建議】：一般開發保持 cached；處理不受信任的 Repository 時設為 disabled；只有在明確需要查詢最新技術文件、且任務不涉及敏感資料時才短暫使用 live。

7.11 Hooks（生命週期攔截）【Official】

Hooks 讓你在 Agent 生命週期的特定事件上掛載自訂程式或 MCP 工具，例如在每次執行指令前先跑一段政策檢查。它是把「組織既有的政策引擎」接進 Codex 的正式接口——不是靠 prompt 請 Agent 自律，而是在 harness 層強制攔截。

完整事件清單【Official】：

定義位置【Official】：

TOML 內嵌寫法：

[[hooks.PreToolUse]]
matcher = "^Bash$"          # 選用：regex，限定哪些工具會觸發

[[hooks.PreToolUse.hooks]]
type          = "command"
command       = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/policy.py"'
timeout       = 600         # 秒
statusMessage = "執行企業政策檢查…"   # 選用：顯示在 UI 的文字
async         = false       # 選用：true 表示背景執行、不阻塞

JSON 寫法（hooks.json）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          { "type": "command", "command": ".codex/hooks/policy.py", "timeout": 600 }
        ]
      }
    ]
  }
}

輸入 / 輸出契約【Official】：

command 類型的 hook 由 stdin 收 JSON、由 stdout 回 JSON：

離開碼【Official】：

其他能力【Official】：

• MCP 工具型 hook：type 可指向已連線 MCP server 上的工具，直接呼叫，而非執行本機腳本。
• 背景執行：async = true 讓 hook 不阻塞主流程，適合送稽核 log、發通知這類副作用。
• 大量輸出處理：超量的 hook 輸出會落地到磁碟，context 中只保留預覽，避免撐爆 context window。

信任模型【Official】：

TUI 內用 /hooks 檢視目前的 hooks 並授予信任。

📌 企業用途範例【建議】

Hook 事件	企業用途
PreToolUse + matcher = "^Bash$"	攔截任何觸及生產環境連線字串、kubectl、aws 的指令，回傳離開碼 2 阻擋
UserPromptSubmit	掃描 prompt 中是否含個資 / 憑證，命中即阻擋並記錄
PostToolUse	把每次檔案寫入寫進企業稽核 log（async = true）
SessionStart	注入當日的企業公告或政策變更（additionalContext）
SubagentStop	統計 subagent 用量，回報成本歸屬

⚠️ 兩個最常見的坑

1. 專案層 hooks 需要專案被信任才會載入——這同時是安全防護（惡意 repo 無法自動執行 hook）與注意事項（你以為設了 hook 但沒生效，先用 /hooks 確認信任狀態）。
2. 受管 hooks 免信任——這是企業能強制執行政策的關鍵，但也代表 MDM / requirements.toml 的寫入權限本身就是最高權限，必須納入變更管控。

7.12 MCP 設定【Official】

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 60
default_tools_approval_mode = "prompt"

完整說明見第 21 章。

7.13 Skills 與 Plugins 設定【Official】

Skill 是「可重用的工作流程單元」——一組寫給 Agent 看的步驟指引，加上選用的腳本與參考資料。它填補了 AGENTS.md 與 MCP 之間的空隙：

7.13.1 目錄結構【Official】

my-skill/
├── SKILL.md            # 必要：metadata + 指引本體
├── scripts/            # 選用：可執行腳本
├── references/         # 選用：參考文件
├── assets/             # 選用：範本與資源
└── agents/
    └── openai.yaml     # 選用：UI、呼叫政策、工具相依

SKILL.md 的 frontmatter 必要欄位只有兩個：

---
name: spring-boot-upgrade
description: 執行 Spring Boot 主版本升級的標準流程；當任務涉及 Spring Boot 版本升版、Breaking Changes 分析或 Jakarta 命名空間遷移時使用。
---

1. 先執行 `mvn dependency:tree` 盤點現況，輸出到 `docs/upgrade/before.txt`。
2. 對照官方 Migration Guide 產出 Breaking Changes 清單。
3. 依第 14 章的分批策略執行，每批獨立 commit。
4. 每批完成後執行 `mvn verify`，失敗即停。

🎯 description 是整個 Skill 最重要的一行。 Codex 採 progressive disclosure（漸進揭露）：平時 context 中只有每個 skill 的 name 與 description，只有當它判斷要用時才載入完整的 SKILL.md。 這代表 description 同時扮演兩個角色：索引（讓模型找得到）與守門員（讓模型不會誤用）。官方建議「寫出範圍與邊界清楚的簡短描述，把關鍵使用情境與觸發詞放在最前面」。

7.13.2 呼叫方式【Official】

7.13.3 設定與停用【Official】

# ~/.codex/config.toml
[[skills.config]]
path    = "/path/to/skill/SKILL.md"
enabled = false        # 停用特定 skill

TUI 內可用 /plugins 管理已安裝的 plugin 並探索新的。

7.13.4 企業使用建議【建議】

⚠️ Skill 的安全面【建議】：Skill 可以攜帶可執行腳本，等同於「一段會被 Agent 主動執行的程式碼」。因此：

• skill_approval（granular approval 的一環，見第 20 章）決定 skill 執行是否需要核准——企業環境建議開啟。
• 第三方 skill / plugin 一律視同第三方相依套件：先審查 scripts/ 內容，再納入組織白名單。
• 企業可透過管理端集中管控可用的 skill 與 plugin（見第 28 章）。

7.14 Model Providers（自訂供應者 / 企業代理）【Official】

簡單代理（只換 endpoint）：

openai_base_url = "https://us.api.openai.com/v1"

完整供應者定義：

model_provider = "proxy"

[model_providers.proxy]
name     = "LLM Proxy"
base_url = "http://proxy.example.com"
env_key  = "OPENAI_API_KEY"

指令式認證（適合需要動態換取 token 的企業環境）：

[model_providers.proxy.auth]
command             = "/usr/local/bin/fetch-codex-token"
timeout_ms          = 5000
refresh_interval_ms = 300000

📌 這是企業「自主可控」的關鍵設定【建議】。透過內部 LLM Proxy，企業可以：集中記錄所有請求、統一套用 DLP 規則、控制成本歸屬、在必要時切換底層供應者。

⚠️ 注意：這些 key 不能在專案層 .codex/config.toml 中覆寫——這是刻意的防護，避免惡意 Repository 把你的請求導向它自己的伺服器。

7.14.1 Amazon Bedrock 通道【Official】

對於「資料不得離開自有雲帳號邊界」的企業，官方提供了直連 Amazon Bedrock 的路徑：

# ~/.codex/config.toml
model_provider = "amazon-bedrock"
model          = "openai.gpt-5.6-sol"   # 必須使用 Bedrock 的完整 model ID

可用模型 ID【Official】：openai.gpt-5.6-sol、openai.gpt-5.5、openai.gpt-5.4 等。先確認你的 AWS Region 是否支援該模型——Region 覆蓋率是最常見的失敗原因。GPT-6-Astra 的 Bedrock 支援於 Codex CLI 0.153.3 加入。

認證順序【Official】：

⚠️ 桌面 App 與 IDE 擴充不繼承 shell 環境變數。這類情境請把憑證放進 ~/.codex/.env。

功能限制【Official】——這是選型前必須知道的取捨：

📌 支援窗口【Official】：Bedrock 相關問題請找 AWS 管理員或 AWS Support，而非 OpenAI Support。企業導入時應把這一點寫進內部的支援流程文件，避免問題在兩邊之間來回。

🎯 選型建議【建議】：Bedrock 通道換到的是資料落點的控制權，付出的是功能完整度。若你的合規要求可以透過「企業版 ChatGPT 的零留存條款 + 內部 LLM Proxy」滿足，一般建議優先走 Proxy 路線；只有在合約明確要求推論必須發生在自有 AWS 帳號內時，才採用 Bedrock 通道。

7.15 歷史、遙測與稽核【Official】

[history]
persistence = "save-all"   # save-all / none
max_bytes   = 10485760

[analytics]
enabled = false

OpenTelemetry 為選用且預設關閉。啟用後可產生涵蓋對話、核准、工具決策、API 請求的事件。

⚠️ 關鍵設定【Official / 建議】：務必保持 log_user_prompt = false，避免把敏感的程式碼或資料存進 prompt 記錄。企業若要開啟遙測作稽核用途，應先確認記錄內容不含原始碼與個資。

7.16 企業受管設定 requirements.toml【Official】

管理者透過 requirements.toml 建立組織強制約束，下層設定無法違反。可控制的項目包含：

Source: https://learn.chatgpt.com/docs/agent-approvals-security

📌 這是企業治理的執行點【建議】。第 28 章的所有政策，最終都要落實到 requirements.toml 與 /etc/codex/config.toml 上，否則只是一份沒有強制力的文件。

7.17 專案層設定範例【建議】

放進 Repository 並進版控，讓全隊有一致的預設：

# <repo>/.codex/config.toml
# 本專案的 Codex 預設設定（會被個人設定與 CLI 旗標覆寫）

model_reasoning_effort = "medium"

sandbox_mode    = "workspace-write"
approval_policy = "on-request"

# 本專案的建置需要寫入 Maven local repository
[sandbox_workspace_write]
writable_roots = ["~/.m2/repository"]
network_access = false

# 本專案不需要網頁搜尋
web_search = "disabled"

# 專案內的文件指引可能較長
project_doc_max_bytes = 65536

⚠️ 記得：這份設定只有在專案被信任時才會載入。第一次在新 Repository 執行 codex 時會詢問是否信任該目錄。

7.18 設定除錯【建議】

「設定沒生效」的排查順序【建議】：

1. 是不是被更高優先的層級覆寫了？（CLI 旗標 > 專案 > profile > 使用者 > 系統）
2. 專案是不是「不受信任」？→ .codex/ 整層都不會載入
3. 這個 key 是不是專案層禁止覆寫的？（model_provider / auth 類）
4. 是不是用了已淘汰的 [profiles.name] 舊寫法？（0.134.0 起不支援）
5. 是不是被企業 requirements.toml 強制約束？
6. TOML 語法錯誤？→ codex doctor

7.19 本章實務案例【建議】

情境：一個同時有「一般開發專案」與「客戶敏感資料專案」的團隊，要建立分級設定。

三層設定架構：

flowchart TD
    subgraph ENT["企業層（IT 維護）"]
        E1["requirements.toml<br/>禁止 danger-full-access<br/>限制 approvals_reviewer<br/>核可的 MCP server 清單"]
        E2["/etc/codex/config.toml<br/>forced_login_method = chatgpt<br/>企業 LLM Proxy<br/>CA 憑證"]
    end

    subgraph USR["個人層（開發者維護）"]
        U1["~/.codex/config.toml<br/>模型偏好、環境變數過濾"]
        U2["explore / dev / deep / ci<br/>四個 profile"]
    end

    subgraph PRJ["專案層（進版控）"]
        P1["一般專案 .codex/config.toml<br/>workspace-write + on-request<br/>web_search = cached"]
        P2["敏感專案 .codex/config.toml<br/>read-only + untrusted<br/>web_search = disabled<br/>network_access = false"]
    end

    ENT --> USR --> PRJ

    style ENT fill:#7a3b12,color:#fff
    style USR fill:#1e3a5f,color:#fff
    style PRJ fill:#2d5016,color:#fff

敏感專案的 .codex/config.toml【建議】：

# <sensitive-repo>/.codex/config.toml
# ⚠️ 本專案包含客戶資料，採最嚴格設定

# 預設唯讀。需要修改時由開發者以 CLI 旗標明確提升，留下意圖紀錄
sandbox_mode    = "read-only"
approval_policy = "untrusted"

# 完全禁止網路與網頁搜尋
web_search = "disabled"

[sandbox_workspace_write]
network_access = false

# 不保存對話歷史
[history]
persistence = "none"

搭配 AGENTS.md 中的明文提醒（見第 8 章），以及企業層 requirements.toml 的強制約束，形成三重防護。

驗收：

□ 在敏感專案目錄執行 codex，/status 顯示 sandbox 為 read-only
□ 嘗試讓 Agent 執行 curl，被沙箱阻擋
□ 結束 session 後，$CODEX_HOME/sessions 下沒有新增該專案的紀錄

7.20 本章注意事項

• ⚠️ 設定優先順序要背起來：CLI 旗標 > 專案 > profile > 使用者 > 系統 > 內建。八成的「設定沒生效」都是這個問題。
• ⚠️ 不受信任的專案會略過整個 .codex/ 層。這是安全特性，但也是常見的困惑來源。
• ⚠️ [profiles.name] 舊寫法在 0.134.0 起已不支援，網路上大量教學仍是舊寫法。
• ⚠️ 模型名稱會淘汰。5.4 / 5.4 Mini 已於 2026-08-31 退場，gpt-5.2 / gpt-5.3-codex 已淘汰。CI 中釘選的模型要定期檢查。
• ⚠️ danger-full-access 不該出現在任何個人或專案設定中。企業應在 requirements.toml 層直接禁止。
• 📌 網路要開就用 features.network_proxy 白名單，不要用 network_access = true 全開。
• 📌 web_search 在處理不受信任的 Repository 時應設為 disabled。
• 📌 企業治理最終要落到 requirements.toml。寫在 Confluence 上的政策沒有強制力。
• 📌 codex doctor + /status + codex debug prompt-input 是設定除錯的三件套。

8. AGENTS.md

8.1 AGENTS.md 是什麼【Official】

AGENTS.md 是給 AI Agent 看的 README。

它是一份純文字（Markdown）檔案，用來告訴 Codex：這個專案怎麼跑測試、有哪些慣例、哪些地方不能碰、架構長什麼樣。Codex 在開始工作前會先讀取這些檔案。

Source: OpenAI 官方 AGENTS.md 文件 https://learn.chatgpt.com/docs/agent-configuration/agents-md

AGENTS.md 是一個開放格式，由 AI 軟體開發生態系共同推動（OpenAI Codex、Amp、Google Jules、Cursor、Factory 等），格式規範見 https://agents.md/。這代表同一份 AGENTS.md 可以同時服務多種 Agent 工具，不會被單一廠商綁定。

8.2 為什麼它是最高投報率的一件事【建議】

沒有 AGENTS.md 的專案，Agent 每一次任務都要重新摸索：

📌 一句話：AGENTS.md 把「每次都要在 prompt 裡講的話」變成「講一次就永久生效」。這是所有 Codex 導入工作中投報率最高的一項。

8.3 檔案探索與優先順序【Official】

這是本章最關鍵的機制，必須精確理解。

flowchart TD
    START["Codex 啟動"] --> G["① 全域範圍<br/>$CODEX_HOME（預設 ~/.codex）"]

    G --> G1{"AGENTS.override.md<br/>存在且非空？"}
    G1 -->|"是"| GU["使用它"]
    G1 -->|"否"| G2{"AGENTS.md<br/>存在且非空？"}
    G2 -->|"是"| GU
    G2 -->|"否"| P
    GU --> P

    P["② 專案範圍<br/>從 Git root 往下走到目前工作目錄"] --> P1["對每一層目錄依序檢查：<br/>AGENTS.override.md<br/>→ AGENTS.md<br/>→ project_doc_fallback_filenames"]
    P1 --> P2["每層目錄最多取一個檔案"]
    P2 --> P3{"累計大小超過<br/>project_doc_max_bytes？<br/>（預設 32 KiB）"}
    P3 -->|"是"| STOP["停止讀取"]
    P3 -->|"否"| P4["繼續往下一層"]
    P4 --> P2

    STOP --> MERGE
    P4 --> MERGE["③ 合併<br/>由 root 往下串接<br/>越接近的目錄覆寫越早的指引"]
    MERGE --> CTX["進入 Context"]

    style G fill:#1e3a5f,color:#fff
    style P fill:#2d5016,color:#fff
    style MERGE fill:#3d2b5f,color:#fff

規則整理【Official】：

8.4 驗證有沒有被讀到【Official】

寫完 AGENTS.md 最重要的一步是驗證它真的生效了：

codex --ask-for-approval never "Summarize current instructions."

Agent 會摘要它目前收到的指引，你可以據此確認載入順序是否正確。

更底層的檢查方式：

codex debug prompt-input

這會把模型實際看到的 prompt 以 JSON 印出來——如果你的 AGENTS.md 內容不在裡面，那它就是沒被讀到。

沒被讀到的常見原因【建議】：

8.5 覆寫機制 AGENTS.override.md【Official】

AGENTS.override.md 用於臨時覆寫，不必動到基準檔案。

兩個典型用途【建議】：

1. 全域臨時覆寫——~/.codex/AGENTS.override.md。例如今天在做資安稽核，想讓所有專案的 Agent 都更保守：

   # 臨時覆寫（資安稽核期間）
   - 本週所有工作一律先分析、不修改，除非我明確說「開始修改」。
   - 任何涉及認證、加密、輸入驗證的程式碼，改動前必須先說明風險。

2. 專案子目錄的特殊規則——例如某個 service 有不同於全專案的規範。

⚠️ 注意：AGENTS.override.md 不應該進版控（除非團隊刻意要用它建立子目錄規則）。個人臨時用的 override 檔進了版控，會影響到所有人。建議把 AGENTS.override.md 加入 .gitignore，需要團隊共用的規則一律寫在 AGENTS.md。

8.6 相關設定【Official】

# ~/.codex/config.toml 或 <repo>/.codex/config.toml

# 指引檔的累計大小上限（預設 32768，即 32 KiB）
project_doc_max_bytes = 65536

# 備用檔名（若團隊已有其他慣例檔案）
project_doc_fallback_filenames = ["TEAM_GUIDE.md", "CONTRIBUTING.md"]

# 判定專案根目錄的標記檔案
project_root_markers = ["pom.xml", "package.json", ".git"]

8.7 階層式配置的企業範例【建議】

大型 Repository 應該用多層 AGENTS.md，讓每個區域有自己的規範：

repository/
├── AGENTS.md                       ← 全專案通用規範
├── frontend/
│   ├── AGENTS.md                   ← Vue / TypeScript 規範
│   └── src/
│       └── components/
│           └── AGENTS.md           ← 元件層特殊規範
├── backend/
│   ├── AGENTS.md                   ← Java / Spring Boot 規範
│   ├── order-service/
│   │   └── AGENTS.md               ← 訂單服務的業務規則
│   └── payment-service/
│       └── AGENTS.md               ← ⚠️ 支付服務的高風險規範
├── infrastructure/
│   └── AGENTS.md                   ← Terraform / K8s 規範
└── legacy/
    └── AGENTS.md                   ← ⚠️ 舊系統：唯讀、不重構

運作方式：當 Agent 在 backend/payment-service/ 底下工作時，它會依序讀到：

~/.codex/AGENTS.md            （你的個人偏好）
repository/AGENTS.md          （全專案規範）
repository/backend/AGENTS.md  （Java 規範）
repository/backend/payment-service/AGENTS.md  （支付服務規範，優先權最高）

越接近的規則覆寫越遠的規則。這讓你可以：全域訂寬鬆的通則，在高風險目錄訂嚴格的例外。

8.8 根目錄 AGENTS.md 完整範本【建議】

以下是可直接複製使用的企業級範本（Java + Vue 全端專案）：

# AGENTS.md

本檔案是給 AI Coding Agent 的專案指引。修改前請先閱讀 `docs/architecture.md`。

## 專案概觀

- 名稱：訂單管理系統（OMS）
- 架構：Spring Boot 後端（`backend/`）+ Vue 3 前端（`frontend/`）
- 資料庫：PostgreSQL（開發）/ Oracle（生產）
- 建置：後端 Maven，前端 pnpm

## 常用指令

| 目的 | 指令 |
| --- | --- |
| 後端編譯 | `mvn -q -pl backend compile` |
| 後端測試 | `mvn -q -pl backend test` |
| 後端單一測試 | `mvn -q -pl backend test -Dtest=OrderServiceTest` |
| 前端測試 | `pnpm --dir frontend test` |
| 前端型別檢查 | `pnpm --dir frontend type-check` |
| 前端 lint | `pnpm --dir frontend lint` |
| 全專案驗證 | `./scripts/verify.sh` |

**修改任何程式碼後，必須執行對應的測試指令。**

## 工作原則

1. **先理解再修改。** 修改前先讀相關檔案與既有測試。
2. **小步前進。** 一次處理一個關注點，不要順手重構無關的程式碼。
3. **不確定就問。** 涉及業務規則的判斷，不要自行假設，先提出問題。
4. **保持 diff 最小。** 不要調整無關的格式、import 順序、註解。

## 架構規則

- 分層：`Controller → Service → Repository`。**禁止跨層呼叫**（Controller 不可直接用 Repository）。
- Controller 只做參數驗證與回應組裝，**不得包含業務邏輯**。
- 跨模組呼叫一律透過介面，不可直接依賴實作類別。
- 新增 REST endpoint 必須同時更新 `docs/api/openapi.yaml`。

## 程式碼慣例

### Java

- Java 21，使用 `record` 表示不可變 DTO。
- 命名：Service 以 `Service` 結尾，Repository 以 `Repository` 結尾，DTO 以 `Dto` 結尾。
- **禁止** `System.out.println`，一律使用 SLF4J（`private static final Logger log = ...`）。
- 例外處理：業務例外繼承 `BusinessException`；**禁止吞掉例外**（空的 catch block）。
- 所有 public method 需有 JavaDoc。

### TypeScript / Vue

- Vue 3 Composition API + `<script setup>`。
- **禁止 `any`**。無法確定型別時使用 `unknown` 並收斂。
- 狀態管理用 Pinia，不使用 provide/inject 傳遞跨頁狀態。
- 樣式一律 Tailwind utility class，不寫自訂 CSS 除非 Tailwind 無法表達。

## 測試規則

- 新增或修改業務邏輯**必須**附帶測試。
- 測試命名：`方法名_情境_預期結果`，例如 `cancelOrder_shippedOrder_throwsIllegalState`。
- 後端使用 JUnit 5 + AssertJ + Mockito。
- **不要為了讓測試通過而修改斷言**。若既有測試失敗，先分析是「行為真的改變了」還是「測試需要更新」，說明後再動。

## 安全規則

- **禁止**在程式碼、設定檔、測試資料中出現任何真實憑證、金鑰、密碼、個資。
- SQL 一律使用參數化查詢，**禁止字串拼接**。
- 外部輸入必須驗證（使用 Bean Validation annotation）。
- 新增依賴前必須說明理由；**禁止**引入未經核可的第三方套件。
- 記錄日誌時**禁止**輸出完整的身分證字號、卡號、密碼。

## Git 規則

- **不要執行 `git commit`、`git push`、`git reset --hard`**，除非我明確要求。
- 變更留在 working tree 讓我審查。
- 不要修改 `.git/` 下的任何內容。

## 不要碰的地方

以下目錄唯讀，除非我明確指示：

- `legacy/` — 舊系統，凍結中
- `**/generated/` — 程式碼產生器輸出
- `db/migration/` — 已套用的 Flyway migration（**只能新增，不可修改既有檔案**）
- `.github/workflows/` — CI 設定
- 任何 `*.lock`、`package-lock.json`、`pnpm-lock.yaml`

## 完成任務時

請在最後提供：

1. 改了哪些檔案、為什麼
2. 執行了哪些驗證指令、結果如何
3. 有哪些你不確定、需要我確認的地方
4. 有哪些你發現但**沒有**處理的問題

📌 範本使用建議：不要照抄。刪掉不適用的、加上你們專案真實的規則。 一份 60 行、完全貼合專案現況的 AGENTS.md，遠勝一份 300 行的通用範本。

8.9 子目錄 AGENTS.md 範例【建議】

backend/payment-service/AGENTS.md（高風險模組）：

# AGENTS.md — Payment Service

> ⚠️ 本模組處理實際金流。所有修改都需要格外謹慎。

## 額外規則（覆寫上層）

1. **任何修改前必須先說明影響範圍**，等我確認後才動手。
2. 涉及金額計算的程式碼，**一律使用 `BigDecimal`**，禁止 `double` / `float`。
3. 金額比較禁止用 `==`，使用 `compareTo`。
4. **所有金流操作必須具備冪等性**。新增 endpoint 時必須說明冪等鍵設計。
5. 修改任何 `*Payment*` 類別後，除了單元測試，還必須執行：
   `mvn -q -pl backend/payment-service verify -Pintegration-test`
6. **禁止**在日誌中輸出卡號、CVV、完整帳號。遮罩規則見 `MaskingUtils`。
7. 對外部支付閘道的呼叫必須有 timeout 與重試上限。

## 本模組的關鍵不變量

- 一筆訂單的支付總額不得超過訂單金額
- 已完成的支付不可修改，只能建立沖正交易
- 所有狀態轉換必須寫入 `payment_audit_log`

legacy/AGENTS.md（凍結區）：

# AGENTS.md — Legacy（凍結中）

> 🚫 本目錄為凍結的舊系統，**預設唯讀**。

## 規則

1. **不要修改本目錄下的任何檔案**，除非我在 prompt 中明確寫出「修改 legacy/」。
2. 可以**閱讀**本目錄以理解既有行為，這是被鼓勵的。
3. 若你認為某個 bug 的根因在 legacy/，**請說明並提出建議，但不要動手修**。
4. 產出分析文件時，請寫到 `docs/legacy-analysis/` 而非本目錄。

## 背景

本目錄為 2014 年的 Struts 1 系統，正在以 Strangler Fig 模式逐步汰換。
新功能一律寫在 `backend/`，本目錄只做安全性修補。

8.10 寫好 AGENTS.md 的七個原則【建議】

/init 指令【Official】：在 TUI 中輸入 /init，Codex 會分析專案並產生一份 AGENTS.md 草稿。

📌 /init 的正確用法：把它當草稿產生器，不是最終答案。它能正確抓到建置指令、技術棧、目錄結構；但猜不到你們的業務規則、歷史包袱、與內部規範——那些必須你來寫。

8.11 AGENTS.md 反面教材【建議】

8.12 本章實務案例【建議】

情境：某團隊導入 Codex CLI 一個月後，統計出「Agent 產出需要人工返工」的前五大原因：

處置：把這五點逐條寫進 AGENTS.md：

## 從實際返工紀錄整理的規則（2026-09 更新）

1. **嚴禁跨層呼叫**：Controller → Service → Repository。Controller 中出現
   `*Repository` 型別的注入即為違規。
2. **嚴禁 `System.out.println` / `System.err.println`**。一律：
   `private static final Logger log = LoggerFactory.getLogger(X.class);`
3. **新增或修改 Service 層方法，必須附帶單元測試**，且測試需實際執行通過。
4. **`**/generated/` 目錄唯讀**。若你認為需要修改，請說明原因並停下來問我。
5. **測試失敗時禁止修改斷言**。先判斷是「行為真的改變」還是「測試該更新」，
   說明你的判斷後再動手。

一個月後的複測結果：

這個案例的方法論【建議】：

flowchart LR
    A["記錄每次返工原因"] --> B["每月統計 Top 5"]
    B --> C["寫成 AGENTS.md 的具體規則"]
    C --> D["下個月再統計"]
    D --> E{"改善了嗎？"}
    E -->|"是"| F["保留規則<br/>處理下一批問題"]
    E -->|"否"| G["規則寫得不夠具體<br/>改寫得更可操作"]
    G --> C
    F --> A

    style A fill:#1e3a5f,color:#fff
    style C fill:#2d5016,color:#fff
    style G fill:#4a2020,color:#fff

AGENTS.md 應該是一份「持續演進的文件」，內容來自真實的返工紀錄，而不是憑空想像的最佳實務。

8.13 本章注意事項

• ⚠️ 檔名大小寫必須完全正確：AGENTS.md。agents.md、Agents.md、AGENT.md 都不會被讀到。
• ⚠️ 32 KiB 是硬上限。超過會被截斷，且你不會收到明顯警告。內容多就拆到子目錄。
• ⚠️ 絕不在 AGENTS.md 中放任何憑證。它一定會進版控。
• ⚠️ AGENTS.override.md 建議加入 .gitignore，避免個人臨時設定影響全隊。
• ⚠️ 過時的 AGENTS.md 比沒有更糟。它會讓 Agent 自信地做錯事。
• 📌 寫完一定要驗證：codex --ask-for-approval never "Summarize current instructions."
• 📌 用 /init 產草稿，人工補業務規則。前者 Codex 很擅長，後者只有你會。
• 📌 規則要從真實返工紀錄來，不要一次寫 300 行想像出來的規範。
• 📌 AGENTS.md 是開放格式（https://agents.md/），同一份檔案可服務多種 Agent 工具，不會鎖定廠商。

9. Codex CLI Basic Usage

9.1 第一次執行【Official】

cd /path/to/your/repo
codex

就這樣。安裝完成後直接執行 codex 即可進入互動式 TUI。

第一次在某個目錄執行時，Codex 會詢問是否信任該目錄。這個決定會影響：

⚠️ 不要對來路不明的 Repository 按下信任。 一個惡意 Repository 可以透過 .codex/hooks.json 在你執行指令時觸發任意程式。詳見第 19 章。

9.2 帶著 prompt 啟動【Official】

# 直接帶入初始 prompt
codex "解釋這個專案的整體架構"

# 附加圖片（例如錯誤畫面截圖、設計稿）
codex -i ./screenshot.png "照這張設計稿實作登入頁面"

# 指定模型
codex -m gpt-5.6-sol "分析這個效能問題的根因"

# 指定 sandbox 與 approval
codex -s read-only -a untrusted "盤點本專案的所有外部依賴"

# 使用 profile
codex --profile explore

# 單次設定覆寫
codex -c model_reasoning_effort=xhigh "重構訂單狀態機"

9.3 全域旗標【Official】

以下旗標在 codex、codex exec、codex review 等多數指令上通用：

-s 與 -a 的合法值：

9.4 互動式 Slash Commands【Official】

在 TUI 的輸入框輸入 / 即可看到可用指令。

最常用的七個：

完整清單【Official】：

Codex 的 slash commands 依用途分為六類。標示 CLI 者為 Codex CLI 可用；部分指令為桌面 App / IDE 專屬，列出以避免讀者誤以為 CLI 缺少功能。

⚠️ 查證提示：官方把 slash commands 分散在三個頁面記載—— /init、/status、/permissions、/model、/review 見 https://learn.chatgpt.com/docs/codex/cli（互動式 session 選單）； /ide、/keymap、/vim、/agent、/subagents、/apps、/plugins、/hooks、/clear、/rename、/archive、/theme 見 https://learn.chatgpt.com/docs/developer-commands 的 Built-in slash commands 表格； /approve、/compact、/fast、/fork、/worktree、/side、/cloud、/reasoning、/mcp、/memories 見 https://learn.chatgpt.com/docs/reference/slash-commands。 只看單一頁面會誤以為某些指令不存在。

Skill 的呼叫【Official】：除了 slash commands，Codex CLI 另以 $skill-name 顯式呼叫已安裝的 skill（ChatGPT 端為 @skill-name）。詳見第 7.13 節。

編輯長 prompt【Official】：按 Ctrl+G 會用你系統設定的編輯器（VISUAL / EDITOR 環境變數）開啟編輯視窗，適合撰寫本手冊第 10 章那種結構化的長 prompt。

9.5 Session 管理【Official】

# 恢復最近一次 session
codex resume --last

# 恢復指定 session
codex resume <SESSION_ID>

# 從既有 session 分支出新對話（保留原 transcript）
codex fork <SESSION_ID>

# 封存 / 取消封存
codex archive <SESSION>
codex unarchive <SESSION>

# 永久刪除
codex delete <SESSION>

resume 與 fork 的差別【建議】：

📌 fork 的高價值用法【建議】：當你做完了完整的 repository 分析（花了大量 token 建立 context），要嘗試兩種不同的重構方案時——fork 兩次，各自試一種。不用重新分析一遍。

9.6 非互動模式 codex exec【Official】

這是自動化與 CI 的核心指令。

# 基本用法
codex exec "your task prompt here"

# 別名
codex e "your task prompt here"

# 從 stdin 餵資料
curl -s https://api.example.com/data | codex exec "process this data"

# 恢復非互動 session
codex exec resume --last "continue with next step"
codex exec resume <SESSION_ID>

codex exec 專屬旗標【Official】：

⚠️ 重要差異：codex exec 的 sandbox 預設為 read-only，與互動式 TUI 的預設不同。要讓它修改檔案必須明確指定 --sandbox workspace-write。這是刻意的安全設計。

輸出行為【Official】：

• 預設：進度串流到 stderr，只有最終訊息印到 stdout——這讓你可以直接用管線接給其他工具。
• --json：發出事件物件，包含 thread.started、turn.started、item.completed、turn.failed 等。

# 只取最終結果
RESULT=$(codex exec "總結本次變更" 2>/dev/null)

# 解析事件流
codex exec --json "analyze repo" | jq

# 結構化輸出
codex exec "extract metadata" --output-schema ./schema.json -o output.json

Source: https://learn.chatgpt.com/docs/non-interactive-mode

9.7 腳本化使用【建議】

範例 1：CI 中分析測試失敗

#!/usr/bin/env bash
set -euo pipefail

# 先跑測試，把輸出留下來
if mvn -q test > test-output.log 2>&1; then
  echo "測試通過，不需要分析"
  exit 0
fi

# 測試失敗 → 讓 Codex 唯讀分析（不改任何檔案）
codex exec \
  --sandbox read-only \
  --ask-for-approval never \
  --ephemeral \
  -o analysis.md \
  "$(cat <<'PROMPT'
以下是本次 CI 的測試失敗輸出（見 test-output.log）。

請分析：
1. 哪些測試失敗了
2. 每個失敗的最可能根因（指出具體檔案與行號）
3. 建議的修正方向（不要修改任何檔案）
4. 這些失敗是否互有關聯

輸出 Markdown，供人工判讀。
PROMPT
)"

echo "分析完成，見 analysis.md"
exit 1

範例 2：批次為多個模組產生文件

#!/usr/bin/env bash
set -euo pipefail

for module in order payment inventory shipping; do
  echo "==> 分析 ${module}"
  codex exec \
    --sandbox read-only \
    --ask-for-approval never \
    -o "docs/modules/${module}.md" \
    "分析 backend/${module}-service 模組，產出：職責說明、對外介面清單、依賴關係、資料表使用、已知風險。輸出 Markdown。"
done

範例 3：用 --output-schema 取得結構化結果

schema.json：

{
  "type": "object",
  "properties": {
    "risk_level": { "type": "string", "enum": ["low", "medium", "high"] },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": { "type": "string" },
          "line": { "type": "integer" },
          "issue": { "type": "string" },
          "severity": { "type": "string", "enum": ["info", "warning", "error"] }
        },
        "required": ["file", "issue", "severity"]
      }
    }
  },
  "required": ["risk_level", "findings"]
}

codex exec \
  --sandbox read-only \
  --output-schema ./schema.json \
  -o findings.json \
  "審查 backend/payment-service 的安全性問題"

# 結果可直接餵給後續工具
jq -r '.findings[] | select(.severity=="error") | "\(.file):\(.line) \(.issue)"' findings.json

📌 --output-schema 是把 Codex 接進既有工具鏈的關鍵。有了結構化輸出，你可以把結果寫進資料庫、開成 Jira 工單、或轉成 SARIF 餵給 GitHub Code Scanning。

9.8 常用維運指令【Official】

9.9 Plugins【Official】

自 0.153.0 起，Plugin CLI 可以從遠端 marketplace 列出、安裝與移除 plugin。

codex plugin              # 管理已安裝的 plugin
codex plugin marketplace  # 管理 plugin 來源

TUI 中則用 /plugins。

⚠️ 企業注意事項【建議】：Plugin 會擴充 Agent 的能力，等同於擴大攻擊面。企業應：

1. 建立核可的 plugin 白名單。
2. 禁止開發者自行從公開 marketplace 安裝未經審查的 plugin。
3. 把 plugin 納入第 28 章的變更管理流程。

9.10 每個常用指令的完整說明【Official / 建議】

以下依「語法 / 參數 / 用途 / 範例 / 注意事項 / 常見錯誤」格式整理最重要的六個指令。

codex（互動式）

codex exec

codex resume

codex review

codex doctor

codex mcp

9.11 一天的典型工作流【建議】

flowchart TD
    A["早上：git pull<br/>確認 working tree 乾淨"] --> B["codex --profile explore<br/>唯讀理解今天要動的區域"]
    B --> C["/plan<br/>要求 Agent 先出計畫"]
    C --> D{"計畫方向對嗎？"}
    D -->|"否"| E["補充資訊 / 修正目標"]
    E --> C
    D -->|"是"| F["/permissions<br/>切換到 workspace-write"]
    F --> G["讓 Agent 執行"]
    G --> H["git diff<br/>逐行審查"]
    H --> I{"可接受？"}
    I -->|"否"| J["說明問題，要求修正"]
    J --> G
    I -->|"是"| K["自己跑一次完整測試"]
    K --> L["codex review<br/>機械檢查"]
    L --> M["git add / commit<br/>（由人執行）"]
    M --> N["開 PR，人工 review"]

    style B fill:#1e3a5f,color:#fff
    style C fill:#3d2b5f,color:#fff
    style H fill:#7a3b12,color:#fff
    style N fill:#2d5016,color:#fff

這個流程的四個關鍵設計【建議】：

1. 先唯讀理解，再開放寫入——降低誤改的機率。
2. 先看計畫再執行——最便宜的糾錯時機。
3. git diff 由人逐行看——這是不可省略的一步。
4. git commit 由人執行——AGENTS.md 中應明確禁止 Agent 自行 commit。

9.12 Git Worktree 與平行 Session【Official】

當你想「讓 Codex 在背景做一個大任務，同時自己繼續在同一個 repo 上開發」，最直覺的做法是開兩個終端機——然後兩邊互相踩到對方的工作目錄。Codex 對這個問題的官方解法是 Git worktree。

9.12.1 它解決什麼【Official】

Git worktree 是 Git 原生功能：同一個 repository 可以有多個獨立的 checkout，共用同一份 repository metadata。Codex 直接把它整合進 session 模型，讓多個 chat 可以在同一個專案上互不干擾地平行工作。

9.12.2 使用方式【Official】

/worktree      # 在新的 Git worktree 中執行本 chat
/fork          # 把目前 chat 複製成新 chat 或新的 worktree（保留既有 context）
/local         # 把 chat 切回指定的本機專案

Codex 預設把受管的 worktree 放在 $CODEX_HOME/worktrees，且通常置於 detached HEAD 狀態，以避免分支衝突。

9.12.3 兩種收斂路徑【Official】

9.12.4 必須知道的限制【Official】

⚠️ 同一個分支不能同時存在於多個 worktree。 這是 Git 本身的限制，不是 Codex 的：

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

實務上這代表：不要讓 Agent 和你同時 checkout 同一個分支。讓 Agent 在 detached HEAD 上工作、完成後才建立分支，是官方預設行為，也是正確的做法。

9.12.5 自動清理【Official】

Codex 預設保留最近 15 個受管 worktree，較舊的會自動刪除，同時保留已封存工作的快照。

⚠️ 不要把唯一的成果留在 worktree 裡。 15 個的滾動視窗在頻繁使用平行 session 的團隊中可能只有幾天。任何有價值的產出都應該commit 並 push 到 remote 分支，或用 Handoff 帶回主 checkout。

9.12.6 企業應用模式【建議】

📌 與 codex fork 的關係【建議】：/fork 複製的是 chat context，/worktree 切換的是 檔案系統環境。兩者常一起用——「保留目前已建立的分析理解，但換一個乾淨的工作目錄去試另一種實作」正是 /fork 到新 worktree 的典型場景。

9.13 本章實務案例【建議】

情境：一位工程師被指派修一個「使用者上傳超過 10 MB 檔案時系統會 500 錯誤」的 bug。

完整操作紀錄：

# 1. 確認起點乾淨，開新分支
git status
git switch -c fix/large-file-upload

# 2. 唯讀理解問題範圍
codex --profile explore

> 系統在使用者上傳超過 10 MB 的檔案時回傳 500。
> 請以唯讀方式分析：
> 1. 檔案上傳的完整處理路徑（從 Controller 到實際寫入）
> 2. 目前有哪些大小限制設定（應用層、框架層、反向代理層）
> 3. 500 錯誤最可能發生在哪一層，理由是什麼
> 4. 現有測試涵蓋了哪些上傳情境
> 不要修改任何檔案。

Agent 的分析指出：application.yml 的 spring.servlet.multipart.max-file-size 設為 10 MB，但例外處理沒有攔截 MaxUploadSizeExceededException，導致直接拋出 500 而非 413。

# 3. 先出計畫
> /plan
> 目標：超過大小限制時回傳 413 Payload Too Large 與清楚的錯誤訊息，
> 而不是 500。同時補上對應的測試。
> 限制：不要調整 max-file-size 的值（那是產品決策，不是這次的範圍）。

Agent 提出計畫：新增 @ExceptionHandler 處理該例外、定義錯誤回應格式、補 1 個整合測試。

# 4. 確認計畫後切換權限並執行
> /permissions
（切換為 workspace-write）

> 依照剛才的計畫執行。完成後執行 mvn -q test -Dtest=FileUploadControllerTest。

# 5. 人工審查
git diff

# 6. 自己完整跑一次
mvn -q test

# 7. 機械檢查
codex review

# 8. 人工 commit（Agent 被 AGENTS.md 禁止 commit）
git add -A
git commit -m "fix: 上傳超過大小限制時回傳 413 而非 500"

這個案例展示的四個要點：

9.14 本章注意事項

• ⚠️ codex exec 預設 read-only，與互動式不同。CI 中要寫檔案必須明確加 --sandbox workspace-write。
• ⚠️ CI 中務必加 --ask-for-approval never，否則會卡在等待核准而超時。
• ⚠️ 不要在 CI 中執行互動式 codex。
• ⚠️ 信任目錄的決定要謹慎。不受信任的專案略過 .codex/，這是保護你的機制。
• ⚠️ plugin 會擴大攻擊面。企業應建立白名單。
• 📌 /plan 是投報率最高的習慣。任何非瑣碎任務都先用它。
• 📌 /status 隨時確認自己在什麼權限模式下。很多意外來自「以為自己在唯讀模式」。
• 📌 fork 可以省下重複建立 context 的成本，嘗試多種方案時很划算。
• 📌 --output-schema 是把 Codex 接進既有工具鏈的橋樑，值得花時間學。
• 📌 git commit 應該由人執行，並在 AGENTS.md 中明確禁止 Agent 自行 commit。

10. Prompt Engineering for Codex

10.1 為什麼「Fix this bug」不夠【建議】

先看一個真實對比。

低品質 prompt：

Fix this bug.

Agent 會怎麼做？它必須自己猜：哪個 bug？在哪個檔案？什麼是「修好了」？該不該動測試？該不該改介面？結果是大量的探索性工具呼叫（燒 token）、基於猜測的修改（可能改錯地方）、沒有明確的完成標準（它不知道何時該停）。

高品質 prompt：

# Context
訂單取消功能在訂單已出貨後仍可被取消，導致庫存與出貨紀錄不一致。
相關程式碼在 backend/order-service/。

# Objective
讓 OrderService.cancelOrder(orderId) 在訂單狀態為 SHIPPED 或 DELIVERED 時
拋出 IllegalStateException，並附帶清楚的錯誤訊息。

# Constraints
- 不要修改 OrderStatus 列舉的定義
- 不要更動 Controller 層的 API 契約
- 不要調整既有測試的斷言；若既有測試因此失敗，先說明原因再處理

# Acceptance Criteria
1. cancelOrder 對 SHIPPED / DELIVERED 訂單拋出 IllegalStateException
2. 對 PENDING / CONFIRMED 訂單維持原行為
3. 新增測試涵蓋這四種狀態
4. mvn -q test 全部通過

# Validation
執行 mvn -q -pl backend/order-service test 並貼出結果。

差異不在「字比較多」，而在每一段都消除了一個 Agent 必須猜測的東西。

10.2 企業級 Prompt Template【建議】

這是本手冊建議的標準結構。不是每次都要寫滿，但應該心裡有這張清單：

# Context
（現況、背景、為什麼要做這件事）

# Objective
（明確要達成什麼，一到三句話）

# Repository
（相關檔案、模組、進入點。指出來能省下大量摸索）

# Constraints
（不要做什麼。這一段常比「要做什麼」更重要）

# Architecture Rules
（必須遵守的分層、依賴方向、設計模式）

# Implementation Requirements
（具體的實作要求）

# Security Requirements
（輸入驗證、憑證處理、日誌遮罩等）

# Testing Requirements
（要寫什麼測試、用什麼框架、命名慣例）

# Acceptance Criteria
（可驗證的完成條件，最好是編號清單）

# Validation
（要執行哪些指令來證明完成了）

# Deliverables
（要交出什麼：程式碼？文件？報告？）

九成的場合只需要其中五段【建議】：

# Context
# Objective
# Constraints
# Acceptance Criteria
# Validation

📌 如果你只記得一件事：Constraints 與 Acceptance Criteria 是投報率最高的兩段。 前者防止 Agent 做多餘的事，後者讓它知道何時該停。

10.3 Prompt 的七個原則【建議】

10.4 Prompt 範本庫（十種任務類型）【建議】

以下十個範本可直接複製使用。第 48 章 有更完整的版本。

範本 A：Bug Fix

# Context
<系統在什麼情況下出現什麼錯誤現象；使用者影響；何時開始發生>

# Repository
相關程式碼推測在 <路徑>。相關測試在 <路徑>。

# Objective
修正這個問題，使 <明確的正確行為>。

# Constraints
- 先找出根因再修，不要只處理症狀
- 不要修改 <不該動的範圍>
- 不要改動既有測試的斷言以讓測試通過
- 保持 diff 最小

# Acceptance Criteria
1. <錯誤情境> 不再發生，改為 <正確行為>
2. <正常情境> 的行為維持不變
3. 新增測試涵蓋此情境
4. <驗證指令> 全數通過

# Validation
執行 <驗證指令> 並貼出結果。

# Deliverables
1. 程式碼修改
2. 根因說明（為什麼會發生）
3. 你發現但沒處理的相關問題（如果有）

範本 B：Feature Development

# Context
<業務背景；為什麼需要這個功能；使用者是誰>

# Objective
實作 <功能名稱>：<一到三句話說明功能行為>

# Repository
- 後端：<模組路徑>
- 前端：<模組路徑>
- 參考既有的類似實作：<路徑>（請遵循相同的模式）

# Architecture Rules
- 分層：Controller → Service → Repository，禁止跨層
- 新增 endpoint 必須同步更新 <OpenAPI 檔案路徑>
- DTO 與 Entity 分離，不得直接回傳 Entity

# Implementation Requirements
1. <具體要求 1>
2. <具體要求 2>

# Security Requirements
- 所有輸入使用 Bean Validation 驗證
- <此功能的特殊安全考量>

# Testing Requirements
- Service 層單元測試，覆蓋正常路徑與 <列出邊界情境>
- Controller 層測試驗證輸入驗證與狀態碼

# Acceptance Criteria
1. <可驗證的條件>
2. <可驗證的條件>
3. <驗證指令> 全綠

# Validation
執行 <驗證指令>。

# Deliverables
程式碼 + 測試 + OpenAPI 更新 + 一段變更說明

範本 C：Refactoring

# Context
<這段程式碼目前的問題：太長、重複、難測試、耦合過深>

# Objective
重構 <目標範圍>，達成 <具體的結構目標>。

# ⚠️ 最重要的限制
**這是純重構：外部行為必須完全不變。**
不要修正任何 bug、不要改變任何 API、不要調整任何業務邏輯。
若你在過程中發現 bug，請記下來回報，但**不要修**。

# Constraints
- 不新增或移除任何 public method 的簽章
- 不改變任何對外行為
- 不修改測試（測試是這次重構的安全網）
- 若既有測試失敗，代表你改變了行為 → 回退並重新思考

# Acceptance Criteria
1. <結構目標，例如：沒有超過 40 行的方法>
2. 所有既有測試**未經修改**即通過
3. <驗證指令> 全綠

# Validation
1. 先執行 <測試指令>，確認起點是綠的
2. 重構
3. 再執行 <測試指令>，必須仍是綠的

# Deliverables
程式碼 + 重構說明 + 你發現但未修的問題清單

範本 D：Code Review

# Context
請審查 <目標：未提交變更 / 某個 PR / 某個 commit range>。

# Objective
以資深工程師的標準做 code review，找出真正的問題。

# Review Dimensions
請依序檢查以下面向，每一項都要明確回答「有問題」或「沒問題」：

1. **正確性**：邏輯錯誤、邊界條件、null 處理、併發問題
2. **安全性**：注入風險、認證授權、敏感資料處理、依賴風險
3. **架構**：是否違反分層、是否引入不當耦合、是否重複既有功能
4. **錯誤處理**：例外是否被吞掉、錯誤訊息是否有用、是否有資源洩漏
5. **測試**：新增邏輯是否有測試、測試是否真的能抓到問題
6. **效能**：N+1 查詢、不必要的迴圈、大物件複製
7. **可維護性**：命名、複雜度、註解是否必要且正確

# Constraints
- **不要修改任何程式碼**，只做審查
- 每個問題必須指出具體的檔案與行號
- 區分「必須修」與「建議改」
- 不要為了湊數量而報告瑣碎的風格問題

# Deliverables
Markdown 報告，格式：

## 必須修正（Blocking）
| 檔案:行號 | 問題 | 為什麼是問題 | 建議 |

## 建議改善（Non-blocking）
| 檔案:行號 | 問題 | 建議 |

## 沒有問題的面向
（明確列出你檢查過且認為沒問題的面向）

範本 E：Testing

# Context
<目標模組> 目前測試覆蓋不足 / 沒有測試。

# Objective
為 <目標範圍> 建立測試。

# Test Type
<選一種>
- Characterization Test：**鎖住現有行為**（不管它對不對），供後續重構使用
- Unit Test：驗證單一類別的邏輯正確性
- Integration Test：驗證跨元件協作

# Constraints
- 使用 <測試框架與斷言函式庫>
- 遵循既有測試的風格（參考 <既有測試路徑>）
- 測試命名：<命名慣例>
- **不要為了讓測試通過而修改被測程式碼**
- 測試必須能真正抓到問題（不要寫只斷言「不拋例外」的空測試）

# Coverage Requirements
必須涵蓋：
1. 正常路徑
2. <列出具體的邊界情境>
3. <列出具體的例外情境>

# Acceptance Criteria
1. 新增測試全數通過
2. 既有測試不受影響
3. <覆蓋率目標，如果有>

# Validation
執行 <測試指令> 並貼出結果。

範本 F：Migration / Upgrade

# Context
目前使用 <舊版本>，需要升級到 <新版本>。
<為什麼要升：安全性、支援期限、需要新功能>

# ⚠️ 執行方式
**這是分階段任務。本次只執行第 <N> 階段。**

# 本階段的 Objective
<這一階段要做什麼，範圍要小到可以人工審查>

# Constraints
- **絕對不要一次改完所有東西**
- 不要動 <明確的範圍外>
- 每改完一個檔案就執行 <編譯指令>
- 遇到不確定的 breaking change，停下來問我，不要自己猜

# Acceptance Criteria
1. <本階段的具體完成條件>
2. <編譯指令> 通過
3. <測試指令> 通過（或明確列出哪些失敗與原因）

# Validation
1. <編譯指令>
2. <測試指令>

# Deliverables
1. 程式碼變更
2. 本階段變更摘要
3. 遇到的 breaking change 清單與處理方式
4. 下一階段的建議範圍

範本 G：Reverse Engineering

# Context
這是一個 <技術棧> 的 <年份> 系統，原開發人員已離職，沒有文件。

# Objective
分析並產出 <特定面向> 的技術文件。

# ⚠️ 嚴格限制
**唯讀模式。不要修改任何檔案。**
分析結果寫到 <輸出路徑>。

# Analysis Scope
請依序分析：
1. <面向 1，例如：目錄結構與模組職責>
2. <面向 2，例如：進入點與請求處理流程>
3. <面向 3，例如：資料存取方式與資料表使用>

# Output Requirements
- 使用繁體中文
- 包含 Mermaid 圖表
- **明確區分「從程式碼確認的事實」與「你的推測」**
  - 事實請註明檔案路徑與行號
  - 推測請標註「推測」並說明依據
- 不確定的地方請列成「待確認清單」，不要自行填空

# Deliverables
Markdown 文件，含：
1. 概觀
2. 詳細分析（含圖表）
3. 事實 vs 推測的區分
4. 待確認清單
5. 你觀察到的風險

範本 H：Documentation

# Context
<為什麼需要這份文件；讀者是誰>

# Objective
為 <目標範圍> 產生 <文件類型>。

# Source of Truth
**以實際程式碼為準**，不要依賴既有文件（可能已過時）。
若發現程式碼與既有文件不符，請明確指出。

# Constraints
- 唯讀，不修改程式碼
- 不要編造程式碼中不存在的行為
- 不確定的地方標註「待確認」

# Content Requirements
1. <章節 1>
2. <章節 2>

# Format
- Markdown
- 繁體中文，技術名詞保留英文
- 複雜流程用 Mermaid 圖表
- 程式碼引用需附檔案路徑

# Deliverables
輸出到 <路徑>

範本 I：Performance Optimization

# Context
<哪個功能慢；目前的量測數據；使用者感受>

# Objective
找出效能瓶頸並改善，目標 <具體數字>。

# ⚠️ 方法論要求
**先量測，再優化。禁止憑直覺改。**

執行順序：
1. 建立可重複的量測方式（benchmark / 壓測腳本 / EXPLAIN）
2. 量測目前基準，記錄數字
3. 找出瓶頸，說明證據
4. 提出優化方案並說明預期效果
5. **等我確認後**再實作
6. 實作後重新量測，比較前後數字

# Constraints
- 不要為了效能犧牲正確性
- 不要引入快取來掩蓋根本問題（除非快取本身就是正解，並說明失效策略）
- 所有既有測試必須仍然通過
- 不要一次做多個優化（無法判斷哪個有效）

# Acceptance Criteria
1. <具體的效能目標數字>
2. 所有既有測試通過
3. 有前後對照的量測數據

# Deliverables
1. 量測方法與腳本
2. 前後數據對照
3. 程式碼變更
4. 瓶頸分析說明

範本 J：Security Review

# Context
請對 <目標範圍> 做安全性審查。

# ⚠️ 嚴格限制
**唯讀。不要修改任何檔案。不要執行任何會產生外部連線的指令。**

# Review Checklist
請逐項檢查並明確回答：

1. **注入類**：SQL 注入、命令注入、路徑穿越、XSS、XXE、反序列化
2. **認證授權**：驗證是否可繞過、權限檢查是否遺漏、水平/垂直越權
3. **敏感資料**：硬編碼憑證、日誌洩漏、錯誤訊息洩漏、未加密傳輸與儲存
4. **輸入驗證**：邊界檢查、型別驗證、大小限制、檔案上傳
5. **依賴風險**：已知漏洞的套件、來源不明的依賴
6. **設定安全**：預設密碼、除錯模式、過度寬鬆的 CORS / 權限
7. **業務邏輯**：競態條件、重放攻擊、金額/數量的邊界

# Constraints
- 每個發現必須指出檔案與行號
- 標註嚴重程度（Critical / High / Medium / Low）
- 說明**可利用性**（攻擊者實際要怎麼做）
- 不確定是否為真問題時，標註「需人工確認」
- **不要產生誤報來湊數**

# Deliverables
Markdown 報告：

## 發現摘要
| 嚴重度 | 數量 |

## 詳細發現
### [嚴重度] 標題
- 位置：檔案:行號
- 說明：
- 可利用性：
- 建議修正：

## 已檢查且無問題的項目

10.5 Prompt 的常見錯誤【建議】

10.6 迭代式 Prompt 策略【建議】

複雜任務不要用一個 prompt 解決，用三段式：

flowchart LR
    P1["① 理解<br/>read-only<br/>「分析並說明現況」"] --> V1["人：確認理解正確"]
    V1 --> P2["② 規劃<br/>read-only<br/>「提出方案與計畫」"]
    P2 --> V2["人：確認方案可行"]
    V2 --> P3["③ 執行<br/>workspace-write<br/>「依計畫執行第 N 步」"]
    P3 --> V3["人：審查 diff"]
    V3 --> D{"還有下一步？"}
    D -->|"是"| P3
    D -->|"否"| DONE["完成"]

    style P1 fill:#1e3a5f,color:#fff
    style P2 fill:#3d2b5f,color:#fff
    style P3 fill:#2d5016,color:#fff
    style V1 fill:#7a3b12,color:#fff
    style V2 fill:#7a3b12,color:#fff
    style V3 fill:#7a3b12,color:#fff

為什麼這樣做更省錢【建議】：階段 ① 與 ② 用唯讀模式與較便宜的模型即可，且在方向錯誤時，糾正成本只是一句話。若直接進入階段 ③，方向錯了就是整個 diff 作廢，前面燒的 token 全部浪費。

10.7 本章實務案例【建議】

情境：同一個需求「加一個匯出訂單為 Excel 的功能」，三種 prompt 品質的實際結果對比。

版本 1（30 秒寫完）：

加一個匯出訂單成 Excel 的功能。

結果：Agent 自行選了一個團隊沒在用的套件（EasyExcel）、把邏輯全塞在 Controller、沒有分頁（大量資料會 OOM）、沒有測試、沒有權限檢查。返工率 100%。

版本 2（3 分鐘寫完）：

在 OrderController 加一個匯出訂單為 Excel 的 endpoint。
用專案已有的 POI，遵循現有分層，記得加測試。

結果：套件對了、分層對了、有測試。但仍缺：分頁處理、權限檢查、欄位定義（Agent 自己決定匯出哪些欄位，其中包含了不該外流的成本價）、大檔案的串流處理。返工率約 40%。

版本 3（8 分鐘寫完）：

# Context
業務單位需要把訂單查詢結果匯出成 Excel 供對帳使用。
現有的訂單查詢 API 在 OrderController.searchOrders()。

# Objective
新增 GET /api/orders/export endpoint，接受與 searchOrders 相同的查詢條件，
回傳 Excel 檔案。

# Repository
- Controller: backend/order-service/src/main/java/.../OrderController.java
- Service:    backend/order-service/src/main/java/.../OrderService.java
- 參考既有的匯出實作：backend/report-service/.../ReportExportService.java
  （請遵循相同的模式與工具類別）

# Architecture Rules
- Excel 產生邏輯放在 Service 層，Controller 只負責參數綁定與回應標頭
- 使用專案既有的 Apache POI 封裝（見 ExcelWriterUtils）

# Implementation Requirements
1. **必須分頁處理**：使用 SXSSFWorkbook 串流寫出，每批 1000 筆，
   避免大量資料造成 OOM
2. 匯出欄位固定為：訂單編號、下單日期、客戶名稱、商品名稱、數量、
   訂單金額、狀態
   ⚠️ **不得匯出成本價、利潤、內部備註** — 這些是內部資訊
3. 檔名格式：orders_yyyyMMddHHmmss.xlsx
4. 單次匯出上限 50000 筆，超過回傳 400 並提示縮小查詢範圍

# Security Requirements
- 需要 ORDER_EXPORT 權限（參考既有的 @PreAuthorize 用法）
- 匯出動作必須寫入 audit log（參考 AuditLogService）

# Testing Requirements
- Service 層測試：正常匯出、空結果、超過上限、欄位正確性
- Controller 層測試：權限不足回 403、參數錯誤回 400
- 使用 JUnit 5 + AssertJ，命名遵循 方法名_情境_預期結果

# Acceptance Criteria
1. 匯出的 Excel 只包含指定的 7 個欄位
2. 5 萬筆資料匯出不會 OOM（heap 設 512MB 下測試）
3. 無 ORDER_EXPORT 權限者回傳 403
4. 超過 5 萬筆回傳 400
5. mvn -q -pl backend/order-service test 全綠

# Validation
執行 mvn -q -pl backend/order-service test 並貼出結果。

# Deliverables
程式碼 + 測試 + OpenAPI 更新 + 變更說明

結果：一次到位。返工率約 5%（只有一個錯誤訊息文案需要調整）。

投報分析：

📌 這就是為什麼 Prompt Engineering 值得投資。 花 8 分鐘寫 prompt，省下 3 小時返工——而且版本 3 的產出品質最高，因為那些安全與效能要求，Agent 自己想不到。

最關鍵的一段是哪一段？——是 Implementation Requirements 中的第 2 點。「不得匯出成本價」是業務規則，Agent 沒有任何辦法自己知道。 這正是第 1 章說的：「Human 負責 Intent，Agent 負責 Execution」。

10.8 本章注意事項

• ⚠️ 業務規則 Agent 永遠猜不到。任何涉及「哪些資料能給誰看」「這個金額怎麼算」的規則，都必須明確寫出來。
• ⚠️ 沒有 Constraints 的 prompt 等於授權 Agent 自由發揮。範圍外的事一定要寫。
• ⚠️ 不要在 prompt 中貼大量程式碼。指出路徑讓 Agent 自己讀，省 token 且它讀到的是最新版本。
• ⚠️ 「盡量」「應該」「最好」這類詞在 prompt 中沒有意義。要嘛是要求，要嘛不是。
• 📌 Constraints + Acceptance Criteria 是最重要的兩段。時間有限就先寫這兩段。
• 📌 複雜任務用三段式：理解（唯讀）→ 規劃（唯讀）→ 執行（可寫）。方向錯誤的糾正成本最低。
• 📌 重構任務一定要寫「外部行為必須完全不變」，否則 Agent 會順手「改善」邏輯。
• 📌 把常用的 prompt 存成檔案，用 codex exec "$(cat prompts/bugfix.md)" 呼叫，或放進第 48 章的 Prompt Library。

11. Repository Understanding

11.1 為什麼「理解」要單獨成為一個階段【建議】

大多數 Agent 使用失敗，根因不是「模型不夠聰明」，而是它在還沒理解系統的情況下就開始修改。

一個沒有 context 的 Agent 會：用通用寫法而非專案慣例、漏掉隱含的依賴、動到不該動的地方、重複實作已存在的功能。

理解階段的產出，是後續所有工作的地基。 而且它是唯讀的——成本低、風險零、可重複執行。

11.2 理解的七個層次【建議】

flowchart TD
    R["Repository<br/>原始檔案"] --> S["① Structure<br/>目錄結構、模組劃分"]
    S --> A["② Architecture<br/>分層、元件、職責"]
    A --> D["③ Dependencies<br/>內部依賴 + 外部套件"]
    D --> RT["④ Runtime<br/>如何建置、如何啟動、如何部署"]
    RT --> DF["⑤ Data Flow<br/>資料從哪來、經過什麼、存到哪"]
    DF --> BF["⑥ Business Flow<br/>業務規則與流程"]
    BF --> T["⑦ Tests<br/>測試涵蓋什麼、不涵蓋什麼"]

    S -.->|"最容易<br/>Agent 幾乎不會錯"| EASY["高可信度"]
    T -.->|"最困難<br/>需要人工驗證"| HARD["需人工確認"]
    BF -.-> HARD

    style R fill:#1e3a5f,color:#fff
    style EASY fill:#2d5016,color:#fff
    style HARD fill:#4a2020,color:#fff

📌 關鍵認知【建議】：越往下層，Agent 的可信度越低。 目錄結構它幾乎不會錯；業務規則它經常「合理地猜錯」。因此第 ⑥ 層的產出必須由熟悉業務的人驗證。

11.3 標準的理解流程【建議】

永遠以 read-only 模式進行。

codex --profile explore

步驟 1：全景盤點

# Objective
建立本 Repository 的全景認識。

# ⚠️ 限制
唯讀。不要修改任何檔案。

# 請依序回答
1. 這是什麼系統？（從 README、package.json/pom.xml、目錄結構推斷）
2. 技術棧盤點：語言、框架、建置工具、資料庫、訊息中介軟體，各自的版本
3. 頂層目錄結構，每個目錄的職責（一句話）
4. 模組劃分：有幾個可獨立建置/部署的單元
5. 進入點：main 方法、Controller、CLI 指令、排程任務、消費者
6. 建置與執行方式：完整的指令
7. 設定檔清單：哪些檔案控制什麼

# 輸出要求
- 明確區分「從檔案確認的事實」與「推測」
- 事實請附檔案路徑
- 不確定的列成「待確認清單」

步驟 2：架構與依賴

# Objective
分析架構與依賴關係。

# ⚠️ 唯讀

# 請分析
1. 分層架構：實際的分層是什麼？（不要照抄理論，看實際程式碼）
2. 模組間依賴：畫出依賴圖（Mermaid），標出是否有循環依賴
3. 外部依賴：列出所有第三方套件、各自的用途與版本
4. 依賴風險：有沒有已停止維護的、版本過舊的、重複功能的
5. 有沒有違反分層原則的地方？（例如 Controller 直接呼叫 Repository）

# 輸出
Mermaid 依賴圖 + 表格 + 風險清單

步驟 3：資料流與 API 流

# Objective
還原資料在系統中的流動路徑。

# ⚠️ 唯讀

# 請針對以下三條路徑逐層追蹤
（若不清楚該追哪些，先列出所有對外 endpoint 再問我）

1. <路徑 1，例如：使用者下單>
2. <路徑 2>
3. <路徑 3>

# 每條路徑請說明
- 進入點（HTTP method + path，或事件名稱）
- 經過的每一層（類別名稱 + 檔案路徑）
- 每一層做了什麼轉換
- 存取了哪些資料表
- 呼叫了哪些外部系統
- 錯誤如何處理

# 輸出
每條路徑一張 Mermaid sequence diagram + 文字說明

步驟 4：認證授權與錯誤處理

# Objective
理解橫切關注點的實作方式。

# ⚠️ 唯讀

# 請分析
1. **認證**：使用什麼機制？在哪裡實作？token 如何驗證與更新？
2. **授權**：權限如何定義與檢查？有沒有遺漏檢查的 endpoint？
3. **錯誤處理**：全域例外處理在哪？錯誤回應格式？有沒有吞例外的地方？
4. **日誌**：用什麼框架？記錄了什麼？有沒有記錄敏感資料？
5. **交易管理**：交易邊界在哪一層？有沒有明顯的問題？

# 輸出
每一項的實作位置（檔案路徑）+ 說明 + 你觀察到的問題

步驟 5：測試現況

# Objective
盤點測試現況，找出風險區域。

# ⚠️ 唯讀

# 請分析
1. 測試框架與工具
2. 測試分類：單元 / 整合 / E2E 各有多少
3. **哪些模組完全沒有測試**（這是最重要的一題）
4. 既有測試的品質：有沒有「只驗證不拋例外」這種無效測試
5. 測試如何執行？完整指令是什麼？大概要跑多久？
6. 有沒有測試依賴外部環境（真實資料庫、真實 API）

# 輸出
覆蓋現況表格 + **無測試模組清單（依風險排序）**

11.4 大型 Repository 的處理策略【建議】

當 Repository 大到無法一次分析時：

找變更熱點的指令【建議】：

# 過去一年變更最頻繁的 20 個檔案
git log --since="1 year ago" --name-only --pretty=format: \
  | sort | uniq -c | sort -rn | head -20

# 最多人碰過的檔案（通常是核心）
git log --since="1 year ago" --format='%an' --name-only \
  | awk 'NF' | sort -u | head -40

📌 變更熱點通常就是：核心業務邏輯、技術債集中處、或設計不良需要反覆修改的地方。三者都值得優先理解。

11.5 把理解結果沉澱下來【建議】

分析完就結束，等於白做。理解的產出必須沉澱成兩種資產：

flowchart LR
    ANA["Codex 分析"] --> DOC["① 給人看的文件<br/>docs/architecture/"]
    ANA --> AGT["② 給 Agent 看的指引<br/>AGENTS.md"]

    DOC --> HUM["新人 onboarding<br/>架構討論<br/>技術決策依據"]
    AGT --> NEXT["下一次 Agent 任務<br/>直接具備 context"]

    NEXT -.->|"品質提升"| ANA

    style ANA fill:#1e3a5f,color:#fff
    style DOC fill:#2d5016,color:#fff
    style AGT fill:#3d2b5f,color:#fff

具體做法：

# 分析階段產出人看的文件
codex exec --sandbox read-only -o docs/architecture/overview.md \
  "<步驟 1 的 prompt>"

# 然後把「Agent 需要知道的部分」濃縮進 AGENTS.md

什麼該進 AGENTS.md、什麼該進 docs/【建議】：

📌 判準：問自己「Agent 不知道這件事會不會做錯？」——會，就進 AGENTS.md；不會但人需要知道，就進 docs/。

11.6 驗證 Agent 的理解是否正確【建議】

Agent 的分析看起來永遠很有說服力，這是最大的陷阱。三種驗證方法：

降低幻覺的 prompt 技巧【建議】：在 prompt 中明確要求：

# 輸出要求
- **每一個事實陳述都必須附上檔案路徑**（格式：`path/to/File.java:123`）
- 無法從程式碼確認的內容，一律標註為「推測」並說明推測依據
- 不確定的內容放進「待確認清單」，**不要為了讓文件看起來完整而填空**
- 若某個問題你無法從程式碼回答，就直接說「無法從程式碼判斷」

這幾句話能大幅降低幻覺率——因為要附檔案路徑，就不容易編造。

11.7 本章實務案例【建議】

情境：接手一個 8 年的 Spring MVC 專案，2,300 個 Java 檔案，沒有文件，沒有測試。

執行紀錄（實際耗時 2.5 天）：

人工驗證階段（0.5 天）：

抽查了 20 個 Agent 標為「事實」的陳述：

那個錯誤很有代表性：程式碼還在、註冊還在，但實際上被外部設定關掉了——這是 Agent 從程式碼無法知道的資訊。

沉澱成果：

docs/arch/
├── 00-overview.md          （全景）
├── 01-dependencies.md      （依賴圖 + 風險）
├── 02-flow-order.md        （下單流程）
├── 03-flow-reconcile.md    （對帳流程）
├── 04-flow-batch.md        （日終批次）
├── 05-cross-cutting.md     （認證/授權/錯誤/日誌）
├── 06-test-coverage.md     （測試現況 + 風險排序）
└── 99-open-questions.md    （待確認清單，共 23 條）

同時建立 AGENTS.md：

# AGENTS.md

## 建置與測試
| 目的 | 指令 |
| --- | --- |
| 編譯 | `mvn -q compile` |
| 測試 | `mvn -q test`（約 4 分鐘） |
| 打包 | `mvn -q package -DskipTests` |

## 架構現況（2026-09 分析）
- Spring MVC 4.3 + MyBatis + Oracle
- 分層：Controller → Service → Mapper（MyBatis）
- ⚠️ 現存兩處循環依賴：`OrderService ↔ InventoryService`、
  `BatchScheduler ↔ ReportService`。**不要加深這些依賴。**

## 高風險區域（動之前先問）
- `OrderProcessor.java`（4,200 行，零測試，核心邏輯）
- `BatchScheduler.java`（日終批次，出錯影響對帳）
- 任何 `*Mapper.xml`（手寫 SQL，改動風險高）

## 規則
1. **本專案測試覆蓋率極低（約 4%）。修改任何邏輯前，先為該處建立
   characterization test 鎖住現有行為。**
2. 禁止在 Controller 中直接注入 Mapper。
3. SQL 一律寫在 `*Mapper.xml`，不要用 annotation SQL（與現有風格不一致）。
4. `legacy-batch/` 目錄凍結中，唯讀。

兩週後的效果：新加入的兩位工程師，onboarding 時間從預估的 3 週縮短到 5 天；後續所有 Codex 任務的返工率明顯下降，因為 AGENTS.md 已經包含關鍵 context。

11.8 本章注意事項

• ⚠️ 理解階段一律唯讀。這階段不該有任何檔案被修改。
• ⚠️ 業務規則的分析必須人工驗證。Agent 會把「程式碼看起來在做什麼」當成「業務上應該是什麼」，這兩者經常不同。
• ⚠️ 程式碼無法告訴你的事：外部設定關掉的功能、實際上沒人用的 endpoint、口頭約定的規則、生產環境的實際行為。這些都要靠人補。
• ⚠️ 不要相信沒有檔案路徑的陳述。在 prompt 中強制要求附路徑。
• 📌 分析成果必須沉澱，否則下一個人（和下一次 Agent 任務）又要重來。
• 📌 AGENTS.md 與 docs/ 的分工：Agent 不知道會做錯的 → AGENTS.md；人需要理解的 → docs/。
• 📌 從變更熱點切入是接手陌生專案最快的路徑。
• 📌 「待確認清單」是有價值的產出，不是失敗。它明確標示了知識缺口在哪。

12. Web Application Development

12.1 完整開發流程【建議】

flowchart TD
    REQ["Requirement<br/>業務需求"] --> SPEC["Specification<br/>規格釐清"]
    SPEC --> ARCH["Architecture<br/>技術方案"]
    ARCH --> PLAN["Implementation Plan<br/>Codex 產出、人審查"]
    PLAN --> BE["Backend 實作<br/>Entity → Repository → Service → Controller"]
    PLAN --> FE["Frontend 實作<br/>API Client → Store → Component → Page"]
    BE --> UT["Unit Test"]
    FE --> FT["Component Test"]
    UT --> IT["Integration Test"]
    FT --> IT
    IT --> BUILD["Build<br/>後端 package + 前端 build"]
    BUILD --> REV["Code Review<br/>codex review + 人工"]
    REV --> PR["Pull Request"]

    style SPEC fill:#7a3b12,color:#fff
    style PLAN fill:#3d2b5f,color:#fff
    style REV fill:#2d5016,color:#fff
    style PR fill:#2d5016,color:#fff

📌 關鍵設計【建議】：Specification 與 Architecture 兩個階段由人主導，Codex 只提供選項分析。從 Implementation Plan 開始才是 Codex 的主場。這條界線劃錯，後面全錯。

12.2 技術棧設定【建議】

以下以本手冊的參考技術棧為例。請依實際專案調整。

前端：Vue 3 + TypeScript + Tailwind CSS + PrimeVue + Pinia + Vue Router + vue-i18n 後端：Java 21 + Spring Boot + Maven + JUnit 5 + ArchUnit 資料庫：PostgreSQL（開發）/ Oracle、DB2、SQL Server（生產）

對應的 AGENTS.md 片段：

## 技術棧

| 層 | 技術 | 版本 |
| --- | --- | --- |
| 前端框架 | Vue | 3 |
| 語言 | TypeScript | 5 |
| 樣式 | Tailwind CSS | 3 |
| UI 元件 | PrimeVue | 4 |
| 狀態管理 | Pinia | 2 |
| 路由 | Vue Router | 4 |
| 國際化 | vue-i18n | 9 |
| 後端框架 | Spring Boot | 3.x |
| 語言 | Java | 21 |
| 建置 | Maven | 3.9 |
| 測試 | JUnit 5 + AssertJ + Mockito | — |
| 架構測試 | ArchUnit | — |
| 資料庫 | PostgreSQL（dev）/ Oracle（prod） | — |

## 指令

| 目的 | 指令 |
| --- | --- |
| 後端編譯 | `mvn -q -pl backend compile` |
| 後端測試 | `mvn -q -pl backend test` |
| 架構測試 | `mvn -q -pl backend test -Dtest=ArchitectureTest` |
| 前端型別檢查 | `pnpm --dir frontend type-check` |
| 前端測試 | `pnpm --dir frontend test` |
| 前端 lint | `pnpm --dir frontend lint` |
| 前端建置 | `pnpm --dir frontend build` |
| 全部驗證 | `./scripts/verify.sh` |

12.3 後端開發【建議】

完整的 Feature Prompt 範例

# Context
業務需要「訂單備註」功能：客服人員可以為訂單新增內部備註，
供後續處理參考。備註只有內部人員看得到，不會出現在客戶端。

# Objective
實作訂單備註的新增與查詢功能。

# Repository
- 模組：backend/order-service
- 參考既有的類似實作：OrderStatusHistory（相同的「附屬於訂單的紀錄」模式）
  路徑：backend/order-service/src/main/java/com/example/order/history/

# Architecture Rules
- 分層：Controller → Service → Repository，**禁止跨層**
- Entity 不得直接對外回傳，一律透過 DTO
- 使用 Java 21 record 定義 DTO
- 新增 endpoint 必須更新 docs/api/openapi.yaml

# Implementation Requirements
1. Entity：OrderNote（id, orderId, content, createdBy, createdAt）
   - content 上限 1000 字元
   - 使用 Flyway migration 建表，檔名遵循既有慣例
   - **只能新增 migration 檔，不可修改既有的**
2. Repository：Spring Data JPA，提供 findByOrderIdOrderByCreatedAtDesc
3. Service：OrderNoteService
   - addNote(orderId, content, operator)：訂單不存在時拋 OrderNotFoundException
   - listNotes(orderId)：回傳 DTO 清單
4. Controller：
   - POST /api/orders/{orderId}/notes
   - GET  /api/orders/{orderId}/notes

# Security Requirements
- 兩個 endpoint 都需要 ORDER_NOTE_MANAGE 權限（參考既有 @PreAuthorize 用法）
- content 需經 Bean Validation：@NotBlank @Size(max=1000)
- **備註內容可能包含客戶個資，日誌中不得輸出 content 全文**

# Testing Requirements
- OrderNoteServiceTest：新增成功、訂單不存在、內容超長、查詢排序正確
- OrderNoteControllerTest：權限不足回 403、驗證失敗回 400、成功回 201
- 命名：方法名_情境_預期結果
- 使用 JUnit 5 + AssertJ + Mockito

# Acceptance Criteria
1. 可為存在的訂單新增備註
2. 對不存在的訂單新增備註回傳 404
3. 內容超過 1000 字元回傳 400
4. 無權限回傳 403
5. 查詢結果依建立時間倒序
6. `mvn -q -pl backend/order-service test` 全綠
7. `mvn -q -pl backend test -Dtest=ArchitectureTest` 通過

# Validation
依序執行並貼出結果：
1. mvn -q -pl backend/order-service test
2. mvn -q -pl backend test -Dtest=ArchitectureTest

# Deliverables
程式碼 + 測試 + Flyway migration + OpenAPI 更新 + 變更說明

用 ArchUnit 讓架構規則可執行【建議】

這是本節最重要的技巧。 AGENTS.md 中的架構規則是「請求」，ArchUnit 測試是「強制」。

package com.example.arch;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.*;

@AnalyzeClasses(
    packages = "com.example",
    importOptions = ImportOption.DoNotIncludeTests.class
)
class ArchitectureTest {

    @ArchTest
    static final ArchRule controller_不可直接使用_repository =
        noClasses().that().resideInAPackage("..controller..")
            .should().dependOnClassesThat().resideInAPackage("..repository..")
            .because("Controller 必須透過 Service 存取資料");

    @ArchTest
    static final ArchRule service_不可依賴_controller =
        noClasses().that().resideInAPackage("..service..")
            .should().dependOnClassesThat().resideInAPackage("..controller..")
            .because("依賴方向必須由外向內");

    @ArchTest
    static final ArchRule entity_不可外洩到_controller =
        noClasses().that().resideInAPackage("..controller..")
            .should().dependOnClassesThat().resideInAPackage("..entity..")
            .because("Controller 只能使用 DTO");

    @ArchTest
    static final ArchRule 禁止使用_system_out =
        noClasses().should().accessClassesThat()
            .haveFullyQualifiedName("java.lang.System")
            .because("一律使用 SLF4J Logger");

    @ArchTest
    static final ArchRule service_必須以_Service_結尾 =
        classes().that().resideInAPackage("..service..")
            .and().areAnnotatedWith(org.springframework.stereotype.Service.class)
            .should().haveSimpleNameEndingWith("Service");

    @ArchTest
    static final ArchRule 不可有循環依賴 =
        com.tngtech.archunit.library.dependencies.SlicesRuleDefinition
            .slices().matching("com.example.(*)..")
            .should().beFreeOfCycles();
}

📌 為什麼這件事這麼重要【建議】：

有了 ArchUnit 測試後，「Controller 不可直接用 Repository」這條規則，從需要人在 review 時發現，變成 Agent 自己會在跑測試時發現並修正。

這就是第 4 章說的「提供高品質的 Observation」——你把架構規則變成了一個 Agent 可以自我驗證的驗證器。

12.4 前端開發【建議】

完整的 Feature Prompt 範例

# Context
後端已完成訂單備註 API（見 docs/api/openapi.yaml 的
/api/orders/{orderId}/notes）。現在要做前端。

# Objective
在訂單詳情頁新增「內部備註」區塊，支援檢視與新增備註。

# Repository
- 前端模組：frontend/src/
- 目標頁面：frontend/src/views/order/OrderDetailView.vue
- 參考既有的類似實作：frontend/src/components/order/OrderStatusHistory.vue
  （相同的「訂單附屬清單」模式，請遵循相同結構）

# Architecture Rules
- Vue 3 Composition API + `<script setup>`
- **禁止 `any`**；型別定義放在 frontend/src/types/
- API 呼叫封裝在 frontend/src/api/，不要在元件中直接呼叫 axios
- 跨元件狀態用 Pinia，本元件內部狀態用 ref/reactive
- 樣式一律用 Tailwind utility class

# Implementation Requirements
1. 型別：在 types/order.ts 新增 OrderNote 介面
2. API client：api/orderNote.ts，提供 listNotes / addNote
3. Pinia store：stores/orderNote.ts，管理載入狀態與錯誤
4. 元件：components/order/OrderNoteSection.vue
   - 顯示備註清單（時間倒序、顯示建立者與時間）
   - 新增備註表單（textarea + 送出按鈕）
   - 字數即時顯示（上限 1000）
5. 整合進 OrderDetailView.vue

# UI Requirements
- 使用 PrimeVue 元件：Textarea、Button、Message
- **RWD**：手機（<640px）單欄，桌機雙欄
- 載入中顯示 skeleton，不要用轉圈圈
- 送出中禁用按鈕，避免重複送出
- 錯誤以 PrimeVue Message 顯示，不要用 alert

# i18n Requirements
- **所有使用者可見文字必須走 i18n**，不可硬編碼中文
- 在 locales/zh-TW.json 與 locales/en.json 同步新增鍵值
- 鍵值命名遵循既有慣例：order.note.*

# Testing Requirements
- 元件測試（Vitest + @vue/test-utils）：
  - 正確渲染備註清單
  - 空清單顯示空狀態
  - 超過 1000 字元時按鈕禁用
  - 送出成功後清空輸入框並重新載入

# Acceptance Criteria
1. 訂單詳情頁可看到備註清單（時間倒序）
2. 可新增備註，成功後清單即時更新
3. 超過 1000 字元無法送出
4. 無權限時區塊不顯示
5. 手機與桌機版面皆正常
6. 沒有硬編碼的使用者可見文字
7. `pnpm --dir frontend type-check` 通過
8. `pnpm --dir frontend lint` 通過
9. `pnpm --dir frontend test` 全綠

# Validation
依序執行並貼出結果：
1. pnpm --dir frontend type-check
2. pnpm --dir frontend lint
3. pnpm --dir frontend test

📌 前端 prompt 的三個關鍵【建議】：

1. 指出參考實作——「照著 OrderStatusHistory.vue 的模式做」比描述十條規則有效。
2. 明確要求 i18n——這是 Agent 最常漏的一項，因為硬編碼中文「看起來也能動」。
3. 把 type-check / lint / test 都寫進驗證——三個驗證器比一個好。

12.5 資料庫【建議】

跨資料庫的注意事項

專案若需同時支援 PostgreSQL、Oracle、DB2、SQL Server，必須在 AGENTS.md 明確約束：

## 資料庫規則

本專案需同時支援 PostgreSQL（開發）、Oracle、DB2、SQL Server（生產）。

### 必須遵守
1. **一律使用 JPA / Spring Data 的標準功能**，避免資料庫專屬語法
2. 需要原生 SQL 時，必須確認四種資料庫都支援；不支援時提供各自的實作
3. **禁止**使用以下資料庫專屬語法：
   - PostgreSQL：`ILIKE`、`::` 轉型、`RETURNING`、陣列型別、`JSONB`
   - Oracle：`ROWNUM`、`CONNECT BY`、`DECODE`、`NVL`（改用 `COALESCE`）
   - SQL Server：`TOP`、`ISNULL`、`GETDATE()`（改用 `CURRENT_TIMESTAMP`）
   - DB2：`FETCH FIRST n ROWS ONLY` 以外的專屬分頁語法
4. 分頁一律使用 Spring Data 的 `Pageable`，不要手寫 LIMIT/OFFSET
5. 識別碼長度：**上限 30 字元**（Oracle 11g 限制）
6. **禁止使用保留字**作為表名或欄位名（如 `user`、`order`、`group`、`size`）
   - 訂單表命名為 `orders` 而非 `order`
7. 字串比較的大小寫敏感性因資料庫而異，**不要依賴預設行為**

### Migration
- 使用 Flyway，檔名 `V{版本}__{說明}.sql`
- **已套用的 migration 一律不可修改**，只能新增
- 每個 migration 必須可重複執行或明確標示不可重入
- DDL 與 DML 分開成不同 migration 檔

SQL 相關的 Prompt 技巧【建議】

# Objective
優化訂單查詢的效能。目前查詢 3 個月資料需要 8 秒。

# ⚠️ 方法論要求
**先量測，再優化。**

執行順序：
1. 找出實際執行的 SQL（開啟 Hibernate SQL log 或看 Mapper XML）
2. 對每個候選 SQL 執行 EXPLAIN，貼出執行計畫
3. 指出瓶頸（全表掃描？缺索引？N+1？）並提出證據
4. 提出優化方案與預期效果
5. **等我確認後**才實作
6. 實作後重新量測並比較

# Constraints
- **禁止**在未量測的情況下直接加索引
- 加索引必須說明：索引欄位順序的理由、對寫入效能的影響、索引大小估算
- 不要用快取掩蓋查詢問題
- 修改後所有既有測試必須通過

# Acceptance Criteria
1. 3 個月資料查詢時間 < 1 秒
2. 有 EXPLAIN 的前後對照
3. 既有測試全綠

⚠️ N+1 查詢是 Agent 最常產生的效能問題。在 AGENTS.md 中明確要求：「涉及關聯查詢時，必須說明是否會產生 N+1，並使用 @EntityGraph 或 JOIN FETCH 避免。」

12.6 端到端範例：從需求到 PR【建議】

需求：客服人員需要能為訂單加註記。

每一步的 Codex 呼叫方式：

# 步驟 3：先出計畫
codex --profile dev
> /plan
> <貼上需求規格與技術方案>

# 步驟 4-5：後端（一次一個關注點）
> 執行計畫的第 1-2 步：建立 Flyway migration 與 Entity。完成後執行 mvn -q compile。
> 執行第 3-4 步：Repository 與 Service。完成後執行 mvn -q -pl backend/order-service test。
> 執行第 5 步：Controller 與其測試。

# 步驟 6：驗證
> 執行 mvn -q -pl backend test -Dtest=ArchitectureTest

# 步驟 7-8：前端
> 執行計畫的第 6-8 步：前端實作。完成後依序執行 type-check、lint、test。

# 步驟 10：機械 review
codex review

📌 注意每一步都很小，且每一步都有驗證。 這不是為了「流程完整」，而是因為小步 + 驗證 = 可審查的 diff + 可自我修正的 Agent。

12.7 本章實務案例【建議】

情境：團隊導入 Codex 開發 Web 功能三個月後的成效統計（12 個功能）。

最值得注意的是最後一列：需求理解錯誤變多了。

根因分析：因為開發速度變快，工程師傾向「先讓 Codex 做做看」而跳過與業務確認需求的步驟。Codex 會很快產出一個「看起來完整」的功能，讓人誤以為需求已經清楚。

改善措施：

1. 在流程中強制加入「需求釐清簽核」關卡——未簽核不得進入實作。

2. AGENTS.md 加入規則：

   ## 需求不明時的處理
   
   若你在實作過程中遇到需求不明確之處（例如：邊界條件未定義、
   權限規則不清楚、錯誤情境未說明），**停下來列出問題，不要自行假設**。
   
   寧可交出一個「有 3 個待確認問題」的部分成果，
   也不要交出一個「基於錯誤假設」的完整成果。

3. Prompt 範本中加入固定的最後一段：

   # Deliverables
   ...
   4. **你在實作中做出的所有假設清單**（即使你認為很明顯）

三個月後複測：需求理解錯誤數降至 0.2，低於導入前水準。

📌 這個案例的核心教訓【建議】：Agent 讓「做」變快了，但沒有讓「想清楚」變快。 當執行成本下降時，思考不足的問題會被放大而非縮小。企業導入時必須有意識地強化上游的需求釐清環節，否則會出現「更快地做出錯的東西」。

12.8 本章注意事項

• ⚠️ 需求釐清與技術方案由人主導。Codex 提供選項分析，但決策是人的責任。
• ⚠️ 執行變快會放大需求不清的問題。要有意識地強化上游把關。
• ⚠️ i18n 是 Agent 最常漏的一項，因為硬編碼看起來也能動。務必列入驗收標準。
• ⚠️ 跨資料庫專案要明確禁止專屬語法，否則 Agent 會用開發環境（通常是 PostgreSQL）的寫法。
• ⚠️ N+1 查詢是常見產出。在 AGENTS.md 中明確要求說明關聯查詢策略。
• ⚠️ Flyway migration 只能新增不能改。這條要寫進 AGENTS.md，Agent 不會自己知道。
• 📌 ArchUnit 是把架構規則變成驗證器的最佳工具。投資一次，長期受益。
• 📌 「參考既有的 XXX 實作」比列十條規則有效。指出範本檔案。
• 📌 type-check + lint + test 三個驗證器都要跑。前端尤其如此。
• 📌 要求 Agent 列出「它做的假設」。這是發現需求誤解最有效的一招。

13. Reverse Engineering

本章是企業導入 Codex CLI 最有價值的應用場景。多數企業的痛點不是「寫新程式碼太慢」，而是「沒人看得懂舊系統」。

13.1 逆向工程的目標【建議】

目標不是「讀懂每一行程式碼」，而是「建立足以做出決策的理解」。

具體要回答的問題：

13.2 逆向工程 Workflow【建議】

flowchart TD
    REPO["Legacy Repository"] --> INV["① Inventory<br/>盤點：有什麼"]
    INV --> DEP["② Dependency Analysis<br/>依賴：靠什麼"]
    DEP --> ARCH["③ Architecture Discovery<br/>架構：怎麼組織"]
    ARCH --> BIZ["④ Business Flow Discovery<br/>業務：在做什麼"]
    BIZ --> DATA["⑤ Data Flow<br/>資料：從哪到哪"]
    DATA --> API["⑥ API Flow<br/>介面：對外對內"]
    API --> RISK["⑦ Risk Analysis<br/>風險：哪裡危險"]
    RISK --> DOC["⑧ Documentation<br/>文件：沉澱知識"]
    DOC --> PLAN["⑨ Modernization Plan<br/>計畫：接下來做什麼"]

    INV -.->|"唯讀"| RO["整個流程<br/>全程 read-only"]
    HV["⚠️ ④⑤ 必須人工驗證<br/>Agent 在業務規則上最容易出錯"]
    BIZ -.-> HV
    DATA -.-> HV

    style REPO fill:#4a2020,color:#fff
    style RO fill:#1e3a5f,color:#fff
    style HV fill:#7a3b12,color:#fff
    style PLAN fill:#2d5016,color:#fff

全程使用：

codex --profile explore   # read-only + untrusted

或明確指定：

codex -s read-only -a untrusted -c web_search=disabled

⚠️ 為什麼要 web_search=disabled【建議】：分析不受信任的 Legacy 程式碼時，程式碼中的註解或字串可能包含惡意指令（prompt injection）。關閉網頁搜尋可切斷「Agent 被誘導去抓取外部內容」的路徑。

13.3 階段 ①：Inventory（盤點）【建議】

# Objective
盤點本 Repository 的全部內容，建立技術資產清單。

# ⚠️ 嚴格限制
唯讀。不修改任何檔案。不執行任何會產生外部連線的指令。

# 請產出以下清單

## 1. 檔案類型統計
依副檔名統計檔案數量與總行數，至少涵蓋：
.java .jsp .js .ts .html .css .xml .properties .sql .sh .bat .cmd
.jar .war .ear .yaml .yml .json .txt .md

## 2. 技術棧識別
從建置檔、設定檔、import 語句判斷：
- 語言與版本（從 pom.xml / build.gradle / web.xml 判斷）
- Web 框架（Struts? Spring MVC? 原生 Servlet? JSF?）
- 持久層（JDBC? Hibernate? MyBatis? iBATIS?）
- 前端（jQuery? 原生 JS? 有無打包工具？）
- 應用伺服器（WebSphere? WebLogic? Tomcat? JBoss?）
- 建置工具（Maven? Ant? Gradle? 手工 script?）

## 3. 進入點清單
- HTTP 進入點（Servlet mapping、Struts action、Spring Controller）
- 排程任務（Quartz、Timer、cron 呼叫的腳本）
- 訊息消費者（JMS、MQ listener）
- 批次程式（main 方法、shell script）
- 檔案接口（FTP/SFTP 收送、目錄輪詢）

## 4. 外部整合清單
- 資料庫連線（從設定檔找出所有 datasource）
- 外部 API 呼叫（HTTP client、SOAP client 的呼叫目標）
- 訊息佇列（queue / topic 名稱）
- 檔案傳輸（FTP / SFTP 主機與路徑）
- 其他（郵件、簡訊、列印⋯⋯）

## 5. 設定檔清單
每個設定檔的路徑 + 它控制什麼

## 6. 疑似死程式碼
- 沒有被任何地方引用的類別
- 被註解掉的大段程式碼
- 名稱含 old / bak / test / tmp / 日期 的檔案

# 輸出要求
- Markdown 表格為主
- **每一項都要附檔案路徑**
- 無法確定的標註「待確認」，不要猜
- 最後列出「待確認清單」

# 輸出到
docs/reverse/01-inventory.md

這一階段的產出，是後續所有工作的地圖。

13.4 階段 ②：Dependency Analysis（依賴分析）【建議】

# Objective
分析本系統的依賴關係。

# ⚠️ 唯讀

# 1. 外部依賴（第三方套件）
從 pom.xml / build.gradle / lib 目錄 / WEB-INF/lib 列出：
| 套件 | 版本 | 用途 | 最後發布年份（若你知道） | 風險 |

風險判定：
- 🔴 已知有嚴重 CVE、已停止維護、版本超過 8 年
- 🟡 版本超過 4 年、有較新的主要版本
- 🟢 相對新近

⚠️ 若你不確定某個套件的 CVE 狀態，標註「需查證」，不要編造。

# 2. 內部依賴（模組/套件之間）
- 產出 Mermaid 依賴圖
- 標出循環依賴
- 標出「被最多地方依賴」的前 10 個類別（這些是核心）

# 3. 依賴倒置檢查
有沒有低層模組依賴高層模組的情況？

# 4. 隱性依賴
- 靠字串反射載入的類別（Class.forName）
- 靠設定檔指定的實作類別
- 靠檔案系統路徑約定的依賴
- 靠資料庫中的設定值決定行為的地方
⚠️ 這一項最重要 — 這些依賴在靜態分析中看不出來，
   但升版或重構時會炸掉。

# 輸出到
docs/reverse/02-dependencies.md

📌 第 4 項「隱性依賴」是逆向工程的關鍵【建議】。Legacy 系統最大的地雷不是看得見的依賴，而是 Class.forName(config.get("handler.class")) 這種——編譯器不會抱怨，靜態分析工具找不到，但你一改就掛。

13.5 階段 ③：Architecture Discovery（架構發現）【建議】

# Objective
還原本系統的實際架構（不是「應該的」架構，是「實際的」架構）。

# ⚠️ 唯讀

# 請分析
## 1. 實際分層
從程式碼觀察實際的分層結構。
⚠️ 不要照抄教科書的分層名稱。如果實際上是
「JSP 直接寫 SQL」，就照實寫。

## 2. 每一層的職責與典型類別
| 層 | 職責 | 典型類別（附路徑） | 檔案數 |

## 3. 分層違規
列出違反自身分層原則的地方（附路徑與說明）

## 4. 設計模式使用
實際用到哪些模式？用得對不對？

## 5. 橫切關注點的實作方式
- 交易管理在哪一層？用什麼機制？
- 認證授權怎麼做？
- 錯誤處理有沒有統一機制？
- 日誌怎麼記？
- 有沒有 AOP / Filter / Interceptor？

## 6. 「上帝類別」
列出超過 1000 行的類別，以及它們各自在做幾件事

# 輸出
- Mermaid 架構圖
- 表格
- **明確區分「事實」與「推測」**

# 輸出到
docs/reverse/03-architecture.md

13.6 階段 ④：Business Flow Discovery（業務流程還原）【建議】

⚠️ 這是整個逆向工程中 Agent 最容易出錯、也最需要人工驗證的階段。

# Objective
還原以下業務流程的實際實作：
1. <流程 1>
2. <流程 2>
3. <流程 3>

# ⚠️ 唯讀

# 對每一條流程，請追蹤
1. 進入點（HTTP path / 排程時間 / 訊息名稱）
2. 完整的呼叫鏈（每一層的類別.方法 + 檔案路徑:行號）
3. 每一步做了什麼判斷、什麼轉換
4. 所有的分支條件（if/else、switch）與各分支的意義
5. 存取了哪些資料表，做了什麼操作
6. 呼叫了哪些外部系統
7. 錯誤時會發生什麼
8. 交易邊界在哪裡

# ⚠️ 最重要的輸出要求
請把每一條業務規則分成兩類明確標示：

**【程式碼事實】** — 你在程式碼中直接看到的
  格式：規則描述（來源：檔案路徑:行號）

**【推測】** — 你根據命名、註解、或常理推斷的
  格式：規則描述（推測依據：⋯⋯）

⚠️ 不要把推測寫成事實。若某個判斷條件你看得懂語法但
不理解業務意義，請寫「此處有一個判斷 X，但無法從程式碼
判斷其業務意義」，**不要編造合理的解釋**。

# 輸出
每條流程：
- 一張 Mermaid sequence diagram
- 一張 Mermaid flowchart（決策分支）
- 【程式碼事實】清單
- 【推測】清單
- 【待業務確認】清單

# 輸出到
docs/reverse/04-business-flow-<流程名>.md

人工驗證的做法【建議】：

flowchart LR
    A["Agent 產出<br/>【事實】+【推測】+【待確認】"] --> B["工程師驗證【事實】<br/>抽查 20%，對照原始碼"]
    B --> C["業務人員驗證【推測】<br/>逐條確認"]
    C --> D{"推測正確？"}
    D -->|"是"| E["升級為【已確認事實】"]
    D -->|"否"| F["標記為【錯誤理解】<br/>記錄正確版本"]
    F --> G["寫進 AGENTS.md<br/>避免下次再錯"]
    E --> H["正式業務流程文件"]
    G --> H

    style A fill:#1e3a5f,color:#fff
    style C fill:#7a3b12,color:#fff
    style H fill:#2d5016,color:#fff

13.7 各技術類型的專用 Prompt【建議】

JSP / Servlet

# Objective
分析 JSP 與 Servlet 層的實作。

# ⚠️ 唯讀

# 請分析
1. web.xml 中的所有 servlet mapping、filter、listener（附設定內容）
2. JSP 檔案清單，每個的用途
3. **JSP 中是否有業務邏輯或直接 SQL**（scriptlet `<% %>`）
   ⚠️ 這是最重要的一題。列出所有含 scriptlet 的 JSP 與其內容摘要
4. JSP 之間的 include / forward 關係（畫成 Mermaid 圖）
5. 使用的 taglib 與自訂 tag
6. 前端與後端的資料傳遞方式（request attribute? session? hidden field?）
7. **session 中放了哪些東西**（這常是狀態管理的地雷）
8. XSS 風險：有沒有未經 escape 直接輸出的地方

# 輸出到 docs/reverse/jsp-servlet.md

Struts

# Objective
分析 Struts 設定與 Action 實作。

# ⚠️ 唯讀

# 請分析
1. struts-config.xml / struts.xml 的完整 action mapping
   | path | Action 類別 | form bean | forward 目標 | validate |
2. ActionForm 清單與各自的欄位
3. Action 類別的實際職責（有沒有塞了業務邏輯）
4. validation.xml 的驗證規則
5. tiles / 版面配置的使用方式
6. **Struts 版本**（Struts 1 vs Struts 2 差異極大）
7. 已知的 Struts 安全風險是否適用於本專案
   ⚠️ 若不確定 CVE 細節請標註「需查證」

# 輸出到 docs/reverse/struts.md

SQL / Stored Procedure

# Objective
分析資料存取層與資料庫物件。

# ⚠️ 唯讀。不要連線到任何資料庫。

# 請分析
1. SQL 出現在哪些地方（Java 字串? XML? Stored Procedure? JSP?）
2. 所有存取到的資料表清單，每個表的用途（從欄位與使用方式推斷）
3. **SQL 注入風險**：找出所有字串拼接產生的 SQL（附路徑:行號）
4. Stored Procedure / Function 清單與各自的職責
5. **業務邏輯有多少寫在資料庫裡**（這決定了遷移難度）
6. 交易管理：commit / rollback 在哪裡控制
7. 效能疑慮：
   - 沒有 WHERE 的查詢
   - SELECT *
   - 迴圈中執行 SQL（N+1）
   - 明顯缺索引的查詢條件
8. 資料庫專屬語法的使用（會影響未來換 DB 的可能性）

# 輸出到 docs/reverse/data-access.md

Shell Script / Batch

# Objective
分析排程與批次作業。

# ⚠️ 唯讀

# 請分析
1. 所有 .sh / .bat / .cmd 檔案清單與用途
2. 每個腳本：觸發方式（cron? 排程器? 手動?）、執行內容、輸出去向
3. 腳本之間的呼叫關係（Mermaid 圖）
4. **腳本中的硬編碼**：路徑、主機名、帳號密碼、環境變數
   ⚠️ 若發現疑似憑證，只標註位置，**不要在輸出中重複憑證內容**
5. 錯誤處理：有沒有 set -e？失敗會怎樣？有沒有告警？
6. 對外部環境的假設（特定目錄存在、特定工具已安裝、特定使用者身分）
7. 冪等性：重跑會怎樣？

# 輸出到 docs/reverse/batch.md

FTP / SFTP / MQ 整合

# Objective
分析系統的外部整合介面。

# ⚠️ 唯讀

# 檔案傳輸（FTP / SFTP）
1. 所有傳輸點：對象主機、目錄、檔名格式、傳輸方向
2. 觸發時機
3. 檔案格式（定長? CSV? XML? 自訂?）與欄位定義
4. 傳輸失敗的處理
5. 檔案處理完後怎麼辦（刪除? 搬移? 保留?）
6. ⚠️ 憑證管理方式（只說明機制，不要輸出憑證內容）

# 訊息佇列（MQ / JMS）
1. 所有 queue / topic 名稱與用途
2. 生產者與消費者分別在哪裡
3. 訊息格式與 schema
4. 錯誤處理：重試? DLQ? 有沒有可能訊息遺失?
5. 順序性要求
6. 冪等性處理

# SOAP / REST
1. 對外提供的介面清單
2. 對外呼叫的介面清單
3. WSDL / schema 位置
4. 逾時與重試設定

# 輸出到 docs/reverse/integration.md

13.8 階段 ⑦：Risk Analysis（風險分析）【建議】

# Objective
基於前面所有分析，產出風險清單。

# ⚠️ 唯讀

# 風險分類
## 1. 安全風險
- SQL 注入、XSS、路徑穿越、不安全的反序列化
- 硬編碼憑證（標註位置，不輸出內容）
- 缺少認證/授權的入口
- 已知有 CVE 的依賴（不確定就標「需查證」）
- 不安全的加密（MD5 存密碼、DES、硬編碼 IV）

## 2. 可維護性風險
- 超過 1000 行的類別
- 圈複雜度極高的方法
- 完全沒有測試的核心模組
- 大量重複程式碼

## 3. 技術過時風險
- 已停止支援的框架版本
- 已停止支援的執行環境
- 無法在現代作業系統/JDK 上運作的依賴

## 4. 營運風險
- 單點故障
- 沒有錯誤告警的批次作業
- 硬編碼的環境相關設定
- 沒有冪等性的重要操作

## 5. 知識風險
- 只有一個人懂的模組（從 git log 判斷）
- 完全沒有註解的複雜邏輯
- 命名與實際行為不符的地方

# 輸出格式
| ID | 分類 | 風險描述 | 位置 | 嚴重度 | 可能後果 | 建議處置 |

嚴重度：Critical / High / Medium / Low
⚠️ 嚴重度判定要有依據，不要全部標 High

# 輸出到 docs/reverse/07-risks.md

13.9 階段 ⑨：Modernization Plan（現代化計畫）【建議】

# Objective
基於前面的分析與風險清單，提出現代化建議。

# ⚠️ 唯讀。這是「建議」不是「決策」，最終由架構師決定。

# 請提出
## 1. 現況總評
- 系統健康度評分與依據
- 最大的三個問題

## 2. 可能的路徑（至少三個選項）
對每個選項說明：
| 選項 | 做法 | 預估工作量 | 風險 | 適合的情境 |
例如：
- 原地維護（只做安全性修補）
- 漸進式現代化（Strangler Fig）
- 重寫

## 3. 若採漸進式現代化，建議的階段
每個階段：範圍、前置條件、驗證方式、預估工作量、風險

## 4. 第一步該做什麼
⚠️ 請具體到「第一週該做哪些事」

## 5. 前置條件
在動任何程式碼之前必須先具備什麼
（例如：測試安全網、CI、可重現的環境）

# 輸出到 docs/reverse/09-modernization-plan.md

13.10 逆向工程的品質控管【建議】

Agent 的分析看起來永遠很專業。這是最危險的地方。