CLI Agent 新手入坑：三大家真正共有的 8 個命令（Claude Code / Codex CLI / OpenCode）

裝完 Claude Code，第一次在 prompt 敲 /，跳出來 90 幾個命令——這不是誇張，是 我自己 grep 官方 docs 數出來的 。Codex CLI 大概 40 個，OpenCode 大概 20 個。三家加起來破百，你坐在那邊滑著選單想：「我到底要記哪幾個才能開始幹活？」

我也是這樣愣過。後來把三家官方 docs 整個爬一遍，發現一件事：真正三家都有、語意又夠接近的內建命令，只有 8 個。把這 8 個吃透，你就能跨工具切換，不必在每次換家時重學一輪。

這篇是給準備入坑的人看的——不講花俏、不秀進階；講 8 個命令、3 個必踩坑，和一條「第一天就能跑」的工作流。

---

三大家是誰？要選哪一家入坑？

先說人是誰：

工具	出身	語言	架構	開源
Claude Code	Anthropic 官方	TypeScript / Node.js	Standalone	否
Codex CLI	OpenAI 官方	Rust	Standalone	是（Apache 2.0）
OpenCode	sst.dev （GitHub org sst）	Go（server）+ TypeScript / Bun（TUI）	Client / Server	是（MIT，168k+ stars ）

實戰選擇講白話：

• 想要功能最齊全、Claude 模型強：選 Claude Code ，命令 90 個爆炸給你，連 /stickers（訂貼紙）/voice（語音輸入）都有，廢到笑但有用的也不少。
• 想要 ChatGPT 訂閱戶免費 + 跑 CI / 自動化：選 Codex CLI ，命令精簡正交，sandbox + approval + plan mode 三層防護做得最嚴。
• 想要自由換 model、隱私、跨裝置：選 OpenCode ，唯一 client/server 架構，SSH 斷線後重連，跑中的任務還活著——這在跨域工作或長任務時夭壽好用。

三家不必選邊站。我自己是平常 Claude Code 主力、CI 用 Codex、長跑任務或想換 Sonnet/GPT/Gemini 比較時切到 OpenCode。能跨家的關鍵就是接下來這 8 個命令。

---

三家真正共有的 8 個命令

把三家的官方 slash commands 列表交叉比對之後，所有三個工具都內建、語意相近的命令只有這 8 個：

命令	Claude Code	Codex CLI	OpenCode	一句話用途
/init	產生 CLAUDE.md	產生 AGENTS.md	產生 AGENTS.md	專案初始化掃描
/clear	aliases /reset /new	清螢幕＋新對話	/new 的 alias	開新對話
/compact	[instructions] 可指定焦點	摘要對話釋放 context	alias /summarize	壓縮對話
/help	顯示全部命令	顯示全部命令	顯示全部命令	忘記就敲它
/model / /models	單數	單數	複數	切換模型
/resume	[session] 或選單	從本地 transcript	alias /sessions /continue	恢復過去 session
/exit / /quit	/exit	兩個都收	/exit /quit /q	離開
/diff	含 untracked	含 untracked	沒有原生，用 !git diff	看 Git diff

⚠️ 嚴格講 /diff 在 OpenCode 不是原生 slash 命令，但 OpenCode 支援 ! 前綴跑 shell 命令，敲 !git diff 就行，所以放寬算進來。如果你龜毛，真共有只有 7 個。

8 個命令我幫你分成三組記憶：

開局 / 收工：/init /exit
對話管理：/clear /compact /resume
日常操作：/help /model /diff

這分組不是亂湊的——這正是你在一個 session 從頭到尾會經過的順序。

---

/init 看似一樣，產物完全不同（最容易踩第一坑）

三家 /init 都會「掃描你的專案、生成一份 markdown，給 agent 每次對話開頭讀」。但產物檔名不一樣：

• Claude Code → CLAUDE.md
• Codex CLI → AGENTS.md
• OpenCode → AGENTS.md

