05 - 實戰提示詞與上手流程

← 04-權限與安全設定 | 00-Index | 下一篇 → 06-進階功能-Skills-Automations-多代理

初學者最需要的不是華麗 prompt

官方在 Working with Codex 很明確地說：你不需要完美 prompt，也不需要很技術化的指令。

真正有用的是把這 3 件事講清楚：

你要做什麼
可以用哪些檔案 / 範圍
done 長什麼樣

一個通用 prompt 模板

你可以直接套這個：

請先檢查 [資料夾 / 專案 / 檔案]，告訴我你看到的重點。
接著提出一個安全、範圍小、可在這次完成的方案。
如果需要修改檔案，請先告訴我你預計會改哪些檔案，以及完成後我會得到什麼。

如果你已經準備好要讓它直接做，可以改成：

請在這個 project 內完成以下任務：
1. ...
2. ...
3. 完成後回報你改了哪些檔案、做了哪些驗證、還有哪些風險或待確認事項。

5 種很適合新手的任務

1. 看懂資料夾

請先閱讀這個資料夾的結構與主要檔案，告訴我它大概是做什麼的。
接著列出 3 個我可以安全開始的小任務。

2. 整理文件

請把這些 Markdown 筆記整理成一份條理更清楚的索引頁。
不要刪原文，只新增整理檔。

3. 找 bug

請根據這段錯誤訊息找出可能原因。
如果你認為可以安全修正，請實作並說明改了什麼。

4. 補測試

請先閱讀這個模組與現有測試。
找出一個合理但缺漏的測試情境並補上。

5. 做固定格式輸出

請閱讀這個資料夾中的內容，整理成一份一頁式摘要。
格式要包含：背景、現況、問題、下一步。

prompt 的實用原則

說輸出格式

比起只說「整理一下」，更好的是說：

產出一份 Markdown
用條列式
控制在 1 頁
最後列出引用來源
回答用繁體中文，專有名詞保留英文

說限制條件

例如：

不要改原始檔
只新增新檔
不要碰 production 設定
修改前先告知
若不確定先停下來問

說驗證方式

例如：

做完後告訴我你怎麼檢查
若有測試請跑測試
若沒法驗證請直接說

明確指定 done 條件（最被低估的一招）

agent 失控最常見的原因不是它笨，而是你沒講清楚「做到什麼程度算完成」。沒有 done 條件，它會自己猜——可能少做，也可能過度發揮（over-engineering）。

把 done 寫成可被檢查的條件清單，越具體越好：

❌ 模糊：「幫我把筆記整理好」
✅ 可驗：「done = 每篇都有合法 YAML frontmatter、有 prev/next 導覽、新增的引用都附 PMID；完成後列出你改了哪幾檔」

實用句型：

完成條件（done）：
1. <可檢查的結果 1>
2. <可檢查的結果 2>
3. 不要做的事：<明確排除，例如：不要動其他資料夾、不要 commit>
完成後請回報：改了哪些檔、做了哪些驗證、還有哪些不確定要我裁定。

幾個讓 done 更穩的細節：

正面條件 + 負面邊界一起給：「要做 A、B」和「不要碰 C、不要 D」同樣重要。
把驗證指令寫進 done：例如「跑 npm run validate 要綠燈才算完成」，agent 就會自己驗到過為止。
要求結尾自我回報：改了哪些檔、怎麼驗的、哪裡不確定——這份回報就是你 review 的起點。
歧義先問、不要猜：「若有多種合理解讀，先列選項問我，不要直接挑一個做」。

Review 與收斂：agent 產出後你要做什麼

放出去的任務回來後，review 才是品質的真正關卡，尤其是內容正確性（程式可以靠測試，但「事實對不對」測試管不到）。

收斂的固定動作：

先看自我回報：對照你下的 done 條件逐項核。它說做了的，抽查是真的做了。
抽驗高風險的點：引用、數字、外部事實、會連動的改動。平行產出越多，越要有中央驗證——這是 07-實戰工作流範例的核心安全設計。
diff 一定要看：別只看結論，看它實際改了什麼。git diff 是你的好朋友。
連動項自己補：跨檔的一致性（反向連結、index、changelog）容易被單一 agent 漏掉，由你或協調者最後統一收。
錯了給具體回饋再續跑：「第 3 點的引用查不到，請改成原則性描述或標需查證」比「重做」有效率。

心法：agent 負責產出、你負責驗證與收斂。產出可以平行、可以放手；驗證這一關不能外包給同一批正在產出的 agent。

一個穩定的上手流程

可以照這個節奏：

先讓 Codex inspect
讓它提小方案
你確認
它執行
它回報修改與驗證
你 review
再逐步放大任務

這比一開始就丟一個超大需求，成功率高很多。

重點整理

好 prompt 的重點不是 fancy，而是清楚。
目標、範圍、done、限制、驗證，這 5 個元素最實用。
新手最穩的流程是 inspect → propose → approve → execute → review。
你越清楚交代輸出格式，Codex 越容易穩定交付。

參考資料