AlemTuzlak/skills

接觸地圖

建立一個心理地圖，描繪此變更必須觸及哪些部分才能完成。不要撰寫實施計畫。不要撰寫程式碼。不要在流程中載入下一個技能。後續的工作流程技能會將此地圖與其他技能串聯起來。

地圖就是產出：完成變更所需的所有零件和檔案。

使用時機

在使用者已決定變更的內容以及他們已選擇的任何方式之後載入。

• 執行於： 新功能、錯誤修復、移動邊界的重構。
• 跳過： 錯字、註解、格式化、僅鎖定檔案、不含程式碼的文件。
• 如果意圖仍不明確（「實作 X」但未選定行為）：停止。詢問直到變更確定。然後再繪製地圖。不要為尚未選定的功能繪製地圖。

嚴格門檻

1. 無程式碼且無下一個技能。 此技能僅繪製地圖。它不規劃區塊。它不實作。
2. 顯示地圖並停止。 不要等待批准。如果地圖有誤，使用者會中斷。
3. 不要讀取 coupling.json。 那是後續的獨立檢查。
4. 不要中樞整個儲存庫尋找工具。 僅記錄代理在命中網域中實際看到的重用。後續的技能會負責完整搜尋。

持久性地圖

路徑：<repo>/.agent/domain-map.json

與儲存庫一同提交。僅限網域粒度。函式名稱不屬於此處。

{
  "version": 1,
  "domains": [
    {
      "id": "auth",
      "owns": ["packages/auth", "packages/auth-ui"],
      "talksTo": ["users", "sessions"]
    }
  ]
}

• id — 簡短名稱，一個單字或 kebab-case。
• owns — 套件或資料夾路徑。
• talksTo — 其他網域 ID。

僅在網域層級的事實發生變更時才寫入此檔案： 新增、移除或重新命名網域；owns 路徑；或 talksTo 連結。在現有網域內新增函式不得編輯此檔案。

程序

程序 1：確認已確定的意圖

1. 如果變更已明確（已命名的錯誤、已命名的函式、已命名的行為），繼續。
2. 如果使用者仍在選擇他們想要什麼，停止繪製地圖。詢問直到意圖確定。然後返回此處。

程序 2：載入或引導地圖

1. 如果 .agent/domain-map.json 存在，讀取它。
2. 如果它不存在，建立一個僅限網域粒度的初始地圖：
   • 優先使用 packages/*（或儲存庫的套件資料夾）。
   • 否則使用 src/（或主要來源根目錄）下的頂層區域資料夾。
   • 根據這些 owns 路徑之間的匯入邊緣設定 talksTo。
   • 不要將函式名稱放入地圖中。
3. 如有必要，建立 .agent/。寫入檔案。在同一輪中顯示新的地圖。繼續。不要等待。

程序 3：縮小變更範圍

1. 從地圖和已確定的意圖中選取命中網域。
2. 從明確屬於變更的模組開始。
3. 讀取這些檔案。僅在「要觸及的檔案」清單仍在變化時跟隨匯入。
4. 當新開啟的檔案不會改變地圖時停止。不要為了完整性而讀取整個套件。
5. 將零件命名為模組加上變更將使用或相鄰的現有函式和型別。檔案是指標，不是地圖。
6. 記錄在這些檔案中實際看到的重用（路徑 + 符號）。不要中樞整個工作區尋找輔助程式。

程序 4：如果存在多個路徑則選取路徑

如果只有一個誠實的路徑存在，用一句話說明。

如果存在多個路徑，選取一個。在決定路徑的第一個階梯步驟停止：

1. 重用存在的東西，而不是撰寫新的模組。
2. 停留在命中網域內。不要開啟一個新的網域。
3. 如果內部變更可行，不要新增套件、層或公開 API。
4. 然後是最少檔案。

命名獲勝者以及哪個步驟決定了它。最少檔案是平手時的決定因素，不是整個規則。不要為了贏得檔案計數而將新行為塞入一個神級檔案。

程序 5：更新地圖（僅限網域層級）

1. 如果此變更新增、移除或重新命名了一個網域，或變更了 owns / talksTo，請在同一次工作中修補 .agent/domain-map.json。
2. 如果在網域粒度沒有變更，則保持檔案不變。

程序 6：顯示每次變更的地圖

按此順序顯示以下六個部分。不要為每個任務撰寫 markdown 檔案。

1. 命中網域 — 來自地圖。
2. 零件 — 模組，以及涉及的現有函式和型別。包括看到的重用（路徑 + 符號）。
3. 它們如何通信 — 僅此變更使用的邊緣（呼叫、型別、資料）。不是完整的呼叫圖。僅當這些邊緣在項目符號中難以看到時才新增 Mermaid 圖表。
4. 要觸及的檔案 — 終點線清單。這是獨立的產出。
5. 不會觸及 — 明確說明。阻止路過式編輯。
6. 路徑選擇 — 如果只有一個路徑，一句話說明。如果有多個，獲勝者和階梯步驟。

程序 7：停止

1. 在程序 6 之後，停止。
2. 不要撰寫程式碼。不要從這裡載入另一個技能。

決策樹

• 意圖未確定 → 程序 1，然後停止繪製地圖直到它確定。
• 意圖已確定，行為變更 → 程序 2 → 3 → 4 → 5 → 6 → 7。
• 錯字 / 註解 / 格式 / 鎖定檔案 / 僅文件 → 此技能不適用。
• 地圖檔案缺失 → 程序 2 步驟 2（引導），然後繼續。
• 一個路徑 vs 多個路徑 → 程序 4。

紅旗

訊號	含義	應採取的動作
在使用者選擇功能之前繪製地圖	意圖未確定	程序 1。先問清楚。
開啟 owns 中的每個檔案	漫遊，不是地圖	程序 3：當檔案清單穩定時停止。
中樞 monorepo 尋找 isRecord	完整搜尋是另一個技能	僅記錄已看到的重用。
讀取 coupling.json	錯誤的檔案	將該檢查留待後續。
在地圖上等待「看起來可以嗎？」	門檻是顯示並停止	顯示六個部分並停止。
在地圖後開始編碼	此技能僅繪製地圖	程序 7。無程式碼。
從這裡載入下一個管線技能	將組合留給工作流程	停止。讓工作流程技能來串聯。
寫入 .agent/touch-maps/<task>.md	過時的任務垃圾	僅限聊天（或會話）。地圖檔案是唯一的持久性資料。
因為新增了輔助程式而編輯地圖	函式粒度在地圖中	保持地圖不變。將輔助程式放在第二節。
首先選取最少檔案的路徑	神級檔案陷阱	執行完整的階梯。

錯誤處理

• 不在 git 儲存庫內： 在六個部分中繪製此變更的地圖。跳過地圖檔案。用一句話說明。
• 地圖 JSON 無效： 不要猜測。報告解析錯誤。僅在使用者同意時從程序 2 步驟 2 重建，或如果意圖很明顯（尾隨逗號、缺少括號）則修正 JSON。
• 命中網域不明確： 選取能夠擁有此變更的最小網域集合。在路徑選擇中說明不確定性。不要為一個單一檔案的錯誤發明一個新網域。
• 使用者中斷表示地圖有誤： 修正六個部分。如果路徑變更，重新執行程序 4。然後停止。