AGENTS.md 是社群在 2025 年慢慢收斂出來的「跨工具標準」，目前 Codex、OpenCode、Cursor、Amp、Zed 全部採用。只有 Claude Code 還在堅持自家的 CLAUDE.md——這件事在 GitHub 上吵了將近一年（issue #6235 自 2025-08 開到現在），到 2026 年中還沒結論。

那實務上怎麼處理？兩種解法：

解法一：symlink 大法（跨工具團隊推薦）

# 在專案根目錄
touch AGENTS.md
ln -s AGENTS.md CLAUDE.md
# 之後只維護 AGENTS.md，CLAUDE.md 自動跟著動

這招 HN 上 很多人在用 ，乾淨。

解法二：在 CLAUDE.md 內嵌 AGENTS.md

# CLAUDE.md
@AGENTS.md
（其他 Claude 專屬指令…）

Anthropic 官方有承認這招會把 AGENTS.md 內容塞進 system prompt，等同直接讀。

順帶一提：OpenCode 會自動讀 CLAUDE.md——如果你已經寫好 CLAUDE.md 想切到 OpenCode，啥都不用改。Codex 不會，需要自己改名。

還有一個雷：別亂跑 /init

HumanLayer 的這篇 講得直白：自動生成的 CLAUDE.md / AGENTS.md 通常太長，會塞滿每一次對話的 context window，反而降低品質。

實戰建議：/init 第一次跑就好，跑完立刻精簡——只留下 LLM「光看 repo 結構推不出來」的東西（例如：團隊內部用詞、隱私限制、特殊架構決策）。剩下的全刪。50 行就很夠。

---

/clear vs /compact vs /resume——新手最容易死的三條 alley

這三個命令長得很像，做的事差很多。我看過太多人把它們搞混，結果不是燒爆 token，就是把重要對話清掉。

/clear——徹底重置

session 開始 → 講了三件事 → /clear → 對話歸零，但檔案改動還在

三家都有，但 alias 略不同：

• Claude Code：/clear /reset /new 三個都一樣，/clear [name] 還可以順手把舊對話命名存到 /resume 選單裡（這設計超貼心）
• Codex CLI：/clear 直接清螢幕＋開新對話。如果只想清螢幕保留對話，按 Ctrl+L
• OpenCode：/new 才是本名，/clear 是 alias。前一個 session 自動留在 /sessions 列表

⚠️ 三家都不會還原檔案改動。要還原檔案：

• OpenCode：/undo（內建用 git 管，乾淨）
• Claude Code：/rewind（可選「只還原程式碼 / 只還原對話 / 都還原」）
• Codex CLI：手動 git restore，沒有 slash 命令

/compact——壓縮但保留

session 開始 → 講了 30 件事 → /compact → LLM 摘要前 28 件，最後 2 件保留原樣

三家都有，這是「長對話救命招」。社群公認最大的省 token 技巧不是 /compact，是用 /clear 換題。但如果你「想繼續同一個任務、但 context 已經滿到警告了」，這時 /compact 才出場。

Claude Code 還能帶參數指定保留焦點：

/compact Focus on the auth module and the failing tests

OpenCode 對應命令是 /summarize（與 /compact 互為 alias）。Codex 跑 /compact 會先問你確認再壓——保守派最愛。

/resume——三家「貌合神離」，差異最大

表面三家都做「恢復過去 session」，但底層機制完全不同：

工具	機制	體感
Claude Code	讀存檔的 transcript 重啟	冷啟動，狀態凍結重建
Codex CLI	讀本地存檔的 transcript 復原	類似 Claude，靜態
OpenCode	連回 live 的後台 server	session 還活著，跑中任務沒中斷

夭壽，這就是為什麼 Medium 上有篇比較文 一直強調 OpenCode 的「session 持久性」是真差異化——它是唯一不怕 SSH 斷線的工具。

如果你的工作流會涉及長跑任務（測試套件、大型重構、批次處理），這個差異會直接影響你選哪家。

