【2026 最新】Sphinx 教學：Claude Code 寫完後，用三道情境題檢查自己是否看懂

Claude Code 把功能寫好了，畫面也能動；同事卻問：「如果操作成功後斷線，再試一次會怎樣？」你發現自己還得回去問 AI。這篇 Sphinx 教學，要幫你把「程式交出來」與「自己能預測行為」分開檢查。

這篇專為剛開始接觸 AI 寫程式、願意逐步操作終端機的讀者寫。先懂它在問什麼，再用一個不含私密資料的練習專案設定檢查點，最後走過重複工作、逾時與快取三道題。你不必背術語；重點是能用自己的話說出原因。

操作基準為 2026 年 10 月 20 日查閱的 Sphinx 0.1.11，原始碼固定在 824e448e。本次執行了隔離環境的 Hooks、設定與卸載相關測試；下文三題則是本文設計的練習示例，沒有冒充 Sphinx 實際生成或真人作答紀錄。

先說結論：Sphinx＝變更檢查點＋本人預測＋換題再答

Sphinx 像交車前的口試：車子能開是一件事，你能否說出煞車失靈時會發生什麼，是另一件事。它在符合政策的 Git 操作前，讓另一個審查模型讀取變更，再請你預測行為；答錯後解釋，換一個情境繼續練。

• 先在專用測試帳號或可還原的虛擬機試裝；只換一個 Repo，仍會碰到全域 Git 設定。
• 先寫預測，再讀程式、補理由；隔天再改一個條件，觀察自己是否仍能解釋。
• 把通過、跳過、暫停與題目有爭議分開記錄。通過口試並不等於程式已完成安全審查。

一、Sphinx 在檢查誰？先分清 Git、Hooks 與審查模型

Git 是保存程式版本的工具；Repo 是專案的版本資料夾；git push 則把本機提交送往另一個儲存庫。Hook（掛鉤）像出貨口的門鈴：某個動作發生時，自動叫起指定程式。Git 官方 Hooks 文件列出 pre-push 等時點。

Sphinx 把「人能否說明這份變更」放進這個時點。官方架構說明描述獨立的審查流程：它讀取 Git 裡的證據，而非沿用寫碼時那串對話。這能少帶一部分先入為主的脈絡，卻不代表兩個模型就會自然互相糾錯。

Claude Code 也有自己的事件 Hooks。Anthropic 官方文件把它們定義為工作階段或工具呼叫時執行的處理器。Git Hook 負責攔住指定 Git 動作；Agent 整合則協助等待與呈現備用問答。兩者名稱相似，工作層次不同。想先練基礎，可接著看Claude Code Hooks 三道閘門教學。

它適合你已經有一份能讀的小變更，卻不確定自己是否看懂失敗路徑。若問題是 PR 一次太大，先用Cognitive Debt 與理解預算縮小範圍；若問題是測試會不會漏掉錯誤，則另看Coding Agent 測試驗證。這篇要練的是人對行為的預測。

二、Sphinx 教學第一步：先盤點，再準備可退出的練習環境

①「看清門鈴接在哪」：安裝前留下設定收據

擔心把原有自動檢查蓋掉？先查看目前有效設定與來源，在打算練習的 Repo 執行：

node --version
git --version
git config --show-origin --get-all core.hooksPath
git config --global --get-all core.hooksPath
git config --local --get-all core.hooksPath
git rev-parse --git-path hooks

某個查詢沒有輸出且回傳狀態 1，可能只是該層尚未設定。把結果存成私人筆記，並備份實際使用的 Hooks 目錄與 Agent 設定；不要把備份推進專案。依Git 的 core.hooksPath 說明，它會改變 Git 尋找 Hooks 的位置，路徑也可能是相對路徑。

這版要求 Node.js 22.19 以上、Git，以及 macOS、Linux 或 WSL。sphinx install 會設定全域 Hooks，並非只安裝到目前 Repo。官方表示既有 Hooks 先跑，原本拒絕操作的結果仍保留；Repo 自訂 core.hooksPath 時，需另做相容整合。因此首次練習選專用帳號或可還原 VM，比在日常工作帳號直接試裝更容易收拾。

