---
title: "寫好 Codex 提示詞"
description: "Prompt 描述你希望 Codex 做什麼，好的提示詞會寫清目標、上下文、邊界和驗證方式。"
verifiedAt: "2026-05-07"
---

你透過 prompts 和 Codex 互動。Prompt 描述你希望它做什麼，Codex 隨後進入迴圈：呼叫模型、讀取檔案、編輯檔案、執行命令和呼叫工具，直到任務完成或被取消。

> [!IMPORTANT]
> 好的 Codex prompt 不只是“請幫我做”。它要寫清目標、上下文、範圍、禁止事項、驗證方式和交付格式。

<Cards>
  <Card title="Prompting" href="https://developers.openai.com/codex/prompting">
    官方 Codex prompting 基礎。
  </Card>
  <Card title="From theory to practice" href="/zh-Hant/docs/codex/understanding/from-theory-to-practice">
    把模糊需求改寫成可執行任務。
  </Card>
  <Card title="How a task completes" href="/zh-Hant/docs/codex/understanding/how-a-task-completes">
    理解 Codex 從 prompt 到驗證的迴圈。
  </Card>
</Cards>

## 兩個簡單例子

解釋程式碼：

```text
请解释 transform module 是如何工作的，以及其他模块如何使用它。
```

新增功能：

```text
请添加一个新的命令行选项 `--json`，用于输出 JSON。
```

這兩個 prompt 能跑，但真實專案裡還不夠。要穩定交付，需要補上下文、範圍和驗證。

## 好 prompt 的結構

```mermaid
flowchart LR
    Goal["目標"] --> Context["上下文"]
    Context --> Scope["範圍"]
    Scope --> Boundaries["禁止事項"]
    Boundaries --> Verify["驗證"]
    Verify --> Deliver["交付"]
```

建議包含：

- 目標：使用者層面的結果是什麼。
- 上下文：相關檔案、錯誤日誌、截圖、連結、業務規則。
- 範圍：只允許動哪些檔案或目錄。
- 禁止事項：不新增依賴、不改資料庫、不動無關檔案等。
- 驗證：跑什麼測試、lint、build、截圖或人工檢查。
- 交付：最後彙報改動檔案、驗證結果、未驗證項和風險。

## Outcome-first 寫法

GPT-5.5 的官方提示詞指導強調 outcome-first：先定義結果、成功標準、約束和可用上下文，讓模型選擇具體路徑。對 Codex 來說，這比寫一長串“先做 A、再做 B、再做 C”更穩，除非每一步都是業務硬約束。

可以用這個模板：

```text
目标：
修复用户在移动端打开设置页时按钮错位的问题。

上下文：
- 复现路径：打开 /settings，宽度 390px，点击 Profile tab。
- 相关文件优先看 src/app/settings 和 src/components/tabs。

范围：
- 只改布局和样式相关文件。
- 不改接口、不改数据结构、不新增依赖。

验证：
- 跑现有 lint/build。
- 用浏览器检查 390px、768px、1440px 三个宽度。
- 最后说明改动文件、验证结果和残余风险。
```

這個 prompt 沒規定 Codex 必須先讀哪個檔案、後改哪個元件，但把目標和驗收寫清楚了。Codex 可以按實際程式碼結構選擇路徑。

## 停止條件和缺證據行為

長任務尤其要寫 stopping conditions。否則 Codex 可能一直擴大搜尋範圍或改到無關檔案。

建議直接寫：

- 如果沒有復現到問題，先停下並報告已檢查路徑，不要猜改。
- 如果需要新增依賴，先說明原因和替代方案。
- 如果測試失敗且與本次改動無關，記錄失敗命令和證據，不要順手大改。
- 如果超過約定範圍，先輸出計劃，等確認後再繼續。

缺證據時也要明確：

```text
如果官方文档、源码和现象不一致，以本仓库当前源码和可复现行为为准；无法确认时标注为推断，不要写成确定结论。
```

## 複雜任務先拆