---

第一天就能跑的 6 步工作流

這套流程在三家 CLI 都通用。把它印出來貼螢幕旁邊，第一週照著做就對了。

# Step 1：進專案
cd /path/to/project

# Step 2：啟動工具（擇一）
claude          # Claude Code
codex           # Codex CLI
opencode        # OpenCode

# Step 3：第一個動作——產生專案說明檔
/init
# 跑完立刻打開 CLAUDE.md / AGENTS.md，刪掉 80% 廢話

# Step 4：開始對話
> 這個專案是做什麼的？先給我一張架構圖

# Step 5：對話一長就壓縮
/compact

# Step 6：commit 前看改動
/diff
# OpenCode 是 !git diff

# 隔天接續
/resume

# 換完全不同的任務時
/clear

# 收工
/exit

口訣（建議背起來）：

/init 開局、/clear 換題、/compact 續命、/resume 接班、/diff 防爆、/exit 收工。

學會這 6 個動詞，你就能在三家 CLI 之間自由換家。其他 90+ 個命令是進階課題，等你穩了再慢慢吃。

---

三家獨家亮點（值得知道但別現在學）

最後留一張小抄，講三家「最值得多看一眼」的獨家命令。第一週不用碰，但知道它們存在，之後遇到痛點才知道要去找哪一家。

Claude Code 獨家

• /rewind：選擇性回滾「程式碼 / 對話 / 兩者」。我覺得這是 Claude Code 最神的命令，比 git stash 還順手。
• /btw <question>：「順便問一下」——暫時插隊問問題，不污染主對話。寫到一半想確認某 API 用法時超好用。
• /security-review：對 pending 變更做安全審查。
• /skills：列出所有 skill（社群在 這個寶藏地圖 收集了不少）。

Codex CLI 獨家

• /personality：對話風格（friendly / pragmatic / none）。pragmatic 模式不會跟你寒暄，CI 用爆好。
• /approve：批准 auto-review 拒絕的動作重試。
• /experimental：開啟實驗功能，例如 subagents。

OpenCode 獨家

• /share：產生公開 URL（opncd.ai/s/...），把 session 丟給同事看，連 onboarding 都省了。
• /unshare：撤回分享。
• /details / /thinking：toggle 工具細節與思考顯示。debug 神器。

---

寫在最後：別被命令數量嚇跑

90+ 個命令看起來嚇人，真正用到的就那 8 個。其他都是「你想到時才存在」的工具——遇到痛點才查 /help，不必預先全部記住。

CLI agent 這場仗打到 2026 年，三家已經明顯收斂在共通詞彙上：/init 產說明檔、/clear 換題、/compact 續命、/resume 接班。再過半年大概還會多幾個共通命令（/skills 看起來會收斂、/hooks 也快了），這篇之後我會更新。

入坑就從 /init 開始，跑完刪掉 80% 自動生成的內容，剩下的事就讓 agent 幫你做。

---

延伸閱讀

• Claude Code Commands 官方文件
• Codex CLI Slash Commands 官方文件
• OpenCode TUI Commands 官方文件
• agents.md 跨工具標準
• Writing a good CLAUDE.md (HumanLayer)
• Claude Code vs Codex vs OpenCode 2026 比較
• HN: How I use every Claude Code feature
• Claude How-To 社群整理

延伸閱讀

• 我不再 prompt AI 了，我寫 loop——Loop Engineering 是什麼，為什麼它正在吃掉 prompt engineering
• 你一直在用錯誤的方式 prompt Claude：Karpathy 的三層工作法
• 為什麼 Gemini 寫程式總被嫌？拆開來看，問題根本不在模型
• Claude Code 動態工作流程實戰：一個對話塞不下時，就讓上千個 subagent 一起上

GitHub CLI 教學：高效的開發工作流程

關於本教學
本教學適合想要透過命令列提升GitHub工作效率的開發者，從基礎功能到進階工作流程都有涵蓋。

## 引言

