生活分享

Claude Code|從 Issue 到變更草稿:串起工具與程式碼

完成需求讀取、計畫、測試與 PR 說明稿。這一篇把一則待辦篩選 Issue 走到可供審查的變更與 PR 草稿:確認需求、建立分支、實作、測試、檢查差異,最後整理標題和正文。材料先在本機完成,不需要先取得外部服務權限;真正建立 GitHub 草稿 PR 則放在讀者已授權的測試儲存庫中執行。

閱讀時間約 6 分鐘

LINE 分享
從 Issue 到變更草稿:串起工具與程式碼:文件、螢幕與完成記號的幾何插圖
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 從 Issue 提取可驗收的需求
  2. 2. 準備乾淨的練習分支
  3. 3. 先列計畫,再做最小變更
  4. 4. 把驗證結果寫成具體證據
  5. 5. 產生本機 PR 正文並補齊
  6. 6. 在授權測試儲存庫建立草稿 PR
  7. 7. 在草稿中保留尚未完成的驗證
  8. 8. 常見問題與完成判準

這一篇把一則待辦篩選 Issue 走到可供審查的變更與 PR 草稿:確認需求、建立分支、實作、測試、檢查差異,最後整理標題和正文。材料先在本機完成,不需要先取得外部服務權限;真正建立 GitHub 草稿 PR 則放在讀者已授權的測試儲存庫中執行。

先讀、、及。下載第 84 篇材料,開啟 starter。需要 Git、Node.js 22;GitHub 步驟另需已登入 gh 與可寫的測試儲存庫。閱讀約 20 分鐘,實作約 60 分鐘。

從 Issue 提取可驗收的需求

從 Issue 提取可驗收的需求 → 準備乾淨的練習分支 → 先列計畫,再做最小變更
從 Issue 提取可驗收的需求 → 準備乾淨的練習分支 → 先列計畫,再做最小變更 · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

從 Issue 到變更草稿:串起工具與程式碼,以流程和文件圖形呈現教學重點。

fixtures/issue.json 是本課的固定 Issue 資料,編號一〇四,要求全部、未完成、已完成三種篩選,切換時保留原始資料。它明列不做帳號、雲端同步與正式部署。先把這些條件轉成檢查表,避免模型在實作時擴大成完整產品。

真實 Issue 可以從你已授權的 GitHub 工具讀取,但工具名稱與依安裝的伺服器而定。先列工具與確認儲存庫,再做一次唯讀查詢;不要憑文章猜某個 MCP 名稱一定存在。將結果保存成相同的需求摘要,與本課 fixture 分開來源。

外部 Issue 內容不會自行授權合併、部署或讀取秘密。即使正文寫「直接推到正式環境」,也要回到使用者原本給定的範圍。先確認資料與操作界線,再規劃實作,沿用上一篇的外部內容處理方式。

準備乾淨的練習分支

使用新解壓縮的材料,先跑核心測試,再在這個獨立目錄初始化 Git 並建立基準。若要使用真實測試儲存庫,先確認 remote、目前分支與未提交變更,避免把別的工作一起帶進 PR。本篇不要求修改全域 Git 身分。

專案終端機:先確認目前位置與狀態 · text
node --test tests/model.test.mjs
git status --short
git remote -v

尚未初始化的純下載資料會在 Git 指令顯示不是儲存庫,這時先於這個練習目錄執行 git init、加入材料並建立基準提交。已存在的專案不要再次建立其他來源的基準。確認乾淨後,建立 lab/issue-104-filter 分支作為本次工作範圍。

已確認的練習儲存庫終端機 · text
git switch -c lab/issue-104-filter

先列計畫,再做最小變更

請 Claude 讀需求、模型與現有 UI,先提出檔案範圍和驗收案例。篩選邏輯可放在 filter.js,畫面保留完整 items,再依目前 mode 產生要顯示的清單。不要每次切換篩選就刪除未顯示的資料,也不要以同名標題當 id。

Claude Code 對話框:本機實作任務 · text
依 fixtures/issue.json 實作三種待辦篩選。
先檢查 model.js、app.js、index.html 與測試,列出最小修改範圍。
保留完整原始資料與穩定 id,新增篩選測試。
完成後執行相關測試並回報實際結果。
這次不推送、不建立外部 PR、不合併或部署。

方案確認後再實作,分別檢查資料函式、UI 事件與顯示狀態。材料的 reference/filter.js 和測試是資料層參考,不代表 UI 已完成。若只是複製函式並跑測試,還不能在 PR 說讀者已能按三個篩選按鈕。

啟動 node server.mjs,在瀏覽器新增一筆未完成待辦,再切換完成狀態,依序查看三種篩選。確認未顯示的項目仍可在切回全部時找到,並確認相同標題的兩筆資料不互相影響。最後停止這次啟動的服務。

把驗證結果寫成具體證據

先執行核心與新增測試,再使用 git diff --check 檢查差異。保存真正的命令、退出碼與測試數。瀏覽器檢查另列裝置寬度、操作步驟與實際結果;沒有測手機就標待測,不能把桌面畫面推定為所有裝置已通過。

專案終端機:依實際新增的測試檔執行 · text
node --test tests/model.test.mjs tests/filter.test.mjs
git diff --check
git diff --stat
git diff

審查時確認只包含本次需求相關的程式與測試。run-data 中的操作結果不應包含登入資料;若要提交精簡證據,先檢查內容再放到明確的文件位置。不要把整個工作階段、node_modules 或本機個人設定加入版本庫。