②「只拿公開練習本」：先隔開資料與傳送對象

Sphinx 的審查供應商會收到變更程式、相關檔案、你的答案與專案脈絡。.sphinxignore 是依路徑排除；內建也排除常見環境檔、私鑰和憑證檔，但普通程式檔裡貼進去的秘密，仍可能隨內容送出。先用自己的無敏感練習 Repo，再按官方排除規則補上客戶匯出、內部設定等路徑。

在練習環境、安裝 Sphinx 前，先建立一個有基線提交的專案，確認原本的測試和推送能成功。可使用你自己建立的本機 bare Repo 作遠端，避免把練習推到團隊正式儲存庫；模型資料傳送仍是另一條路，不能因遠端在本機就忽略。

三、Sphinx 教學第二步：用四個設定接好檢查點

③「先定出題員與用量」：安裝後立即設上限

已具備可用的 Claude Code CLI 登入與額度時，可在測試環境依序執行；沒有可用帳號時，先完成本文紙上練習，別把下載套件誤當成已取得模型服務：

npm install -g sphinx-understand@0.1.11
sphinx install --yes --preset claude-economy --agents claude --no-launch --max-model-calls 30
sphinx config
sphinx config --max-model-calls 30

這裡固定的是套件版本，並以 claude-economy 選審查路線；30 是本文採用的單次檢查請求上限示例，不是建議每次一定花完。官方用量文件明列預設沒有模型呼叫次數上限，且計數包含調查、評分與失敗請求。次數上限也不是金額上限。

Sphinx 的 Claude 路線預設使用已登入方案的額度；--cli-billing api 則是另一種計費選擇，本練習不啟用。haiku 是模型別名，實際解析會受版本與供應商影響，請對照Claude Code 模型設定核對；這裡不預填單題價格。更換審查路線後，舊的準備題與通過紀錄也會失去原來的適用條件。

④「指定哪個出貨口」：Repo 政策、忽略與脈絡

回到練習 Repo，先確定你要推送的目的分支名稱；下面用 sphinx-lab，而非團隊正式主分支：

sphinx init --yes --branches sphinx-lab --events pre-push --level standard
sphinx doctor
sphinx status

初始化會保留既有設定，不覆寫已存在的三個檔案。打開 .sphinxconfig，把練習政策整理成以下內容；backgroundPreparation: false 讓這個 Repo 不在提交後預先叫模型，github.status: false 則關閉這次練習的 GitHub 狀態回報：

{
  "version": 1,
  "events": ["pre-push"],
  "branches": ["sphinx-lab"],
  "remotes": ["origin"],
  "level": "standard",
  "distance": "mixed",
  "backgroundPreparation": false,
  "github": {"status": false, "comment": false, "answers": false}
}

再編輯 .sphinxignore，加入練習以外的敏感路徑；在 .sphinxcontext.md 寫「這是本機工作佇列練習，請聚焦重複執行、逾時與資料一致性」。後者預設是個人檔案、會被本機 Git 排除；若真要團隊共享，官方另有強制加入版本控制的做法。別把密碼或個資寫進脈絡。

重新開一個 Claude Code 工作階段，在 /mcp 確認 sphinx 連線。若 sphinx doctor 指出 Repo 有自己的 Hooks 目錄，再於該 Repo 執行 sphinx install --repo；它是相容步驟，不能用來假裝全域安裝從未發生。相關操作見官方整合文件。

把一個小型行為變更提交後，以 git push origin sphinx-lab 觸發。比對的是推送目的分支；若目標是 PR 前檢查，只有 main 的政策可能太晚，應依團隊工作分支設規則。官方提供 ["*"] 檢查所有分支的選項，但那會擴大觸發範圍，第一次先守住練習分支。

檢查點應印出本機問答位址，並讓 Git 等待。若出現零題通過，先看是否只有文件、微小或被排除的變更；標準深度的「最多三題」是大型變更的上限，並非每次保證出三題。不要為了湊題目擴大修改。

四、三道情境題：先寫錯在哪，再讀碼，最後換條件