GitHub命令列工具（GitHub CLI） 是提升開發工作流程效率的絕佳工具。透過命令列介面操作GitHub，您可以更快、更有條理地管理專案，無需頻繁切換至瀏覽器界面。本教學將帶您了解GitHub CLI的主要功能和實用工作流程。

安裝與設置

要開始使用GitHub CLI，首先需要安裝它：

各平台安裝命令
macOS (使用Homebrew):

brew install gh

Windows (使用Scoop):

scoop install gh

Linux (Debian/Ubuntu):

sudo apt install gh

安裝後，您需要進行驗證：

gh auth login

遵照螢幕上的指示，選擇通過瀏覽器或令牌（token）進行身份驗證。

基本命令介紹

GitHub CLI使用gh作為主命令，後接不同的子命令執行各種操作：

常用指令類別
| 指令 | 功能 | | ---- | ---- | | gh repo | 倉庫管理 | | gh issue | 問題追蹤 | | gh pr | 拉取請求操作 | | gh release | 版本發布 | | gh gist | 代碼片段管理 |

每個命令都有自己的子命令和選項，可以通過`gh help [command]`獲取幫助。

實用使用案例

讓我們看一些實際使用案例，幫助您更好地理解GitHub CLI在日常開發中的應用：

以下案例展示了GitHub CLI如何在各種場景中幫助您提高工作效率。

### 案例1：快速複製並參與開源專案

想要貢獻某個開源專案？GitHub CLI可以讓這個過程變得簡單：

快速參與開源專案的命令
```bash

複製倉庫並自動在您的帳號創建fork

gh repo fork cli/cli

自動為您設置遠端倉庫，無需手動配置

如果只想創建fork但不clone到本地

gh repo fork cli/cli --clone=false

創建分支並開始工作

git checkout -b feature-branch

完成工作後，直接從命令行提交PR

gh pr create --title "實現新功能" --body "解決了#123問題"

</div>
這個流程讓您無需在瀏覽器和終端間切換，顯著提高效率。

### 案例2：快速查看和管理專案狀態

需要快速了解專案中的問題和拉取請求？

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>專案狀態查詢命令</strong><br>```bash
# 列出所有開放的PR
gh pr list

# 查看特定PR的詳細信息
gh pr view 21

# 列出分配給您的issue
gh issue list --assignee @me

# 查看特定issue的詳細信息和評論
gh issue view 13 --comments

### 案例3：團隊協作和代碼審查

GitHub CLI提供強大的代碼審查功能，讓團隊協作更高效！

代碼審查相關命令
```bash

檢出同事的PR到本地，進行審查

gh pr checkout 15

在終端中查看PR的差異

gh pr diff

直接在命令行中批准PR

gh pr review 15 --approve

或者提出評論和修改建議

gh pr review 15 --comment -b "請考慮優化這部分的性能"

</div>
### 案例4：自動化工作流程整合

將GitHub CLI整合到您的自動化腳本中：

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>自動化工作流程命令</strong><br>```bash
# 創建新版本發布
gh release create v1.0.0 --title "第一個穩定版本" --notes "修復了多個bug和性能優化"

# 監控GitHub Actions工作流程
gh run list

# 等待特定工作流程完成
gh run watch

這些使用案例展示了GitHub CLI如何在各種場景中幫助您提高工作效率。

分支保護設置

在使用GitHub CLI之前，建議先設定分支保護規則，確保工作流程的安全性：

沒有適當的分支保護設置，可能導致團隊成員意外直接推送至主分支。

1. 在GitHub網站上導航至您的倉庫 2. 點擊「Settings」→「Branches」 3. 點擊「Add rule」為主分支（通常是`main`）添加保護規則 4. 建議的設置： - 勾選「Require a pull request before merging」 - 勾選「Require approvals」（團隊協作時） - 勾選「Require status checks to pass before merging」 - 勾選「Do not allow bypassing the above settings」

這些設置將防止直接推送到主分支，確保所有變更都經過PR流程審核。