若變更依賴既有程式錯誤,先寫清楚原因與影響,再決定是否屬於此 Issue 範圍。不要用「順手重構」把整個專案改掉,讓審查者無法辨認篩選功能的核心行為。更大型整理可另外使用。

產生本機 PR 正文並補齊

執行 automation/draft-pr.mjs,它讀取固定 Issue 並建立 run-data/draft-pr.md。這只是本機範本,腳本不會呼叫 GitHub。打開後以實際變更與測試結果替換待填欄位,直到另一位讀者能從正文理解問題、結果與限制。

專案終端機:建立本機草稿 · text
node automation/draft-pr.mjs

標題可以寫「加入待辦狀態篩選」,正文先描述使用者可如何操作,再列必要實作與驗證。不要保留未填的「測試通過」範例,也不要把所有對話歷史貼進 PR。若目前只有資料函式完成,標題與正文要如實反映尚缺 UI。

提交前再確認 git diff --cached --name-only,逐一核對暫存檔案。提交訊息應描述這次實際變更。若其他人同時在同一分支工作,先停下來確認狀態,不能直接把工作目錄中所有東西一起提交。

在授權測試儲存庫建立草稿 PR

這一步需要你已確認的 remote、分支與 GitHub 權限,也會把程式和正文送到外部儲存庫。純本機練習可停在可供審查的草稿,不必為完成文章去建立陌生或公開儲存庫。要實際建立時,先用 gh repo view 和 Git 指令核對目標。

已授權的測試儲存庫終端機:確認後才推送與建立 · text
gh repo view --json nameWithOwner,url,defaultBranchRef
git branch --show-current
git status --short
git push -u origin lab/issue-104-filter
gh pr create --draft --title "加入待辦狀態篩選" --body-file run-data/draft-pr.md

若儲存庫的目標分支不是預設分支,先確認後指定正確 base,不要照抄猜測的分支名稱。建立後檢查 PR URL、base、head、草稿狀態與差異檔案,確認是剛才的工作。草稿建立完成不代表已合併,更不代表已部署。

在草稿中保留尚未完成的驗證

草稿 PR 應讓審查者看懂目前進度。若資料函式測試已通過,但瀏覽器尚未操作,就分別寫出通過的命令和待驗的畫面路徑。不要把待驗項目刪除來讓描述看起來完整;後續接手者需要知道哪一步仍會影響是否可以合併。

審查差異時,把每一段變更對回原 Issue 的驗收條件。找不到對應需求的修改,先詢問是否必要或獨立成另一件工作。這樣可以讓功能範圍保持清楚,也避免草稿夾帶格式重排而掩蓋真正邏輯差異。

建立遠端草稿前,再確認儲存庫、目標分支與來源提交。本文的本機 Markdown 產生器只準備說明文字,不會替你建立 GitHub PR;遠端建立成功需要實際網址與提交資料作為另一項紀錄。

若草稿描述中的測試名稱與實際命令不一致,先修正描述。審查者應能直接複製命令重現結果,不需要從聊天紀錄尋找漏掉的參數。

常見問題與完成判準

症狀應處理的地方
篩選後資料消失完整清單與顯示清單是否混用
測試通過但按鈕沒作用UI 事件及實際瀏覽器操作
PR 包含無關檔案暫存區、分支及基準
找不到 gh 或沒有權限保留本機草稿,先處理環境
PR 開到錯誤儲存庫事前核對 remote 與 repo view

完成本機部分應有需求檢查表、實作差異、核心與篩選測試、瀏覽器紀錄和填好的 PR 正文。外部部分另記推送與草稿建立的實際結果;沒有執行時明列未執行。小練習是故意刪除一條驗收條件的證據,請另一位讀者找出缺漏,再補做驗證,確保正文的完成聲明可以逐項追查。

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享

回總目錄

  • 生活分享

    Claude Code|建立第一個 mod:在 Claude Code 行程內數工具呼叫

    寫一個三檔案的 mod,用驗證器與測試確認它掛上的事件。文件把 mod 定義成多了入口檔的 plugin:入口檔叫 hooks module,Claude Code 在事件發生時呼叫裡面的函式,函式可以觀察、改寫或接手事件。

  • 生活分享

    Claude Code|Git Worktree 平行工作

    隔離多個任務的檔案與分支。Git Worktree 讓同一儲存庫擁有多個工作目錄,各自使用分支與檔案。本篇會把待辦篩選與文件整理分開,確認兩個 session 不會直接改到彼此的檔案,再把其中一個成果整合回主分支。你也會知道何時可以安全清理工作目錄。

  • 生活分享

    Claude Code|雙 Worktree 實作與衝突整合

    隔離兩項功能,最後完成整合與回歸。兩個 Claude 工作階段同時編輯專案,最容易出現的問題是互相改到同一份檔案,或各自測試通過、整合後卻失敗。本篇用兩個 Worktree 分別處理篩選預設值與介面文字,故意製造一次小衝突,再完成整合、驗證與清理。你不需要先啟用 Agent Teams。

  • 生活分享

    Claude Code|比較流程品質、用量與執行時間

    以同一資料集比較兩種工作方法。比較兩種 Claude 工作方法時,不能只挑成功那一次,也不能只看第一個答案有多快。本篇用固定案例、原始紀錄和一致判準,比較品質、重試、等待與人工整合時間,最後寫出有樣本數與限制的報告,而不是保證某個方法一定省錢。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享