OpenAI Codex · Best Practices

AI Agent 最佳實踐
新手互動教學

從零開始，掌握 AI Agent 核心工作方法

8 個章節
每章含互動測驗
完成即可查看成績
🤖
Chapter 01
什麼是 AI Agent？

AI Agent（AI 代理人）是一種可以自動執行多步驟任務的 AI 程式。它不只是回答問題，還能主動讀取檔案、執行指令、呼叫工具，完成你交辦的完整工作。

🔑
核心差異
一般 AI 聊天：你問一句 → AI 答一句
AI Agent：你說「幫我整理這份報告」→ Agent 自動讀取、分析、生成結果，全程無需手動干預。

OpenAI 的 Codex 是目前最強大的 AI 編程代理，能在 CLI、IDE 外掛或 Web App 中幫你自動寫程式、修 bug、跑測試。

🔄 Agent 的工作流程

1
你給任務（Prompt）

用自然語言描述你想做什麼

2
Agent 規劃步驟

分析任務、找出需要的工具 and 資訊

3
自動執行

讀檔、呼叫 API、執行指令、修改程式碼

4
回報結果

完成任務，讓你審查確認

🎯 快速測驗

下列哪一個描述最符合「AI Agent」與「一般 AI 聊天」的本質差異？

✍️
Chapter 02
寫出好的提示詞（Prompt）

提示詞不需要完美，但越清楚，Agent 的結果越可靠。OpenAI 建議一個好的 Prompt 包含 四個核心要素：

🎯
Goal
目標
你想改什麼或做什麼？
📁
Context
脈絡
哪些檔案、錯誤訊息、範例是相關的？
⚙️
Constraints
限制
有哪些規範、架構、安全要求？
✅
Done When
完成條件
什麼狀態叫做「完成」？

📝 Prompt 範例對比

❌ 不好的 Prompt
幫我修好那個 bug
✅ 好的 Prompt
目標：修正登入失敗 bug
脈絡：auth/login.py 第 42 行 KeyError
限制：不改 DB schema，維持 Python 3.9
完成：登入單元測試全部通過

⚡ 推理等級

Low快速、範圍清楚的小任務
Medium / High複雜修改或 debug 任務
Extra High長時間、需要深度推理的任務
💡 在 Codex App 裡，可以用語音輸入口述任務，不用打字！描述複雜需求特別方便。
🎯 快速測驗

一個好的 Prompt 應包含哪四個要素？

🗺️
Chapter 03
先規劃，再行動（Plan First）

面對複雜或模糊的任務，不要急著讓 Agent 直接開始做，而是先讓它「規劃」再「執行」，大幅降低走錯方向的風險。

🏗️
生活比喻
蓋房子不會直接叫工人動工，而是先看設計圖、確認需求、再拿到施工許可。AI Agent 也一樣——複雜任務需要先形成計畫。

📋 三種規劃方式

1
Plan Mode（規劃模式）

最簡單。輸入 /plan 或按 Shift+Tab，Agent 先提問、整理計畫，再開始寫程式。

2
請 Agent 先採訪你

告訴 Agent：「請先問我問題，挑戰我的假設，把模糊想法變成清楚需求，再開始寫程式。」

3
PLANS.md 執行計畫模板（進階）

建立 PLANS.md 文件，定義多步驟任務的標準執行流程。

⚠️
新手常犯的錯誤：跳過規劃直接執行複雜任務。結果是 Agent 完成了很多工作，但方向是錯的，反而要花更多時間修正。
🎯 快速測驗

當你要請 AI Agent 完成一個「複雜、模糊的任務」時，最佳做法是什麼？

📄
Chapter 04
AGENTS.md — Agent 的工作手冊

AGENTS.md 是你給 Agent 的「永久指令」，讓它每次開始工作時自動讀取你的期望與規範，不需要每次重複說明。

👷
生活比喻
請了新工讀生，你可以每天當面交代規則，也可以給他一本「員工手冊」讓他自行閱讀。AGENTS.md 就是那本手冊——一次寫好，Agent 每次都會遵守。

📋 AGENTS.md 應包含的內容

  • 📁 專案結構：重要資料夾和檔案的說明
  • 🚀 執行方式：啟動、測試、建置的指令
  • 📏 程式規範：命名慣例、程式風格
  • 🚫 禁止事項：什麼事 Agent 不可以做
  • ✅ 完成定義：什麼叫做一個任務「完成」了

📂 可放在多個層級

  • ~/.codex/AGENTS.md：個人預設（所有專案適用）
  • 專案根目錄：整個專案的規範
  • 子資料夾：局部特殊規則（優先度最高）
⚡ CLI 指令 /init 可快速建立基礎 AGENTS.md。建立後再根據實際需求修改即可。短而準確比長而模糊更有效！
🎯 快速測驗

關於 AGENTS.md，以下哪個說法是正確的？

🔍
Chapter 05
驗證與審查 — 不要盲目接受