工作流程教學：從issue到PR到合併

GitHub CLI支持完整的開發工作流程，下面是一個典型範例：

步驟1：創建Issue

每個新功能或修復都從創建issue開始：

Issue創建命令
```bash gh issue create -t "添加新功能：使用者註冊" -b "實現使用者註冊功能，包括表單和驗證"

或者使用交互模式：

```bash
gh issue create

系統會提示您輸入標題、描述和其他詳細信息。

步驟2：從Issue創建開發分支

這是GitHub CLI的強大功能之一，您可以直接從issue創建並切換到新分支：

從Issue創建分支
```bash gh issue develop [issue編號] -c

</div>
這個命令會：

- 創建一個基於issue標題的新分支
- 將分支與issue關聯
- 自動切換到新分支

現在您可以開始編寫代碼了！

### 步驟3：提交更改並推送

完成工作後，提交您的更改：

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>提交與推送命令</strong><br>```bash
git add .
git commit -m "添加使用者註冊功能"
git push -u origin HEAD

### 步驟4：創建PR

使用GitHub CLI創建PR：

PR創建命令
```bash gh pr create

系統會提示您輸入標題（默認使用提交信息）和描述。您也可以使用`-d`標記創建草稿PR：

```bash
gh pr create -d

草稿PR表示工作仍在進行中，尚未準備好審核。

步驟5：將草稿PR標記為準備就緒

當您的工作完成並準備好審核時：

將PR標記為準備就緒
```bash gh pr ready

</div>
### 步驟6：審核和合併PR

查看PR的狀態：

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>PR審核與合併命令</strong><br>```bash
gh pr view

合併PR（如果您有權限）：

gh pr merge

您可以選擇合併方式（標準合併、壓縮合併或變基合併）。

GitHub工作流程視覺化指南

以下使用Mermaid圖表視覺化展示GitHub完整工作流程，從初次提交到分支開發、合併與發布：

初始化倉庫與首次提交

[mermaid 圖表 — 原始 HackMD 版本可正常渲染]

