A2 — 讓 CLI agent 每次都照同一套方法做事¶
← A1 — 安全完成第一個 CLI 任務 · Track A: CLI Power User 第 2 站 · 下一站：Stage 5 的 Track A 核心
這一站只解決一個問題：怎麼讓 CLI agent 下次進到同一個 repo，還記得同一套做事方法？
你會把每次都要知道的規則寫進專案規則檔，把常常重複的步驟做成 Skill。臨時任務才留在單次 prompt。這樣就像把「每天都要重新交代」改成「牆上有守則，工具箱裡有操作卡」。
🧩 先認識三個核心詞¶
| 核心詞 | 它是什麼、像什麼 | A2 怎麼用 | 不適合放什麼 |
|---|---|---|---|
| Project instructions（專案規則） | 每次進工作室都要看的共同守則 | 放專案用途、禁止事項、測試指令與交付格式 | 不放只用一次的任務或長篇參考資料 |
| Skill（操作卡） | 有需要時才拿出的可重用操作卡 | 放 review、release、整理文件等重複流程 | 不是每家 CLI 都使用相同路徑、權限或 frontmatter |
| One-off prompt（單次提示） | 只交代今天這一件事的便條 | 放本次任務、範圍、輸入與成功條件 | 不用它重複貼上每次都相同的專案規則 |
📌 學習目標¶
- 用四個欄位寫出一份短而清楚的專案規則。
- 把重複的 review 流程做成一個只讀 Skill。
- 分清哪些內容可以共用，哪些檔名、權限與命令要跟著工具調整。
展開時間、先備條件、環境與費用
- 時間：先完成 CLI-5、CLI-6；CLI-7、CLI-8 可以之後再做，不必一次做完。
- 先備條件：完成 A1，會看
git status、git diff，並有一個不含秘密、可復原的 demo repo。 - 環境：選一個主用 CLI agent。Claude Code、Codex、Gemini CLI、OpenCode 的檔名不完全相同，下方有對照。
- 費用：寫規則檔與 Skill 不會產生模型費用；請 CLI 測試時可能使用額度或 API token。以當日官方 usage／pricing 頁為準。
還沒完成 A1 時，先回去跑一次「只讀取 → 看計畫 → 小改動 → git diff → 復原」。
📚 必修閱讀¶
- 先看你主用工具的 project-instructions 官方文件：Codex 看
AGENTS.md、Claude Code 看CLAUDE.md、Gemini CLI 看GEMINI.md、OpenCode 看AGENTS.md。 - 再看你主用工具的 Skill 文件：Codex／ChatGPT、Claude Code、Gemini CLI、OpenCode。
- 最後回看 Stage 2 — Prompt 設計，把「任務、範圍、成功條件」補進單次 prompt。
展開四個 CLI 的規則檔與 Skill 位置
官方資料查核日：2026-08-30 UTC。
| 工具 | 專案規則 | Project Skill | 要注意什麼 |
|---|---|---|---|
| Codex | AGENTS.md |
.agents/skills/<name>/SKILL.md |
規則會依目錄分層；較近的規則較晚載入 |
| Claude Code | CLAUDE.md |
.claude/skills/<name>/SKILL.md |
舊 .claude/commands/ 仍相容，但新流程優先用 Skill |
| Gemini CLI | GEMINI.md |
.agents/skills/<name>/SKILL.md 或 .gemini/skills/… |
Skill 啟用時會要求同意；不要把秘密放進 Skill |
| OpenCode | AGENTS.md 優先；無此檔時用 CLAUDE.md |
.opencode/skills/…、.agents/skills/… 或 .claude/skills/… |
先查 rules、skills 與 permission 設定 |
共同的是「要交代哪些事」；不同的是檔名、搜尋位置、權限與額外設定。不要把一個工具的專屬功能當成所有 CLI 都有。
🛠 動手練習¶
動手練習 CLI-5：做一張最小專案規則卡¶
成果： CLI agent 每次進 repo，都知道這個專案做什麼、不能碰什麼、怎麼驗證，以及完成時要回報什麼。
先選上方對照表中屬於你工具的規則檔，再放入這四件事：
# 專案規則
- 用途：這是一個練習用文件 repo。
- 不可做：不要刪檔、不要讀取秘密、不要自動 commit 或 push。
- 驗證：修改後執行 `git diff --check`。
- 回報：說明改了什麼、驗證結果，以及仍未處理的事。
這張卡只放「每次都要知道」的事。長篇教學、API 參考與偶爾才用的流程不要塞進來。
展開 CLI-5 的建立與驗證步驟
- 在乾淨的 demo repo 建立你主工具使用的規則檔。先執行
git status --short，不要蓋到別人的未完成修改。 - 把上面的四欄換成這個 demo repo 的真實內容。指令必須可以複製執行；不要寫「把格式弄好」這種看不出成功與否的句子。
- 開一個新的 CLI session，請它只讀規則並用自己的話重述。若它找不到檔案，先查官方的檔名與載入範圍。
- 給一個會碰到禁止事項的測試，例如「直接 commit 這個改動」。正確結果是 agent 停下來或先詢問，而不是自行 commit。
- 先用
git status --short -- <規則檔路徑>看它是舊檔還是新檔。 - 舊檔：用
git diff -- <規則檔路徑>檢查。只有確認開始前該檔乾淨，才用git restore -- <規則檔路徑>復原。 - 新檔：Git 會顯示
??；git restore不能移除它。可以保留它當練習成果。若不要，先核對完整路徑，再用檔案管理員只刪除這一個檔案，最後重跑git status --short -- <規則檔路徑>。
沒有任何行數能保證規則一定好。只保留會改變行為的內容；某段只在特定任務使用時，把它移到 Skill 或其他按需文件。
動手練習 CLI-6：把重複 review 做成 Skill¶
成果： 你能叫 agent 執行同一套只讀 review，輸出 PASS 或具體問題，不會自己 commit、push 或部署。
Claude Code 使用 .claude/skills/review-changes/SKILL.md；Codex、Gemini CLI、OpenCode 可使用 .agents/skills/review-changes/SKILL.md。建立檔案後放入：
---
name: review-changes
description: Review the current git diff and report concrete risks. Use when the user asks to review local changes.
---
1. Read `git diff --no-ext-diff HEAD` without changing files.
2. Check for secrets, unsafe commands, broken links, and missing verification.
3. Report `PASS` when no problem is found; otherwise list each problem with its file and reason.
4. Do not edit, commit, push, deploy, or send messages.
name 是操作卡名稱；description 告訴 agent 何時拿這張卡。正文才是要照著做的步驟。
展開 CLI-6 的測試、權限與相容說明
- 先讀完
SKILL.md，確認沒有下載陌生程式、讀取秘密或改變外部系統的步驟。 - 在 demo repo 做一個小文件改動，但不要 commit。請 agent「review my local changes」，觀察它是否找到 Skill；也可依工具文件手動啟用。
- 對照
git diff檢查回報。測試後執行git status --short，確認 Skill 沒有偷偷改檔。 - 想在多個 CLI 共用時，先共用上面的核心內容，再依每個工具調整資料夾、權限與工具專屬 frontmatter。未知欄位可能被忽略，不要假設所有設定都有效。
Claude Code 的 .claude/commands/<name>.md 目前仍能建立同名 /name，但 Skills 已包含 custom commands，並支援附加檔案與按需載入。新教學使用 Skill；只有維護舊專案時才需要理解 legacy command。
動手練習 CLI-7：把大任務切成看得見的小步驟¶
成果： 你能把一個可復原的文件任務拆成「盤點 → 計畫 → 修改 → 驗證」，每一步都有看得見的結果。
展開 CLI-7 的比較練習與 multi-agent 延伸
選一個小任務，例如「替兩份 README 補上同一個執行指令」。第一次先請 agent 提計畫，不改檔；第二次請它依序盤點兩份檔案、列出差異、修改、跑 git diff --check，最後回報仍未處理的事。
比較兩次結果時，只問：有沒有漏檔、能不能復原、驗證是否真的執行。不要為了看起來厲害，把每個小步驟都分派給不同 agent。任務需要互相等待、會改同一批檔案，或你還說不清成功條件時，先用單一 agent。
完整的 subagent、agent team、背景工作與審查流程放在 Stage 5.5。A2 只練習把工作切清楚。
動手練習 CLI-8：做一張 portable prompt 對照卡¶
成果： 你能保留同一個任務核心，並清楚標出換工具時要改的檔名、權限、命令與啟用方式。
展開 CLI-8 的跨工具測試步驟
- 共用核心只寫四欄：任務、範圍、禁止事項、成功條件。
- 在第一個 CLI 的乾淨 demo repo 跑一次，記錄 CLI 版本、模型／provider、權限設定與
git diff。 - 復原後再換第二個 CLI。不要讓兩個會寫檔的 session 同時操作同一個目錄。
- 另外記下差異：project-instructions 檔名、Skill 位置、shell／sandbox 權限、工具名稱、登入與費用。
「Portable」代表核心意思容易搬，不代表整段文字與設定可以零修改複製。若第二個工具沒有同名功能，就回到成功條件，選它真正支援的方法。
🎯 精選 Projects¶
推薦度是本學習地圖的編輯建議，不是 GitHub stars。⭐⭐⭐⭐⭐ 表示：如果你選那個 CLI 路徑，這份官方文件或工具是必讀／必做；不是叫你讀完所有五星列。
下面按用途分成五組。同一組只顯示一次分類欄，避免重複文字把表格撐亂。
| 類型 | 資源 | 先看什麼 | 適合何時使用 | 推薦度 | 來源 |
|---|---|---|---|---|---|
| 官方專案規則 | Codex AGENTS.md | 分層載入與優先順序 | 替 Codex 寫 repo 規則 | ⭐⭐⭐⭐⭐ | 官方文件 |
Claude Code CLAUDE.md | 何時放規則、何時移到 Skill | 替 Claude Code 寫持續規則 | ⭐⭐⭐⭐⭐ | 官方文件 | |
Gemini CLI GEMINI.md | 目錄範圍與載入方式 | 替 Gemini CLI 放專案 context | ⭐⭐⭐⭐⭐ | 官方文件 | |
OpenCode AGENTS.md | rules 載入、合併與 fallback | 替 OpenCode 寫規則 | ⭐⭐⭐⭐⭐ | 官方文件 | |
| 官方 Skill 文件 | Codex／ChatGPT Build skills | SKILL.md 結構與載入位置 | 做 Codex 可重用流程 | ⭐⭐⭐⭐⭐ | 官方文件 |
| Claude Code Skills | 按需載入、legacy commands、權限 | 做 Claude Code Skill | ⭐⭐⭐⭐⭐ | 官方文件 | |
| Gemini CLI Agent Skills | discovery、安裝同意與啟用同意 | 管理 Gemini CLI Skill | ⭐⭐⭐⭐⭐ | 官方文件 | |
| OpenCode Agent Skills | 支援位置、frontmatter、permission | 做 OpenCode Skill | ⭐⭐⭐⭐⭐ | 官方文件 | |
| 標準與可讀範例 | Agent Skills specification | 共同格式的最低要求 | 想讓核心內容較容易跨工具 | ⭐⭐⭐⭐ | 標準 |
anthropics/claude-plugins-official | 官方 plugin 內的 Skills 與 commands | 想看 Skill 如何被打包分享 | ⭐⭐⭐⭐⭐ | GitHub repo | |
mattpocock/skills | 工程工作中使用的短 Skill 範例 | 想比較不同寫法 | ⭐⭐⭐⭐ | GitHub repo | |
obra/superpowers | 真實 workflow 如何拆成 Skills | 完成第一個 Skill 後再看 | ⭐⭐⭐⭐ | GitHub repo | |
| 索引與 prompt 練習 | hesreallyhim/awesome-claude-code | 按類型找 Claude Code 資源 | 已知道需求、想找更多範例 | ⭐⭐⭐ | GitHub repo |
anthropics/prompt-eng-interactive-tutorial | 一步一步比較 prompt 寫法 | CLI-8 卡在共用核心時 | ⭐⭐⭐⭐ | 官方 GitHub repo | |
| Repo context 工具 | yamadashy/repomix | 產生一次性的 codebase 快照 | 需要把 repo 內容整理給 agent | ⭐⭐⭐⭐⭐ | GitHub repo |
langchain-ai/openwiki | 建立可持續更新的 repo wiki | 大型 repo 需要按需查文件 | ⭐⭐⭐⭐ | GitHub repo |
✅ 進 Stage 5 前的自我檢查¶
- 我能用自己的話分清專案規則、Skill、單次 prompt。
- 我的規則卡有用途、禁止事項、驗證指令、交付格式，而且 agent 能讀到。
- 我的 review Skill 只讀取變更，測試後
git status --short沒有多出非預期修改。 - 我知道「共用核心」不等於「所有 CLI 的檔名與權限都一樣」。
四項都做到，就進入 Stage 5 的 Track A 核心，先讀 5.1–5.4，再前往 A3。若還沒做到，先回 demo repo 重跑 CLI-5 或 CLI-6，不必先讀完所有補充資料。
展開常見問題與修正方式
- 規則寫很多，agent 還是漏掉：先刪掉背景故事與重複句，只留可以觀察的行為。必須每次固定執行的安全檢查，應使用工具提供的 hook／policy，而不是只靠文字提醒。
- Skill 沒出現：檢查資料夾、
SKILL.md大小寫、YAML frontmatter 與工具支援的位置，再依官方方式 reload 或重開 session。 - Skill 自己做了危險動作：把 deploy、send、commit、push 改為只能由使用者明確啟用，並先用只讀版本測試。第三方 Skill 要先讀完內容和 scripts。
- 同一份 Skill 在另一個 CLI 壞掉：保留共同的目標與步驟，重新對照那個工具承認的 frontmatter、permission 與 tool 名稱；不要用猜的。
- 專案資訊太多：專案規則只當地圖，細節放在
docs/、Skill 的references/或其他按需文件。規則越長不代表越可靠。
安全底線：規則與 Skill 都是文字指令，不是絕對防護。不要放 API key、token 或個資；任何會寫檔、commit、push、部署或呼叫外部服務的流程，都要有可以看見的權限邊界與驗證步驟。