生活分享

Claude Code|期末實作:可維護的待辦專案工作流程

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

閱讀時間約 10 分鐘

LINE 分享
期末實作:可維護的待辦專案工作流程:文件、螢幕與完成記號的幾何插圖
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 先閱讀交付範圍
  2. 2. 第一階段:建立可重現起點
  3. 3. 第二階段:把需求變成驗收表
  4. 4. 第三階段:建立最小專案規則
  5. 5. 第四階段:先資料、再畫面
  6. 6. 第五階段:選用一個可重用流程
  7. 7. 第六階段:處理指定故障
  8. 8. 第七階段:桌面與手機驗收
  9. 9. 第八階段:從乾淨材料重現
  10. 10. 第九階段:整理可接手的交付包
  11. 11. 用接手測試檢查整套成果
  12. 12. 最後檢查與延伸練習

這篇期末實作要交付的是一個可以從乾淨材料啟動、能驗證功能、能處理故障、也能讓下一位維護者接手的待辦專案。你會挑選真正需要的規則、Skill、Hook 或 ,完成三種篩選,處理一次指定錯誤,再整理成果與尚未驗證的範圍。

先備包含、、、、、與。不必重新做完每篇,遇到缺少的概念再回頭補讀。

下載第 96 篇完整材料,將 starter 與 reference 分開。需要 Node.js 22、Git、編輯器與瀏覽器;使用 Claude 的步驟另需有效帳號。預估閱讀 30 分鐘、實作約三小時,實際時間依熟悉度調整。

先閱讀交付範圍 → 第一階段:建立可重現起點 → 第二階段:把需求變成驗收表
先閱讀交付範圍 → 第一階段:建立可重現起點 → 第二階段:把需求變成驗收表 · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

期末實作:可維護的待辦專案工作流程,以流程和文件圖形呈現教學重點。

先閱讀交付範圍

主功能是全部、未完成、已完成篩選,切換時保留完整資料,以 id 辨識項目,重新整理後依網站既有方式保持資料。不得新增帳號、資料庫、雲端同步或正式部署。這些排除項讓驗收可以集中在本次需求,不在最後突然變成另一個產品。

基本交付有需求單、規則、功能差異、測試、瀏覽器紀錄、故障恢復及 handoff.md。Skill、Hook、MCP、SDK 和 Teams 不是全部必選;每個加入的工具都要說明解決哪個問題、需要什麼前提、如何驗證及停止。沒有用途就不加入,避免維護者拿到一包無法解釋的設定。

本次不要求發布到正式網站,也不自動推送或合併。若你希望延伸成真正 PR,先完成本機可審查結果,再依核對儲存庫與授權。檔案完成、PR 建立、合併與部署是不同狀態,要分別記錄。

第一階段:建立可重現起點

先在 starter 跑四個模型測試,啟動網站並操作新增、切換及刪除。保存 Node 版本、材料版本、工作目錄與測試結果。確定基準能運作後,停止服務,再在這個獨立目錄建立 Git 基準提交與本次分支。

專案終端機:先確認材料 · text
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、空清單、未知篩選值與原始資料不變。這些不是任意增加功能,而是用來檢查主要需求在合理邊界下仍成立。

寫入 acceptance.md · markdown
# 待辦篩選驗收
- 全部:顯示所有待辦。
- 未完成:只顯示 completed=false。
- 已完成:只顯示 completed=true。
- 切換模式不刪除原始資料。
- 兩筆同名待辦依 id 獨立操作。
- 空清單有可理解狀態,不產生錯誤。
- 來源陣列不被篩選函式原地修改。
- 手機寬度可操作,頁面沒有整體水平溢出。

為每條條件指定證據:資料契約用測試,按鈕與畫面用瀏覽器,資料保留用切換前後和重新整理操作。不要把所有欄位都填成「Claude 說完成」。模型可以協助實作,但最後證據應對應實際檔案、命令或畫面。

也寫下未納入的行為,例如跨裝置資料同步和多人同時編輯。這不是降低品質,而是讓本次交付範圍可理解。如果實作中發現需求不清楚,先記錄決策,再繼續修改,避免不同階段各自採用不同假設。

第三階段:建立最小專案規則

閱讀現有 .claude/CLAUDE.md,保留真正需要的測試命令、資料契約與範圍限制。每條規則應有能被檢查的用途,例如以 id 操作、資料函式不改輸入、畫面文字使用安全的文字渲染。一次性的按鈕文案要求放到任務,不必寫成永久規則。