flowchart TB A[開始專案] --> B["初始化本地倉庫
git init"] B --> C["建立必要檔案
echo '# 專案名稱' > README.md
echo '初始版本' > CHANGELOG.md"] C --> D["添加檔案
git add README.md CHANGELOG.md .gitignore"] D --> E["首次提交
git commit -m '初始提交: 建立專案結構'"] E --> F["創建遠端倉庫
gh repo create my-project --public --source=."] F --> G["推送至遠端
git push -u origin main"]

style A fill:#f9f,stroke:#333,stroke-width:2px
style G fill:#bbf,stroke:#333,stroke-width:2px</div>

查看詳細實現代碼
```bash

初始化本地倉庫

git init

建立忽略檔案 (最佳實踐)

cat > .gitignore << 'EOF'

依語言自動生成適合的 .gitignore

可訪問 https://gitignore.io/ 獲取適合您專案的內容

node_modules/ *.log .DS_Store .env EOF

添加文件

echo "# 我的專案" > README.md echo "初始版本" > CHANGELOG.md git add README.md CHANGELOG.md .gitignore

首次提交

git commit -m "初始提交: 建立專案結構"

使用GitHub CLI創建遠端倉庫 (推薦選項)

gh repo create my-project
--public \ # 公開倉庫，使用 --private 創建私有倉庫 --description "我的新專案描述" \ # 添加描述 --homepage "https://myproject.com" \ # 可選的主頁 --source=. \ # 使用當前目錄作為源 --remote=origin \ # 設置遠端名稱 --gitignore Node # 自動添加語言特定的.gitignore (可選)

如果需要添加授權文件

gh repo edit --add-license mit # 添加MIT授權

推送至遠端

git push -u origin main # 或 git push -u origin master 若使用舊版Git

驗證倉庫創建成功

gh repo view --web # 在瀏覽器中打開倉庫

常見問題解決：

如果遇到分支名稱問題 (master 與 main)

git branch -M main # 將當前分支重命名為main

</div>
**建議選項與最佳實踐：**

<div style="background:#d9edf7;border-left:4px solid #31708f;color:#31708f;padding:12px 16px;margin:12px 0;border-radius:4px">

- 使用有意義的倉庫名稱和描述，方便他人理解專案目的
- 建立 `.gitignore` 文件排除不需要版本控制的檔案
- 添加 `LICENSE` 和詳細的 `README.md` 說明專案用途和使用方法

</div>
使用結構化格式獲取倉庫資訊：

```bash
gh repo view --json name,description,visibility,defaultBranchRef

創建私有倉庫時添加協作者：

gh repo create --private my-project
gh repo add-collaborator my-project username --permission admin

開發分支與Bug修復流程

[mermaid 圖表 — 原始 HackMD 版本可正常渲染]

flowchart TB A["主分支
git checkout main
git pull"] --> B["建立問題
gh issue create -t '修復登入問題'"] B --> C["創建分支
gh issue develop issue編號 -c"] C --> D["修改代碼
(編輯相關檔案)"] D --> E["提交修復
git add .
git commit -m '修復登入問題'"] E --> F["推送分支
git push -u origin HEAD"] F --> G["創建PR
gh pr create --title '修復登入問題'"] G --> H{"需要修改?"} H -- 是 --> I["審查反饋
gh pr view --comments"] I --> J["修改代碼
(根據反饋修改)"] J --> K["提交修改
git commit -am '根據審查調整'
git push"] K --> H H -- 否 --> L["合併PR
gh pr merge --squash"] L --> M["清理分支
git checkout main
git pull
git branch -d bugfix-branch"]

style A fill:#bbf,stroke:#333,stroke-width:2px
style M fill:#bbf,stroke:#333,stroke-width:2px</div>

使用GitHub CLI實現完整修復流程
```bash

確保main分支最新

git checkout main git pull

創建並切換到bugfix分支

gh issue create -t "修復登入問題" -b "使用者無法在Safari瀏覽器登入" gh issue develop $(gh issue list --limit 1 --json number --jq '.[0].number') -c

設置分支追踪 (可選，方便後續操作)

git branch --set-upstream-to=origin/main

修復問題並提交

(進行必要的代碼修改)

git add . git commit -m "修復Safari登入問題" -m "詳細描述問題原因和解決方案"

遇到衝突時如何解決

git fetch origin main

git rebase origin/main

(解決衝突後)

git rebase --continue

推送分支到遠端

git push -u origin HEAD

創建PR (完整選項)

gh pr create
--title "修復Safari登入問題"
--body "解決issue #1中描述的Safari登入問題"
--assignee @me \ # 分配給自己 --label "bug,urgent" \ # 添加標籤 --milestone "v1.0" \ # 指定里程碑 --reviewer teammate1,teammate2 # 請求審核

檢查PR狀態

gh pr status

追蹤PR評論

gh pr view --comments

修改PR以回應審查意見

(進行修改後)

git add . git commit -m "根據審查意見調整" git push

等待審查後合併PR (多種選項)

gh pr merge
--squash \ # 壓縮合併，或使用 --merge/--rebase --delete-branch \ # 合併後刪除分支 --body "包含所有必要修復" # 自定義合併信息

同步本地環境

git checkout main git pull git branch -d bugfix-login-issue

如果忘記刪除遠端分支

gh pr list -s merged # 列出已合併的PR

gh pr view # 查看特定PR

git push origin --delete # 手動刪除遠端分支

</div>
**重要提示與最佳實踐：**

- 使用有意義的分支名稱，推薦格式: `<類型>/<描述>`，例如 `bugfix/safari-login`
- 提交詳細的PR描述，使用模板：

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>PR描述模板</strong><br>```markdown
## 問題描述
簡要說明問題

## 解決方案
如何解決

## 測試方法
如何驗證修復

Fixes #1

- 定期從主分支同步變更，避免大型合併衝突 - 使用 `gh pr ready` 標記草稿PR為可審核狀態 - 利用GitHub CLI監控CI/CD狀態: `gh run list --workflow=ci.yml`

版本發布流程

[mermaid 圖表 — 原始 HackMD 版本可正常渲染]

flowchart TB A["同步最新代碼
git checkout main
git pull"] --> B["確保測試通過
npm test"] B --> C["更新版本號
npm version patch
或手動更新package.json"] C --> D["更新變更日誌
更新CHANGELOG.md"] D --> E["提交版本更新
git add .
git commit -m '版本提升至 v1.0.0'
git push"] E --> F["創建標籤
git tag -a v1.0.0 -m '穩定版發布'
git push origin v1.0.0"] F --> G["發布版本
gh release create v1.0.0
--title 'v1.0.0 穩定版發布'
--notes-file CHANGELOG.md"] G --> H["添加發布資產
gh release upload v1.0.0 ./dist/app.zip"]

style A fill:#f9f,stroke:#333,stroke-width:2px
style H fill:#bbf,stroke:#333,stroke-width:2px</div>

使用GitHub CLI實現發布流程
```bash

確保在main分支上並同步最新變更

git checkout main git pull

建立版本標籤的不同方式

方式1: 使用語義化版本標籤

VERSION="1.0.0" echo "當前版本: $VERSION"

更新版本號（示例：在package.json中）

方式1: 手動編輯

方式2: 使用npm工具 (Node.js項目)

npm version patch --no-git-tag-version # 小版本更新

方式3: 使用jq工具 (通用方法)

jq '.version = "1.0.0"' package.json > tmp && mv tmp package.json

更新CHANGELOG.md (最佳實踐)

cat > CHANGELOG.md << 'EOF'

更新日誌

[1.0.0] - $(date +%Y-%m-%d)

新功能

• 實現使用者註冊
• 新增發布通知功能

修復

• 修復Safari登入問題
• 解決移動裝置顯示錯誤 EOF

提交版本更新

git add package.json CHANGELOG.md git commit -m "版本提升至 v1.0.0" git push

創建發布標籤

git tag -a v1.0.0 -m "v1.0.0 穩定版發布" git push origin v1.0.0

使用GitHub CLI創建完整發布 (多樣選項)

gh release create v1.0.0
--title "v1.0.0 穩定版發布"
--notes-file CHANGELOG.md \ # 使用CHANGELOG作為發布說明 --discussion-category "公告" \ # 創建討論主題 --target main \ # 指定目標分支 --verify-tag # 驗證標籤存在

可選: 添加發布資產

gh release upload v1.0.0 ./dist/app.zip ./docs/user-guide.pdf

可選: 發布後的維護操作

更新專案依賴

npm update --save

git add package.json package-lock.json

git commit -m "更新專案依賴"

git push

檢視並驗證發布

gh release view v1.0.0 gh release view v1.0.0 --web # 在瀏覽器中查看發布頁面

</div>
**版本發布最佳實踐建議：**

<div style="background:#dff0d8;border-left:4px solid #3c763d;color:#3c763d;padding:12px 16px;margin:12px 0;border-radius:4px">

- 使用[語義化版本控制](https://semver.org/lang/zh-TW/)規範（MAJOR.MINOR.PATCH）
  - MAJOR: 不兼容的API變更
  - MINOR: 向下兼容的功能新增
  - PATCH: 向下兼容的問題修復
- 維護詳細的CHANGELOG文件，記錄每個版本的更改
- 發布前進行完整測試，確保所有CI流程通過

</div>
為發布添加詳細文檔和使用示例:

- 使用預發布版本進行測試：
  ```bash
  gh release create v1.0.0-beta.1 --prerelease --title "v1.0.0 Beta 1"

• 設置自動化發布流程，利用GitHub Actions：

GitHub Actions發布工作流程
```yaml name: Release on: push: tags: ['v*'] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: npm ci - run: npm test - uses: softprops/action-gh-release@v1

</div>
這個視覺化工作流程展示了使用GitHub CLI管理整個軟體開發生命週期的方式，從初始化專案到功能開發、bug修復，再到版本發布。通過遵循這些步驟和使用GitHub CLI，您可以顯著提高團隊協作效率和代碼質量。

## 進階技巧：draft PR和PR驅動開發

### 使用草稿PR進行迭代開發

草稿PR非常適合用於長期持續開發的任務：

<div style="background:#d9edf7;border-left:4px solid #31708f;color:#31708f;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>草稿PR工作流程</strong><br>1. 創建草稿PR以早期獲取反饋
2. 持續在分支上工作並推送更新
3. 團隊成員可以實時跟踪和評論您的工作
4. 當準備就緒時，將PR標記為可審核

</div>
這種方法的優點：

- 保持工作透明度
- 提早發現潛在問題
- 避免大型PR帶來的審核困難
- 為長期工作保留開發記錄

### 多分支平行開發

當您同時處理多個功能時：

<div style="background:#d9edf7;border-left:4px solid #31708f;color:#31708f;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>平行開發策略</strong><br>1. 為每個功能創建單獨的issue
2. 從每個issue創建開發分支
3. 使用草稿PR跟踪每個功能的開發進度
4. 在不同分支間切換：`gh pr checkout [PR編號]`

</div>
當某個功能開發完成時，將其PR標記為可審核並合併，而不影響其他正在進行的工作。

## 總結與建議

GitHub CLI是一個強大的工具，能夠顯著提升您的開發工作流程效率：

<div style="background:#dff0d8;border-left:4px solid #3c763d;color:#3c763d;padding:12px 16px;margin:12px 0;border-radius:4px">

- 使用issue追踪任務和功能開發
- 遵循分支保護和PR流程，維護代碼質量
- 利用草稿PR進行透明的迭代開發
- 熟練使用GitHub CLI命令，減少上下文切換

</div>
最佳實踐：

- 為每個任務創建issue
- 保持PR規模小且集中
- 定期提交和推送更改
- 使用有意義的提交信息和PR描述
- 鼓勵團隊成員進行早期和持續的代碼審核

通過熟練運用GitHub CLI和這些工作流程，您可以建立更有組織、更高效的開發過程，無論是個人專案還是團隊協作。

## 常用命令參考

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>常用命令速查表</strong><br>```bash
# 倉庫操作
gh repo create           # 創建新倉庫
gh repo clone [倉庫]     # 克隆倉庫
gh repo view             # 查看當前倉庫信息

# Issue操作
gh issue list            # 列出issue
gh issue create          # 創建issue
gh issue view [編號]     # 查看issue詳情
gh issue develop [編號]  # 從issue創建開發分支

# PR操作
gh pr create             # 創建PR
gh pr list               # 列出PR
gh pr view [編號]        # 查看PR詳情
gh pr checkout [編號]    # 檢出PR分支
gh pr ready              # 將草稿PR標記為準備就緒
gh pr merge              # 合併PR

# 瀏覽器整合
gh browse                # 在瀏覽器中打開當前倉庫
gh pr view --web         # 在瀏覽器中查看PR

# 其他實用命令
gh run list              # 列出工作流程運行
gh release create        # 創建發布
gh gist create           # 創建代碼片段

## 參考資料

1. GitHub CLI官方文檔 - Examples
2. GitHub CLI官方快速入門
3. GitHub CLI - 將GitHub帶入命令行
4. GitHub CLI命令行工具(gh) - 知乎專欄

---

希望本教學能幫助您提升GitHub工作流程效率！

---

本文最初發布於 HackMD @BASHCAT。

延伸閱讀

• CLI Agent 新手入坑：三大家真正共有的 8 個命令（Claude Code / Codex CLI / OpenCode）
• 2026 我把 4000+ Claude Code Skills 裝進終端機之後 — 16 個值得收藏的 GitHub Repo 地圖