下面是本文設計的教學對話示例，不是模型實際輸出。每題都先固定假設，走「原預測→找證據→修正→遷移題」；遷移題就是換一個條件，看你是否仍能推理。你可以把自己的答案記在本機筆記，別請 coding agent 代填。

第一題「重複工作」：存好結果，是否就等於領件完成？

題目：假設工作佇列在收到確認前可能重送。Worker 先把訂單記入資料庫，再回覆佇列「完成」；若在兩者之間當機，重新領到同一工作後又新增一筆，結果會怎樣？

常見誤答：「已經存好，應該不會再做。」先把這句留下，再讀實作：哪一行提交資料？哪一行確認領件？收到相同工作 ID 時，有沒有同一筆交易內的唯一性檢查？在題目給定的實作中，資料落盤不會自動替佇列確認，所以重送後可能新增第二筆。

修正答案：「可能重複，因為提交與確認之間有空窗；需要查重與寫入如何一起保護。」這裡的關鍵是冪等性（同一操作重送，仍維持約定的效果），不只是多一個叫 done 的變數。

換題：如果改成先確認領件，再存資料，當機位置相同會怎樣？這次可能變成工作遺失：佇列認為完成，資料卻沒存下來。兩個順序各有失敗窗；請在你自己的程式上指出交易、唯一鍵或補償流程的具體位置，不能只背「加 retry」。這題以官方工作佇列例題的因果問題作起點，延伸成順序變更練習。

第二題「逾時」：沒收到回覆，是否代表對方沒做？

題目：假設付款服務已完成扣款，但回覆在網路上遺失；呼叫端逾時後，使用一個全新的操作識別碼重送。服務只按識別碼防重，第二次會怎樣？

常見誤答：「Timeout 就是失敗，再送一次即可。」讀碼時追三處：識別碼在哪裡建立、重試是否沿用同一碼、服務端把它保留多久。依本題假設，新碼被當成新操作，便可能再扣一次；逾時只告訴呼叫端沒有如期取得結果。

修正答案：「結果未知，先查原操作狀態；若契約允許重試，要維持同一業務操作的識別。」換題：假如兩次請求用同一碼，但防重紀錄已過保存期限，還能沿用剛才的結論嗎？不能直接沿用，得回到服務端的保存期限與狀態查詢契約。這是虛構契約練習，實際金流修改應使用供應商測試環境，別用真實扣款驗答案。

第三題「快取失效」：刪了舊資料，為何又讀到舊值？

題目：假設先寫資料庫、再刪快取。讀取者 A 在寫入前讀到舊資料，接著暫停；寫入者 B 更新並刪掉快取後，A 才把手上的舊值放回去。下一位讀者會看到什麼？

常見誤答：「B 刪過了，所以一定是新值。」把時間線排成 A 讀舊值→B 更新→B 刪快取→A 回填，就能看到舊值重新出現。讀碼時找回填條件、版本比較與失效策略，而不是只找 delete。

修正答案：「仍可能讀到舊值；刪除動作早於舊讀取的回填。」換題：若系統讓快取只接受不小於目前版本號的寫入，還缺哪個條件？你要確認比較與更新是否原子執行，以及失效時是否仍保留最新版本界線；若連版本界線一起刪掉，舊值未必會被擋住。不要把一句『加版本號』當作完整解法。

五、把口試變成學習紀錄：今天答得出，隔天還會嗎？

擔心只是把模型剛講過的話背下來？把首次答案與看過提示後的答案分開。每題留六欄：提交 ID、題目假設、首次預測、查到的程式位置、修正後因果鏈、隔天新題結果。三題是本文的練習配置，並非 Sphinx 固定題數。

隔天先不看昨天的解釋，改一個條件再作答：把重送改成兩個 Worker 同時做；把逾時改成服務已回成功、呼叫端卻在保存回覆前當機；把快取刪除改成延遲訊息。先寫預測與一個能推翻自己的觀察，再讀程式核對。這是自我檢查方法，不把單次進步換算成學習成效百分比。