Codex 處理複雜工作時，拆成更小、更聚焦的步驟更穩。小任務更容易測試，也更容易 review。

如果不知道怎麼拆，先讓 Codex 只做計劃：

```text
请先不要改文件。基于当前问题提出最小实现计划，列出需要读取的文件、可能风险和验证方式。
```

確認計劃後，再讓它執行第一步。

## Prompt 裡應該少寫什麼

很多舊 prompt 會堆滿絕對規則，例如 ALWAYS、NEVER、must、only。官方提示詞指導建議把這些詞留給真正的不變數，例如安全邊界、必填欄位、絕對禁止的動作。

判斷類任務更適合寫 decision rules：

| 不推薦 | 推薦 |
| --- | --- |
| “永遠不要聯網。” | “只有當本地資料不足或需要最新事即時聯網，並引用來源。” |
| “必須先讀所有檔案。” | “先讀入口檔案和呼叫鏈，發現範圍不足再擴充套件。” |
| “一定要完整重構。” | “優先最小改動；只有現有結構無法滿足目標時再提出重構計劃。” |

對 Codex 來說，過多絕對規則會讓它在衝突指令裡浪費推理，甚至錯過更簡單的驗證路徑。

## Thread 和上下文

Thread 是一個單獨 session：包含你的 prompt，以及隨後產生的模型輸出和 tool calls。

一個 thread 可以包含多個 prompts。比如第一個 prompt 實現功能，後續 prompt 新增測試。

可以同時執行多個 threads，但避免讓兩個 threads 修改同一批檔案。併發任務要用 worktree 或明確檔案邊界。

提交 prompt 時，包含 Codex 可以使用的 context，例如相關檔案和圖片引用。IDE extension 會自動包含 open files 和 selected text range。

長任務會受 context window 限制。Codex 可能自動 compact：總結相關資訊，丟棄不太相關的細節。關鍵約束、檔案路徑和驗證方式應寫在清楚位置，不要只藏在很早的對話裡。

## 常見坑

- 任務太寬：讓 Codex “最佳化專案”。
- 沒寫驗證：最後只能憑感覺判斷。
- 沒寫禁止事項：分析任務變成修改任務。
- 沒給復現路徑：Codex 只能猜 bug。
- 多個 threads 同時改同一批檔案。
- 把敏感 token、cookie、私鑰貼進 prompt。

## 驗收清單

- Codex 知道目標和允許範圍。
- Codex 知道不能做什麼。
- Codex 知道先讀哪些檔案或證據。
- Codex 知道完成後怎麼驗證。
- 最終輸出能說明 diff、驗證結果、未驗證項和剩餘風險。
- 長任務寫明停止條件和缺證據處理方式。
- 輸出長度、格式、表格或 JSON 要求寫成可檢查標準。

## 官方資料

- [Prompting](https://developers.openai.com/codex/prompting)
- [Workflows](https://developers.openai.com/codex/workflows)
- [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
- [GPT-5.5 Prompt guidance](https://developers.openai.com/api/docs/guides/prompt-guidance)

## 接下來去哪

<Cards>
  <Card title="選擇模型" href="/zh-Hant/docs/codex/official/04-model-pricing/14-model-selection" description="提示詞寫好之後再考慮換更強模型" />
  <Card title="理解價格和用量" href="/zh-Hant/docs/codex/official/04-model-pricing/15-pricing-usage" description="提示詞大小直接影響 token 與 credits 消耗" />
  <Card title="實踐建議" href="/zh-Hant/docs/codex/official/04-model-pricing/63-best-practices" description="把好提示詞沉澱成 AGENTS.md 與 skill" />
  <Card title="基礎配置" href="/zh-Hant/docs/codex/official/02-config-security/06-basic-config" description="config.toml 是長期偏好的家" />
  <Card title="批准與安全模式" href="/zh-Hant/docs/codex/official/02-config-security/07-approval-security" description="提示詞搭配 approval 才能落地受控自動化" />
</Cards>