Agent 產出程式碼只是開始，要求它自我驗證和審查才是完整的工作流程。

🔄
完整的 Agent 工作迴圈
撰寫程式碼 → 撰寫/更新測試 → 執行測試 → 程式碼審查 → 確認完成

✅ 要求 Agent 執行的驗證清單

  • 為修改的功能撰寫或更新測試
  • 執行完整的測試套件
  • 通過 lint、型別檢查、格式化
  • 最終行為符合任務要求
  • 審查 diff，找出可能的 bug 或回歸問題
🛠️ 在 Codex App 使用 /review 指令，可對 PR、未提交的修改或特定 commit 進行程式碼審查。
🏢 OpenAI 內部所有 PR 都由 Codex 執行 100% 程式碼審查！你也可以在 GitHub 整合中啟用這個功能。
🎯 快速測驗

Agent 完成程式碼修改後，下一步最應該做什麼？

🔗
Chapter 06
MCP — 連接外部世界

MCP（Model Context Protocol） 是開放標準，讓 AI Agent 連接外部工具和系統，如資料庫、Slack、GitHub、Jira 等，無需手動複製貼上資訊。

📱
生活比喻
MCP 就像是手機的 App Store——你可以為 AI Agent 安裝「插件」，讓它存取更多外部資訊和工具。

🎯 什麼時候使用 MCP？

  • 📦 需要的資訊存在於程式庫之外（Jira ticket、資料庫）
  • 🔄 資料經常變動（每天報告、即時數據）
  • 🔧 需要 Agent 呼叫工具，不靠手動貼上指令
  • 👥 需要跨用戶、跨專案的可重複整合

🌟 常見 MCP 應用場景

  • 🐛 讀取 GitHub Issues / Jira Tickets 來修 bug
  • 📊 連接資料庫查詢即時數據
  • 💬 整合 Slack 發送通知
  • 📁 存取 Google Drive 文件
⚠️
新手建議：不要一次接上所有工具！先從 1-2 個最常用的工具開始，找到真正能省時間的整合點，再慢慢擴展。
🎯 快速測驗

你想讓 AI Agent 自動讀取最新的 Jira Bug 票並修復程式碼。最適合使用什麼技術？

⚡
Chapter 07
Skills — 打包你的工作方法

當你發現自己重複使用同樣的 Prompt，或反覆糾正同樣的問題時，就是時候把它打包成 Skill（技能包）了。

📦
什麼是 Skill？
一個 SKILL.md 文件，定義可重複使用的工作方法——包含說明、輸入輸出格式、使用時機。Agent 讀取後就能一致地執行任務。

🎯 哪些工作適合做成 Skill？

  • 📋 Log 分析：每天分析系統錯誤日誌
  • 📝 Release Notes：依照固定格式整理版本說明
  • 🔍 Code Review：按照團隊規範審查 PR
  • 📊 每週進度摘要：整理 Jira / GitHub 本週成果
  • 🐛 標準除錯流程：按步驟診斷常見問題

📂 Skill 存放位置

  • $HOME/.agents/skills：你的個人技能（私有）
  • 專案 .agents/skills：團隊共用技能（可放進 Git）
🚀 使用內建的 $skill-creator Skill 可快速建立新技能！第一個版本先在本地測試，穩定後再分享給團隊。一個黃金法則：如果你重複用同樣的 Prompt 超過 3 次，就應該做成 Skill。
🎯 快速測驗

你發現自己每週都要對 Agent 說「依照我們的格式幫我寫 Release Notes」，每次都需要重新說明格式。最好的解決方案是什麼？

⏰
Chapter 08 · 最終章
自動化 — 讓 Agent 在背景工作

當工作流程已經穩定且可預測時，設定 Automation（自動化排程），讓 Agent 在背景定時執行，完全不需要你手動觸發。

⚖️
Skill vs Automation 的關係
Skill 定義「怎麼做」（方法）
Automation 定義「何時做」（排程）
原則：Skill 先做好，穩定後再設 Automation。

🎯 適合自動化的任務

  • 🌅 每天早上：摘要昨天 commits，生成 standup 報告
  • 🔎 定期掃描：每週檢查潛在 bug 或安全漏洞
  • 📋 每次 PR：自動進行程式碼審查
  • 🚨 CI 失敗時：分析錯誤原因，提供修復建議
  • 📰 每次版本：自動產生 Release Notes 草稿
💡 Automation 不只是執行任務，也適合用來「反省和維護」——每週回顧 Agent 工作記錄，找出重複問題，更新 AGENTS.md 或 Skill。
🎯 最終測驗 — 綜合判斷

你的團隊每天花 30 分鐘整理「昨日 Bug 修復摘要」，格式固定。哪個 AI Agent 最佳實踐組合最適合解決這個問題？

🏆
課程完成！

你已掌握 AI Agent 核心工作方法

0
/ 8 答對

📌 學習成果與錯題分析