模型判錯怎麼辦？先指出題目前提與程式證據的衝突。用 Dispute question 說明哪個檔案、條件或時間順序不符；需要學概念時用 Explain this。作者的開發評估保留了充分答案被拒絕等案例，因此不適合把分數當成對人能力的定論。若題目要求程式根本沒承諾的行為，也應提出爭議，而非照猜評分者想聽的詞。

本次 AlphaLab 跑過固定提交的 10 項相關測試，涵蓋原 Hooks 串接、卸載保留後續編輯、請求上限與忽略規則。它們使用暫存資料與測試替身；這證明的是那些程式路徑通過測試，沒有量到真人學習進步或審查模型的評分準確率。

六、卡住與退出：四種狀態不要混記

• 通過：符合該次檢查的條件；程式、目的地或政策改變會影響原紀錄的適用性。
• 暫停：保存進度並停止推送，稍後再繼續；不是已完成發布。
• 跳過：讓操作繼續，留下跳過紀錄；sphinx status 可查看近期狀態。
• 等待：正常問答時 Git 仍在跑，不要同時啟動第二份推送。

官方文件記載等待最多可達 25 分鐘，Agent 或遠端連線可能更早逾時。若 Git 已退出，完成檢查後再重跑一次；仍在等就先完成同一份問答。sphinx check 可在終端機作答。sphinx yolo 是關閉／恢復檢查的切換，且 Repo 與全域範圍不同；第一次先用介面的單次跳過，觀察紀錄，不必用全域開關測試。

這是練習工具，官方明列本機使用者與 Agent 都能繞過 Hooks；通過無法證明誰寫的程式或是否獨立理解。程式測試、權限與合併政策仍各自驗收。想把這些層次接起來，可讀AI Agent Harness 原理。

結束練習時，依官方卸載順序先移除明確設定過的 Repo 整合，再移除全域整合，最後移除套件：

sphinx uninstall --repo
sphinx uninstall
npm uninstall -g sphinx-understand

第一行只在曾執行 install --repo 的 Repo 使用；若有多個，逐一處理。卸載會在仍由 Sphinx 管理的條件下還原原設定，保留後來的修改並提出警告。再重跑安裝前的 git config 查詢，與私人備份逐項比對。~/.config/sphinx 的設定、憑證和評估狀態仍留著；若要清除，先確認路徑、保留需要的紀錄，再由檔案管理器處理該資料夾。

Sphinx 教學 FAQ：八個直接答案

1. 完全不會寫程式，也能開始嗎？

可以先練預測。先把三題的先後順序畫在紙上；要安裝與判讀實際程式，再找一個自己能讀完的小專案，不要從公司的金流主線開始。

2. 一定每次會問三題嗎？

不一定。題數受變更規模與深度影響，且可能零題；本篇三題是學習配置。

3. 測試全綠，是否表示人也看懂？

兩項分開記。測試觀察指定行為；理解檢查要求你先預測、再指出因果證據。

4. 可以請 Claude Code 幫我作答嗎？

練習時自己回答。可以請它定位程式、輔助閱讀，但讓它代填會失去觀察本人理解的意義。

5. 只裝在練習 Repo，就不影響其他專案？

不是。標準 install 設定全域 Hooks；Repo 的 init 主要建立政策與排除檔。先用專用測試帳號或可還原 VM。

6. 30 次請求代表固定費用嗎？

不是。模型路線、輸入輸出與計費方式都會影響用量；paid API 應另外設供應商側支出限制。

7. 跳過後可寫成已通過嗎？

不可以混記。跳過是讓操作繼續，官方把它與通過分開；先確認原因與 status 紀錄。

8. 模型不接受我的答案，要一直改到它高興？

先核對證據。有錯誤前提或模糊要求就提出爭議，保留程式位置；不要以迎合措辭代替因果推理。

給新手的三個重點

• 先查 Hooks 與資料去向，再安裝；練習 Repo 不會自動隔離全域設定。
• 每題寫「會怎樣＋為什麼＋哪段程式能證明」，錯了就改因果鏈。
• 隔天換條件，並分開記通過、跳過與爭議；別只累積綠色勾勾。