---
site: "zyx.tw"
title: "地圖"
description: "Loki (詹詠翔), CS grad student at NYCU WinLab. Side projects, lab work and GitHub activity."
url: "https://www.zyx.tw/map"
---

# 地圖

沒有連結的點還在規劃中，尚未寫成。

## [基礎](https://www.zyx.tw/map/basics)

先學會把整個任務交給 Claude Code。

- [把完整任務交給 Claude Code，以實際操作結果判斷完成](https://www.zyx.tw/map/basics/what-claude-code-is.md)（觀念，L1）：交代目標與界線，讓 Claude Code 找檔、修改並驗證。
- [我從家目錄啟動 Claude Code，讓跨專案工作在同一個範圍內、共用同一份記憶](https://www.zyx.tw/map/basics/start-from-home.md)（經驗，L2）：跨專案操作方便，但專案規則與記憶整理要自己補上。
- [先確認任務缺什麼，再選擇擴充方式](https://www.zyx.tw/map/basics/four-ways-to-extend.md)（觀念，L1）：從連線、做法、安裝與畫面，判斷任務需要哪種擴充。
- [MCP 把服務操作包成 agent 能呼叫的工具](https://www.zyx.tw/map/basics/mcp-wraps-a-service.md)（觀念，L1）：server 代辦連線與登入，代價是每個工具都佔用 context。
- [Skill 保存同類任務的做法，個案細節留在專案](https://www.zyx.tw/map/basics/skill-loads-on-demand.md)（觀念，L1）：用適用範圍判斷哪些步驟值得重用，哪些資料應留在專案。
- [Plugin 發版要同步更新目錄，跨 agent 才能安裝同一版本](https://www.zyx.tw/map/basics/plugin-ships-by-version.md)（深讀，L2）：從版本判斷、固定來源到目錄同步，串起完整發版流程。先讀：Skill 保存同類任務的做法，個案細節留在專案。
- [CLAUDE.md 依範圍串接規則，寫好後仍要用新任務確認落實](https://www.zyx.tw/map/basics/claude-md.md)（深讀，L2）：先分清規則的作用範圍，再檢查新對話中的實際行為。
- [Skill 的載入由模型決定，harness 負責把全文送進對話](https://www.zyx.tw/map/basics/how-a-skill-loads.md)（深讀，L2）：模型靠 name 與 description 選 Skill，harness 再把全文放進對話。先讀：Agent Loop 讓模型提出請求，由程式執行並送回結果、Skill 保存同類任務的做法，個案細節留在專案。

## [目標](https://www.zyx.tw/map/goals)

希望 Claude Code 做到的事。

- [我把常貼的資料接成 Claude Code 能查詢的來源](https://www.zyx.tw/map/goals/knows-me.md)（經驗，L2）：從常貼的資料選服務，讓任務背景能直接查詢。
- [把糾正存成規則，保存位置依適用範圍決定](https://www.zyx.tw/map/goals/remembers-me.md)（經驗，L2）：糾正後當場保存，再確認新對話從哪裡讀到。
- [我按固定順序選服務介面，做得到就不開網頁](https://www.zyx.tw/map/goals/acts-for-me.md)（經驗，L2）：從常用的網頁操作盤點需求，再決定接上哪些服務介面。
- [我把一般操作交給背景瀏覽器，只在需要登入狀態時使用 Safari](https://www.zyx.tw/map/goals/out-of-my-way.md)（經驗，L2）：用獨立瀏覽器減少工作干擾，代價是沒有既有登入狀態。
- [我把持續執行的工作交給不依賴筆電的遠端排程](https://www.zyx.tw/map/goals/while-i-am-away.md)（經驗，L2）：遠端主機負責持續檢查，手機通知與修復同意保留人的介入。

## [原則](https://www.zyx.tw/map/principles)

每個選擇背後的想法。

- [我把畫面動作與 tool 放進同一份定義，讓 agent 也能操作產品](https://www.zyx.tw/map/principles/agent-experience.md)（經驗，L2）：共用動作定義，再檢查畫面與 tool 是否漏了對應。
- [我先從對話紀錄定位問題，再修改對應規則](https://www.zyx.tw/map/principles/rules-from-numbers.md)（經驗，L2）：把反覆糾正整理成通則，改完再回查同一步驟。
- [把能自動判斷的規則設成合併條件](https://www.zyx.tw/map/principles/rules-become-checks.md)（深讀，L2）：讓規則決定修改能否合併，不再只靠 agent 記得執行。
- [我先讀懂開源做法，再把適用步驟寫成自己的規則](https://www.zyx.tw/map/principles/read-before-adopting.md)（經驗，L2）：採用哪些步驟，取決於任務前提，也取決於誰負責維護。

## [協作](https://www.zyx.tw/map/fleet)

不只 1 個 agent 的時候，還有用量。

- [我把過程長、結論短的工作交給子 agent](https://www.zyx.tw/map/fleet/subagent-bill.md)（經驗，L2）：派工前，我先衡量中間資訊、重讀成本與交接需求。
- [我依修改出錯的後果，決定是否送審](https://www.zyx.tw/map/fleet/review-by-risk.md)（經驗，L2）：高風險修改交給不同模型審查，並限制審查範圍與輪次。
- [我按合計用量決定是否並行，不確定就逐項完成](https://www.zyx.tw/map/fleet/many-at-once.md)（經驗，L2）：並行集中消耗共用額度，我把逐項完成當成用量不明時的預設。
- [git worktree 隔離檔案，測試資源仍要另外安排](https://www.zyx.tw/map/fleet/isolate-parallel-work.md)（深讀，L2）：每個 agent 使用自己的工作目錄，測試仍須檢查共用資源。
- [我把專案規則放進 AGENTS.md，讓 Claude Code 與 Codex 共讀](https://www.zyx.tw/map/fleet/two-agents.md)（經驗，L2）：專案規則共用檔案，個人規則與安裝內容另查同步。

## [機房](https://www.zyx.tw/map/machines)

蓋給 Claude Code 用的機房。

- [Claude Code 留在筆電，用 ssh 把完整指令送到遠端](https://www.zyx.tw/map/machines/one-claude-many-machines.md)（深讀，L2）：每次遠端指令都要完整，共用 ssh 連線不會保留執行環境。
- [私有網路由協調伺服器管金鑰與規則，資料在機器之間傳送](https://www.zyx.tw/map/machines/private-network.md)（深讀，L2）：協調伺服器分發公鑰與規則，機器之間直接傳送資料。
- [我用環境目錄把設備名稱接到用途、連線與詳細筆記](https://www.zyx.tw/map/machines/what-runs-where.md)（經驗，L2）：名稱與連線放在規則，規格與位址留在按需讀取的筆記。
- [我把工作的執行位置寫成分工表，讓 Claude Code 依表選機器](https://www.zyx.tw/map/machines/one-job-per-machine.md)（經驗，L2）：筆電留給編輯，編譯、測試、運算與備份各有固定去處。先讀：Claude Code 留在筆電，用 ssh 把完整指令送到遠端。
- [虛擬機有自己的核心，容器共用主機的核心](https://www.zyx.tw/map/machines/vm-and-container.md)（觀念，L1）：虛擬機隔離整台電腦，容器隔離一組程序。
- [我用主機代碼與位址尾碼替虛擬機編號](https://www.zyx.tw/map/machines/numbers-are-addresses.md)（經驗，L2）：讓編號能反推位址，並把可檢查的限制寫進建立工具。
- [我替常用專案保留固定位置，讓新對話沿用測試環境](https://www.zyx.tw/map/machines/fixed-place.md)（經驗，L2）：保留程式碼與環境說明，再依使用情況分配工作位置。
- [我把網路設定放進 Git，先改檔案再動設備](https://www.zyx.tw/map/machines/network-in-git.md)（經驗，L2）：以檔案記錄預期狀態，合併後套用規則，持續比對設備差異。

## [延伸](https://www.zyx.tw/map/beyond)

終端機以外的地方。

- [我用 Mod 把常查的狀態放進 Claude Code 畫面](https://www.zyx.tw/map/beyond/changing-the-interface.md)（經驗，L2）：把常查的狀態做成面板，再依用途與空間決定去留。
- [我把通訊 bot 的工具、對話與工作空間分開設定](https://www.zyx.tw/map/beyond/outside-the-terminal.md)（經驗，L2）：通訊入口獨立運作，修改動作依計畫核准。
- [替監控提供 agent 可查詢的入口](https://www.zyx.tw/map/beyond/monitoring-for-agents.md)（經驗，L2）：讓 agent 直接查監控資料，問題處理另依規則與核准流程執行。
- [我用鑰匙圈傳入密碼，隔開模型讀取與程式使用](https://www.zyx.tw/map/beyond/what-an-agent-has-seen.md)（經驗，L2）：密碼只在執行時帶入，但程式仍能接觸密碼值。
- [我把記憶留在筆電，讓 Git 自動保存備份](https://www.zyx.tw/map/beyond/backup-memory-and-keys.md)（經驗，L2）：本機繼續讀取記憶，變更自動推送，遇到密碼就停止。
- [信封加密用 file key 加密檔案，再用收件者公鑰加密 file key](https://www.zyx.tw/map/beyond/envelope-encryption.md)（深讀，L3）：拆開檔案與 file key 的加密流程，看懂誰能解開備份。

## [習慣](https://www.zyx.tw/map/craft)

跟 agent 無關的做事習慣。

- [我把畫面修正寫回共用元件庫，再更新各網站的舊寫法](https://www.zyx.tw/map/craft/one-design-system.md)（經驗，L2）：共用修正需要更新元件，也需要替各網站換掉舊寫法。
- [合併前打包，合併後沿用同一份映像檔部署](https://www.zyx.tw/map/craft/one-way-to-deploy.md)（深讀，L2）：用內容辨認映像檔，再讓各專案呼叫共用部署流程。
- [我用 PARA 固定檔案位置，讓 Claude Code 按用途查找](https://www.zyx.tw/map/craft/where-files-live.md)（經驗，L1）：先定分類與命名規則，再用檔名或用途交代工作。
- [新服務的 log 要從監控端查到，才算完成驗證](https://www.zyx.tw/map/craft/observability-first.md)（深讀，L2）：沿著訊號傳送與查詢的路徑，安排上線驗證與故障排查。
- [我先刪掉不需要的功能，再讓主要動作最顯眼](https://www.zyx.tw/map/craft/simple-first.md)（經驗，L2）：先判斷內容該不該留，再決定怎麼呈現。

## [Harness](https://www.zyx.tw/map/harness)

模型外圍的程式怎麼運作，讀完能自己做一個。

- [LLM 每次只預測下一個 token，長回覆靠反覆生成](https://www.zyx.tw/map/harness/llm-basics.md)（觀念，L1）：理解文字生成的迴圈，判斷回覆速度、記憶與正確性的限制。
- [Agent Loop 讓模型提出請求，由程式執行並送回結果](https://www.zyx.tw/map/harness/agent-loop.md)（觀念，L1）：理解模型與程式的分工，才能分清停止與完成。
- [工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果](https://www.zyx.tw/map/harness/tool-calls.md)（深讀，L2）：模型選工具，外圍程式執行，請求與結果靠 id 配對。先讀：Agent Loop 讓模型提出請求，由程式執行並送回結果。
- [每輪重送 context，固定前段與對話長度要分開管理](https://www.zyx.tw/map/harness/context-is-resent.md)（深讀，L2）：前段是否相同決定快取能否重用，對話長度則影響模型表現。先讀：Agent Loop 讓模型提出請求，由程式執行並送回結果。
- [Prompt cache 只重用完全相同的前段，變動內容要放後面](https://www.zyx.tw/map/harness/prompt-cache.md)（深讀，L2）：理解跨請求的前段比對，安排內容順序並查出未命中的位置。先讀：每輪重送 context，固定前段與對話長度要分開管理。
- [KV cache 保存注意力中間值，只能重用從開頭連續相同的前段](https://www.zyx.tw/map/harness/kv-cache.md)（深讀，L3）：前文決定每個位置的計算結果，也決定快取能重用到哪裡。
- [把長任務的狀態寫進檔案，讓新對話有依據接手](https://www.zyx.tw/map/harness/state-in-files.md)（深讀，L2）：用功能清單定義完成，用進度筆記交接，用 Git 保留退路。先讀：每輪重送 context，固定前段與對話長度要分開管理。
- [MCP 用 JSON-RPC 傳訊息：先取得工具定義，再轉送模型選定的操作](https://www.zyx.tw/map/harness/mcp-on-the-wire.md)（深讀，L2）：沿著 client 與 server 的訊息往返，分清工具發現、執行與錯誤。先讀：工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果。
- [權限規則先拒絕、再詢問、最後放行，沒有命中才交給模式](https://www.zyx.tw/map/harness/permission-gates.md)（深讀，L2）：沿著執行前的比對順序，設定不可越過的界線。先讀：工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果。
- [作業系統沙箱限制指令能碰到的資源，與權限規則是兩道邊界](https://www.zyx.tw/map/harness/os-sandbox.md)（深讀，L3）：沿著指令的執行位置，查清檔案、網路與外部程序的限制。
- [工具讀回的內容可能被當成指令，防護要限制讀取與傳送的組合](https://www.zyx.tw/map/harness/untrusted-input.md)（深讀，L2）：從外部文字進入模型的路徑，判斷資料外流風險。先讀：工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果。
- [子 agent 另開迴圈，交接內容決定彼此知道多少](https://www.zyx.tw/map/harness/subagent-fresh-context.md)（深讀，L2）：派工與回報各有一道邊界，背景與發現都要明確交接。先讀：每輪重送 context，固定前段與對話長度要分開管理。
- [先做最小的 harness，遇到問題再加零件](https://www.zyx.tw/map/harness/build-a-small-harness.md)（深讀，L3）：從迴圈與工具起步，依錯誤補上規則、權限與壓縮。先讀：工具以名稱、說明與參數格式約定請求，再用同一個 id 對回結果、每輪重送 context，固定前段與對話長度要分開管理、權限規則先拒絕、再詢問、最後放行，沒有命中才交給模式。
- [修改規則前，先用固定任務與自動評分建立比較基準](https://www.zyx.tw/map/harness/evals.md)（深讀，L2）：用相同任務重跑修改前後的行為，依過程與環境判斷成敗。