寫入 .claude/CLAUDE.md 的期末實作補充 · markdown
# 期末實作範圍
主要需求在 acceptance.md。
核心測試:node --test tests/model.test.mjs。
新增篩選測試放 tests/filter.test.mjs。
依穩定 id 操作待辦;篩選保留完整來源,不原地修改資料。
回報分開列出已執行與未執行的驗證。
不新增登入、雲端同步、正式部署或外部訊息發送。

另開 Claude 工作階段確認來源與實際讀取,再請它提出修改範圍。沒有有效登入時,你仍可手動完成檔案和測試,但不要把那份成果說成已驗證 Claude 遵循規則。交付報告可以同時保留材料完成與產品操作待測兩種狀態。

第四階段:先資料、再畫面

先建立 filter.js 與測試,確認三種 mode 的輸出及來源不變,再接到 UI。資料函式可參考 reference 中的實作,但先嘗試自己寫或讓 Claude 依需求完成,再比較差異。直接覆蓋完成版雖然能得到網站,卻無法展示你是否理解整合過程。

Claude Code 對話框:第一個受控工作切片 · text
依 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,讓它依固定欄位提出問題。先驗證與材料,再要求只讀審查。Skill 回報不是最終判決;每個採納發現仍由你重現,駁回的項目也要有理由,避免為了填表而捏造缺陷。

若你想練習自動化,可選 audit Hook 記錄必要事件,或針對指定 JSON 做格式化。先重播成功與故障事件,再安裝真實 Hook,保存前後設定與停用方式。不要把測試要求全部塞進 Stop 造成無法結束,參考處理遞迴。

專案終端機:選用 Hook 前的離線驗證 · text
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 比較反轉作為指定故障。在獨立副本或具回復點的分支注入,先於瀏覽器重現,再用的案例捕捉。保存修正前非零結果,做最小修改,最後以同一測試證明轉綠。

不要把測試 expected 改成故障結果,也不要 mock 掉真正的 toggleTodo。驗收需要相同輸入、相同斷言與實際程式變更。修正後再檢查未知 id、空清單與篩選中的切換,確認最小修正沒有破壞相鄰情境。

如果選用 MCP 或排程,也可另外加入一個故障:MCP 超時、JSON 輸出不完整或重複任務 id。但主功能故障仍要有自己的證據,不能只跑一個無關的 timeout 程式就宣稱網站除錯完成。

專案終端機:故障修正後的資料驗證 · text
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 階段接手,先只提供交接文件和專案,核對它是否能指出目前狀態,而不是重做已完成的功能。

寫入 delivery.md 的交付格式 · markdown
# 待辦篩選交付
版本與來源:
本次需求與排除範圍:
主要變更及理由:
資料測試命令與實際結果:
桌面及手機版面操作紀錄:
指定故障、修正與紅綠證據:
選用工具、用途與停止方式:
未測或受阻項目:
下一步及維護者需要的資訊:

報告中的每一個完成聲明都應能連到檔案、命令或畫面。沒有部署就寫未部署,沒有真正建立 PR 就寫本機草稿。不要把某個代理已完成、測試工作已結束或目錄已打包,當成使用者整個需求已驗收。

如果要比較效率,可使用記錄總時間、重試與人工核對。資料不足時保留未知,不為了呈現成果而計算沒有來源的節省百分比。交付最重要的是可用、可驗證和可維護。

用接手測試檢查整套成果

完成整合後,另外解壓縮一份交付包到空目錄,依 README 重新執行核心測試和網站啟動。這一步能找出只存在原工作目錄中的漏帶檔案,例如未提交的測試、全域安裝的套件,或寫死的絕對路徑。新的目錄不應需要作者先前對話中的隱含知識。

再請接手者從目錄找到需求、設定、測試與已知限制,逐一對回實際檔案。若找不到某一項,改善交付說明或補齊材料,而不是只增加「已完成」字樣。正式發布之前仍需要依網站流程審查與授權,這份本機成果是可供驗收的材料。

最後檢查與延伸練習

驗收項目合格證據
三種篩選與資料保留資料測試及瀏覽器完整操作
指定故障修正同一測試修正前失敗、修正後通過
工具選擇每項都有用途、前提、驗證及停止
乾淨重現新資料夾依 README 能啟動
交接新讀者能辨認版本、結果及下一步
狀態誠實未測、受阻、未發布明確列出

完成主線後,可選一個延伸:使用分開資料與畫面工作,或用建立只讀報告。每次只增加一個可驗證目標,保存新的前提與故障案例。當你能解釋每個工具為何存在、怎麼知道它完成,以及怎麼安全停止,就能把同樣流程帶到自己的真實專案。

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

LINE 分享

回總目錄

  • 生活分享

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

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

  • 生活分享

    Claude Code|Git Worktree 平行工作

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

資料來源

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

生活分享