生活分享
Claude Code|期末實作:可維護的待辦專案工作流程
整合規則、技能、工具及驗證,交付一次完整變更。這篇期末實作要交付的是一個可以從乾淨材料啟動、能驗證功能、能處理故障、也能讓下一位維護者接手的待辦專案。你會挑選真正需要的規則、Skill、Hook 或 MCP,完成三種篩選,處理一次指定錯誤,再整理成果與尚未驗證的範圍。
閱讀時間約 10 分鐘

進階 · CLI / Desktop
本篇目錄
這篇期末實作要交付的是一個可以從乾淨材料啟動、能驗證功能、能處理故障、也能讓下一位維護者接手的待辦專案。你會挑選真正需要的規則、Skill、Hook 或 MCP模型上下文協定(MCP)是什麼:連接工具與資料的共同介面MCP 是讓 AI 應用程式與外部工具、資料和提示範本交換資訊的開放協定,不是模型本身,也不保證接上就能完成任務。本文用查詢社區圖書室資料的例子,說明主機、用戶端、伺服器及工具、資源、提示的分工,並比較 MCP、A2A 與 Agent Skills。附連線驗證與權限檢查方法,幫你區分已設定、已連接、可呼叫與真正取得結果。閱讀全文,完成三種篩選,處理一次指定錯誤,再整理成果與尚未驗證的範圍。
先備包含待辦網站實作Claude Code|完整實作:待辦清單網站從需求到功能、測試與瀏覽器成果檢查。這篇把前面的小練習串成一個完整待辦網站:需求、介面、資料操作、篩選、本機儲存與測試。你可以直接下載材料開始,不必先完成前五十四篇。最後交付的不只是一張畫面,而是可啟動的檔案、可重跑的測試,以及清楚記錄的限制。閱讀全文、規則工作坊Claude Code|替真實專案設計 CLAUDE.md把模糊、過期或重複的規則改成可操作的專案說明。這一篇要做出的是一份能交給下一位同事使用的專案規則,而不是再認識一次 Markdown。你會拿到一份刻意過期的 CLAUDE.md,找出錯誤的測試命令與資料假設,重寫後用新的工作階段核對載入及實際行為。最後交付規則、取捨紀錄,以及三個前後比較案例。閱讀全文、Skill SOPClaude Code|把一套工作 SOP 做成可重用 Skill將程式碼審查流程做成有輸入、輸出及停止條件的技能。本篇把「檢查程式變更」做成可重複使用的 Skill。完成後,你可以指定一份 diff,得到有檔案位置、觸發條件與驗證狀態的審查報告。練習的核心是讓同一流程處理兩種不同變更,並且在沒有足夠證據時知道如何停下來。閱讀全文、Hook 事件Claude Code|讀懂 Hook 事件:輸入、輸出與退出碼建立可重播事件的本機測試工具。Hook 教學最容易卡住的地方,常常不是腳本語法,而是沒有分清楚誰送入事件、腳本讀到什麼,以及輸出會由誰解讀。本篇建立一個能重播事件的小實驗室,先用固定 JSON 驗證腳本,再接到 Claude 的實際事件。最後你會有正常、拒絕、輸入錯誤及診斷訊息四種可辨認結果。閱讀全文、自建 MCPClaude Code|建立自己的唯讀 MCP 工具讓 Claude 查詢本機練習待辦資料。本篇讓 Claude 讀取你自己提供的待辦資料。你會建立唯讀 MCP server,先用測試客戶端驗證工具清單與呼叫結果,再連進 Claude Code。完成不是畫面顯示 Connected,而是工具真的回傳指定資料、參數錯誤可以辨認,而且伺服器沒有修改原始檔案。閱讀全文、紅綠除錯Claude Code|真正走完一次重現、失敗測試與修正定位跨資料層及介面層的待辦狀態錯誤。點了第一筆待辦,卻改到另一筆,這種問題不能只靠一句「請修好」驗證。本篇從瀏覽器重現開始,寫出修正前會失敗的行為測試,再讓 Claude 做最小修改。最後保留同一個測試由紅轉綠的紀錄,以及相鄰情境沒有退步的證據。閱讀全文與JSON 流程Claude Code|把 claude -p 接進有驗證的 JSON 流程處理合法結果、錯誤、逾時與不完整輸出。這次輸出只要兩個欄位:summary 是非空的繁體中文摘要,taskIds 是不重複的待辦識別碼陣列。先把契約寫清楚,才能決定什麼資料不應往下傳。如果只是要求「回傳 JSON」,模型即使回傳一個空物件,語法上仍是合法 JSON,卻不能完成工作。閱讀全文。不必重新做完每篇,遇到缺少的概念再回頭補讀。
下載第 96 篇完整材料,將 starter 與 reference 分開。需要 Node.js 22、Git、編輯器與瀏覽器;使用 Claude 的步驟另需有效帳號。預估閱讀 30 分鐘、實作約三小時,實際時間依熟悉度調整。
閱讀完整文字說明
期末實作:可維護的待辦專案工作流程,以流程和文件圖形呈現教學重點。
先閱讀交付範圍
主功能是全部、未完成、已完成篩選,切換時保留完整資料,以 id 辨識項目,重新整理後依網站既有方式保持資料。不得新增帳號、資料庫、雲端同步或正式部署。這些排除項讓驗收可以集中在本次需求,不在最後突然變成另一個產品。
基本交付有需求單、規則、功能差異、測試、瀏覽器紀錄、故障恢復及 handoff.md。Skill、Hook、MCP、SDK 和 Teams 不是全部必選;每個加入的工具都要說明解決哪個問題、需要什麼前提、如何驗證及停止。沒有用途就不加入,避免維護者拿到一包無法解釋的設定。
本次不要求發布到正式網站,也不自動推送或合併。若你希望延伸成真正 PR,先完成本機可審查結果,再依PR 草稿流程Claude Code|從 Issue 到變更草稿:串起工具與程式碼完成需求讀取、計畫、測試與 PR 說明稿。這一篇把一則待辦篩選 Issue 走到可供審查的變更與 PR 草稿:確認需求、建立分支、實作、測試、檢查差異,最後整理標題和正文。材料先在本機完成,不需要先取得外部服務權限;真正建立 GitHub 草稿 PR 則放在讀者已授權的測試儲存庫中執行。閱讀全文核對儲存庫與授權。檔案完成、PR 建立、合併與部署是不同狀態,要分別記錄。
第一階段:建立可重現起點
先在 starter 跑四個模型測試,啟動網站並操作新增、切換及刪除。保存 Node 版本、材料版本、工作目錄與測試結果。確定基準能運作後,停止服務,再在這個獨立目錄建立 Git 基準提交與本次分支。
node --version
node --test tests/model.test.mjs
node server.mjs
node server.mjs 會持續運作,瀏覽器檢查後回終端機按 Ctrl+C,不要把它當成已結束的命令串繼續貼 Git 操作。若某個埠已被占用,先確認是哪個服務,不直接終止所有 Node。可以使用新的埠並記錄,讓後面的驗證對得上。
下載材料包含多組共用工具,初期只需要根目錄待辦網站。需要 MCP 測試時才執行 npm ci --ignore-scripts;SDK 有自己的安裝位置。不要一開始就啟用全部 Hook 或連上所有外部服務,讓簡單基準受到不必要的環境影響。
第二階段:把需求變成驗收表
開啟 fixtures/issue.json,將四個驗收條件轉成可操作案例。再補上同名不同 id、空清單、未知篩選值與原始資料不變。這些不是任意增加功能,而是用來檢查主要需求在合理邊界下仍成立。
# 待辦篩選驗收
- 全部:顯示所有待辦。
- 未完成:只顯示 completed=false。
- 已完成:只顯示 completed=true。
- 切換模式不刪除原始資料。
- 兩筆同名待辦依 id 獨立操作。
- 空清單有可理解狀態,不產生錯誤。
- 來源陣列不被篩選函式原地修改。
- 手機寬度可操作,頁面沒有整體水平溢出。
為每條條件指定證據:資料契約用測試,按鈕與畫面用瀏覽器,資料保留用切換前後和重新整理操作。不要把所有欄位都填成「Claude 說完成」。模型可以協助實作,但最後證據應對應實際檔案、命令或畫面。
也寫下未納入的行為,例如跨裝置資料同步和多人同時編輯。這不是降低品質,而是讓本次交付範圍可理解。如果實作中發現需求不清楚,先記錄決策,再繼續修改,避免不同階段各自採用不同假設。
第三階段:建立最小專案規則
閱讀現有 .claude/CLAUDE.md,保留真正需要的測試命令、資料契約與範圍限制。每條規則應有能被檢查的用途,例如以 id 操作、資料函式不改輸入、畫面文字使用安全的文字渲染。一次性的按鈕文案要求放到任務,不必寫成永久規則。
# 期末實作範圍
主要需求在 acceptance.md。
核心測試:node --test tests/model.test.mjs。
新增篩選測試放 tests/filter.test.mjs。
依穩定 id 操作待辦;篩選保留完整來源,不原地修改資料。
回報分開列出已執行與未執行的驗證。
不新增登入、雲端同步、正式部署或外部訊息發送。
另開 Claude 工作階段確認來源與實際讀取,再請它提出修改範圍。沒有有效登入時,你仍可手動完成檔案和測試,但不要把那份成果說成已驗證 Claude 遵循規則。交付報告可以同時保留材料完成與產品操作待測兩種狀態。
第四階段:先資料、再畫面
先建立 filter.js 與測試,確認三種 mode 的輸出及來源不變,再接到 UI。資料函式可參考 reference 中的實作,但先嘗試自己寫或讓 Claude 依需求完成,再比較差異。直接覆蓋完成版雖然能得到網站,卻無法展示你是否理解整合過程。
依 acceptance.md 先完成 filter.js 與 tests/filter.test.mjs。
支援 all、active、completed;未知 mode 明確處理,保留來源資料。
只完成資料邏輯並執行測試,先不修改 UI。
回報檔案、實際命令、結果與仍未完成的驗收項目。
資料部分通過後,讓 app.js 保存完整 items 和目前 mode,渲染時才取得顯示清單。index.html 提供有可理解名稱的控制,style.css 讓選取狀態及手機操作清楚。不要把 filter 後的結果直接覆寫成完整資料,否則切回全部時會遺失項目。
接 UI 後重新執行測試,再進瀏覽器操作。資料函式通過不保證匯入、事件、儲存與畫面都正確。每個階段都保存一個小差異與結果,發生失敗時才能定位是資料邏輯、畫面串接或環境問題。
第五階段:選用一個可重用流程
如果你經常重複審查差異,可安裝 review-change Skill,讓它依固定欄位提出問題。先驗證參數模型參數(Model Parameters)是什麼模型參數是訓練時調整、用來把輸入轉成輸出的數值,例如權重與偏差。本文用簡單算式示例說明參數如何影響預測,區分模型參數、訓練超參數、提示詞與生成設定,並解釋參數量、數值精度和啟用參數為何是不同指標。讀完能更準確閱讀模型規格,理解參數增加不等於知識逐條增加,也不代表每次聊天都在重新訓練模型。閱讀全文與材料,再要求只讀審查。Skill 回報不是最終判決;每個採納發現仍由你重現,駁回的項目也要有理由,避免為了填表而捏造缺陷。
若你想練習自動化,可選 audit Hook 記錄必要事件,或針對指定 JSON 做格式化。先重播成功與故障事件,再安裝真實 Hook,保存前後設定與停用方式。不要把測試要求全部塞進 Stop 造成無法結束,參考有限品質檢查Claude Code|建立可停止的品質檢查 Hook讓完成檢查能指出失敗並有清楚的退出機制。測試沒有通過時,Claude 應知道工作還有問題;但如果 Hook 每次都阻止結束,又可能陷入不停重試。本篇建立有次數邊界的 Stop 檢查,第一次失敗回報原因,重複觸發時停止遞迴,並把尚未完成的結果清楚交回讀者。閱讀全文處理遞迴。
node hooks/replay.mjs audit fixtures/post-edit.json
node hooks/replay.mjs protect fixtures/pre-write.json
node --test tests/hooks.test.mjs
也可選擇唯讀 MCP 查詢固定待辦材料,先以正式客戶端完成列工具與查詢,再接 Claude。若這次功能完全不需要跨工具資料,保留 MCP 為選修即可。不要為了「用到 MCP」把本來簡單的讀檔改成難以維護的服務。
在 tools-choice.md 為每項工具寫四欄:用途、輸入、成功證據、停止方式。未使用工具寫明原因,不需要把所有功能都勾選。這份表應讓下一位維護者知道哪些設定是必要的,哪些只是可刪除的練習材料。
第六階段:處理指定故障
選擇 toggle id 比較反轉作為指定故障。在獨立副本或具回復點的分支注入,先於瀏覽器重現,再用紅綠測試Claude Code|真正走完一次重現、失敗測試與修正定位跨資料層及介面層的待辦狀態錯誤。點了第一筆待辦,卻改到另一筆,這種問題不能只靠一句「請修好」驗證。本篇從瀏覽器重現開始,寫出修正前會失敗的行為測試,再讓 Claude 做最小修改。最後保留同一個測試由紅轉綠的紀錄,以及相鄰情境沒有退步的證據。閱讀全文的案例捕捉。保存修正前非零結果,做最小修改,最後以同一測試證明轉綠。
不要把測試 expected 改成故障結果,也不要 mock 掉真正的 toggleTodo。驗收需要相同輸入、相同斷言與實際程式變更。修正後再檢查未知 id、空清單與篩選中的切換,確認最小修正沒有破壞相鄰情境。
如果選用 MCP 或排程,也可另外加入一個故障:MCP 超時、JSON 輸出不完整或重複任務 id。但主功能故障仍要有自己的證據,不能只跑一個無關的 timeout 程式就宣稱網站除錯完成。
node --test tests/model.test.mjs tests/filter.test.mjs
git diff --check
保留失敗原因、修正檔案、測試結果與尚未處理事項。若功能仍有未解錯誤,交付狀態就維持未完成,不因時間到了或模型回覆很完整而改成成功。這份紀錄也能用來檢查工具是否誠實區分推論與實測。
第七階段:桌面與手機驗收
在桌面瀏覽器新增兩筆同名項目和一筆不同標題,將其中一筆標為完成,依序切換三種模式,再刪除一筆並切回全部。確認資料筆數與狀態都符合預期,重新整理後仍能使用網站既有保存行為。
在三百六十與三百九十像素寬度重做主要操作,檢查控制名稱、點擊區域、選取狀態與水平溢出。可先用瀏覽器響應式模式驗證版面,再於實際手機補做觸控與系統瀏覽器差異;兩種驗證不要混稱為真實手機已測。
輸入含角括號的標題,確認它以文字顯示而不被解讀成 HTML。再使用空白與過長文字測試既有資料限制,觀察錯誤回饋是否清楚。不要使用會攻擊外部服務的內容,本機假資料已足以驗證文字渲染與輸入邊界。
若選用了持久化,也測一次損壞的課程儲存資料,確認網站能給出合理結果或恢復路徑。只清除這個本機來源的練習資料,不動其他網站。完成後停止服務,保留必要畫面與操作紀錄。
第八階段:從乾淨材料重現
把已完成檔案整理成新的可審查版本,另開乾淨資料夾取得它,照 README 從頭啟動。不要依賴原目錄的 node_modules、未提交檔或個人設定。這一輪最容易找出漏掉的腳本、相對路徑與沒有寫進文件的手動步驟。
核心網站仍應不需要資料庫。選用 MCP 或 SDK 時,分別列出安裝命令與有效認證前提,不把自己的登入檔打包。只包含專案需要的內容,排除 run-data 中的私人操作紀錄、權杖與工作階段資料;需要交付證據時先做範圍檢查。
reference 是參考成果,不是所有產品操作的證明。它提供功能與設定的對照,不能替你完成 Claude 登入、手機接續、GitHub run 或外部 OAuth。重新開始驗證時,仍以你自己的實際輸出為準,不能直接複製作者的完成欄位。
第九階段:整理可接手的交付包
建立 handoff.md,記錄需求、版本、修改檔案、決策、測試與下一步。將已完成、受阻與未測分開。若讓新的 Claude 階段接手,先只提供交接文件和專案,核對它是否能指出目前狀態,而不是重做已完成的功能。
# 待辦篩選交付
版本與來源:
本次需求與排除範圍:
主要變更及理由:
資料測試命令與實際結果:
桌面及手機版面操作紀錄:
指定故障、修正與紅綠證據:
選用工具、用途與停止方式:
未測或受阻項目:
下一步及維護者需要的資訊:
報告中的每一個完成聲明都應能連到檔案、命令或畫面。沒有部署就寫未部署,沒有真正建立 PR 就寫本機草稿。不要把某個代理已完成、測試工作已結束或目錄已打包,當成使用者整個需求已驗收。
如果要比較效率,可使用品質與成本評估Claude Code|比較流程品質、用量與執行時間以同一資料集比較兩種工作方法。比較兩種 Claude 工作方法時,不能只挑成功那一次,也不能只看第一個答案有多快。本篇用固定案例、原始紀錄和一致判準,比較品質、重試、等待與人工整合時間,最後寫出有樣本數與限制的報告,而不是保證某個方法一定省錢。閱讀全文記錄總時間、重試與人工核對。資料不足時保留未知,不為了呈現成果而計算沒有來源的節省百分比。交付最重要的是可用、可驗證和可維護。
用接手測試檢查整套成果
完成整合後,另外解壓縮一份交付包到空目錄,依 README 重新執行核心測試和網站啟動。這一步能找出只存在原工作目錄中的漏帶檔案,例如未提交的測試、全域安裝的套件,或寫死的絕對路徑。新的目錄不應需要作者先前對話中的隱含知識。
再請接手者從目錄找到需求、設定、測試與已知限制,逐一對回實際檔案。若找不到某一項,改善交付說明或補齊材料,而不是只增加「已完成」字樣。正式發布之前仍需要依網站流程審查與授權,這份本機成果是可供驗收的材料。
最後檢查與延伸練習
| 驗收項目 | 合格證據 |
|---|---|
| 三種篩選與資料保留 | 資料測試及瀏覽器完整操作 |
| 指定故障修正 | 同一測試修正前失敗、修正後通過 |
| 工具選擇 | 每項都有用途、前提、驗證及停止 |
| 乾淨重現 | 新資料夾依 README 能啟動 |
| 交接 | 新讀者能辨認版本、結果及下一步 |
| 狀態誠實 | 未測、受阻、未發布明確列出 |
完成主線後,可選一個延伸:使用雙 WorktreeClaude Code|雙 Worktree 實作與衝突整合隔離兩項功能,最後完成整合與回歸。兩個 Claude 工作階段同時編輯專案,最容易出現的問題是互相改到同一份檔案,或各自測試通過、整合後卻失敗。本篇用兩個 Worktree 分別處理篩選預設值與介面文字,故意製造一次小衝突,再完成整合、驗證與清理。你不需要先啟用 Agent Teams。閱讀全文分開資料與畫面工作,或用Agent SDKClaude Code|Agent SDK:保存狀態、取消與重新接續建立可中斷且可診斷的最小代理程式。把 Claude 放進程式後,除了收到回答,還要知道程序何時開始、是否真的完成、取消後留下什麼,以及下次能否接續。本篇使用官方 TypeScript Agent SDK,建立帶狀態檔、事件紀錄與停止上限的最小 runner,只處理一個合成標記,不連外部業務系統。閱讀全文建立只讀報告。每次只增加一個可驗證目標,保存新的前提與故障案例。當你能解釋每個工具為何存在、怎麼知道它完成,以及怎麼安全停止,就能把同樣流程帶到自己的真實專案。
回 Claude Code 教學總目錄Claude Code 完整教學目錄:從入門到自動化依平台、程度與功能找到需要的教學,從 96 篇文章與共用練習專案逐步完成操作。這個教學中心把 Claude Code 分成 96 個可以獨立閱讀的小題目,從桌面、CLI、網頁與手機開始,再學 MD 規則、常用指令、Skills、MCP 與自動化。你可以依推薦路線循序學習,也可以直接搜尋正在遇到的功能、命令或檔名。目錄依目前公開狀態顯示可閱讀文章。閱讀全文
覺得這篇整理實用嗎?分享給需要的朋友
同主題延伸閱讀
生活分享
Claude Code|建立第一個 mod:在 Claude Code 行程內數工具呼叫
寫一個三檔案的 mod,用驗證器與測試確認它掛上的事件。文件把 mod 定義成多了入口檔的 plugin:入口檔叫 hooks module,Claude Code 在事件發生時呼叫裡面的函式,函式可以觀察、改寫或接手事件。
生活分享
Claude Code|Git Worktree 平行工作
隔離多個任務的檔案與分支。Git Worktree 讓同一儲存庫擁有多個工作目錄,各自使用分支與檔案。本篇會把待辦篩選與文件整理分開,確認兩個 session 不會直接改到彼此的檔案,再把其中一個成果整合回主分支。你也會知道何時可以安全清理工作目錄。
引用本文的文章
資料來源
- Run Claude Code programmatically查證日期:
- Claude Code GitHub Actions查證日期:
- Run prompts on a schedule查證日期:
- Agent SDK overview查證日期:
本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。