沒看過 repository，就不要先發明檔案、API 和功能

接到「把按鈕統一」這種需求時，很容易立刻想到一個 BaseButton、新的 props，以及幾個要替換的頁面。但在本站，Button 已經存在，也已經有自己的元素選擇、variants 和型別契約。再發明一份，可能只是把同一個責任拆成兩套。

AI 可以很快寫出合理的程式形狀；修改既有專案時，合理還不夠。檔案、介面和功能必須能接到這個 repository 的實際情況，否則提案只是另一個專案的做法。

我的順序是先確認需求指向哪個可觀察結果，再追查目前誰負責它。找到定義和使用點後，才決定要不要新增東西。

先把需求連回實際使用點

「按鈕統一」至少有幾種意思：顏色和間距一致、HTML 語意正確，或互動行為相同。這是需求拆解示例，不代表本站這次又發生了一次按鈕問題。

如果要統一外觀，應先看共用元件和 tokens；如果連結無法開新分頁，要看實際輸出的元素和 href；若頭像控制沒有動作，則要繼續追事件與對話框。不能因為三個地方都看起來像按鈕，就把它們改成同一種操作。

本站作品卡片的 Demo 入口使用本地 Button，但傳入 as="a"；關於頁頭像放大也使用 Button，卻是動作控制。共用的是一部分呈現，操作責任仍在各自的使用點。

按鈕語意篇說明怎麼選元素。這裡要補的是修改順序：先找到這兩種使用方式，再看共用元件怎麼支援它們，不能由元件名稱倒推需求。

沿著定義與引用追查，不從熟悉的名稱開始

目前本站的 Button 由目錄入口匯出本地 .astro 元件，元件內定義可接受的 props 和 variants，再引用 cn 合併 class。cn 的定義又指向實際使用的套件。

這條查法會得到幾個對修改有用的答案：

• 元件已支援哪些輸出元素，不需要重新發明同樣的選項。
• variant 改的是外觀，不能把它和元素選擇混在一起。
• class 如何合併，呼叫端的調整會經過哪個 helper。
• 修改預設值後，哪些頁面可能一起受到影響。

這些答案需要讀目前的定義與引用，不能從其他專案用過的 className、to 或 asChild 推定本站也有。某個 API 在別的元件庫很常見，仍不代表這裡能直接傳入。

manifest 也要一起看。看到範例引用某個套件時，先確認它是否已安裝、版本和專案契約是否符合用途。不能把自己熟悉的 import 貼進來，再把缺少依賴交給使用者發現。

有檔案，不表示有需求；有名稱，也不表示有行為

本站重構時已整理過一個例子：舊專案存在技術篩選元件，但沿著可追溯入口檢查後，沒有證據顯示那組控制被掛載。實際保留的是作品類別切換，不是把所有殘留程式都轉成新功能。

舊元件取證篇保留了那次的入口追查。它回答檔案能不能算成原站功能；對 AI 修改而言，還要多一個界線：即使某個新控制很合理，也不等於已經取得增加它的授權。

現在的作品頁有指向 #development 和 #design 的連結，腳本依 hash 切換對應區塊，並更新 aria-current。要調整這項行為，就應沿著這條實際路徑理解，而不是先建立一份新的全域篩選狀態。

程式形狀如果來自猜測，AI 可能把小需求擴成新的 state、事件和控制，再用更多程式解決自己增加的問題。先看現有責任，可以避免提案一開始就偏離修改範圍；這是工作方法，不是錯誤率降低多少的實驗結論。

找不到時，先區分「不存在」和「還沒找到」

搜尋沒有命中，只能先說這次搜尋沒找到。名稱可能不同，也可能透過匯出入口、資料檔或動態來源接進來。若要斷言某項能力不存在，就需要更完整的追查。

我會回到頁面入口看 import，再沿著元件、資料和腳本往下找。如果需求談的是可見行為，就用實際輸出補確認；如果涉及 API、登入或外部服務，則還要有對應的執行與授權資料，不能只靠前端名稱下結論。

當 repository 或外部環境無法取得時，應把提案標成假設，明確說缺少哪份資料。例如：「目前未找到既有的送出流程，需要確認是否已有後端介面。」這是溝通示例，不是本站新增了表單或 API。

假設可以用來討論選項，但不能偽裝成已存在的函式簽名，更不能寫出一段看似成功的請求結果來補空白。

動手前，至少說得清楚這次會接到哪裡

不需要為每個小修改列出整份架構報告。比較有用的是一段能被核對的短說明：目前由誰負責、這次要改哪個契約，以及哪些使用點要保持不變。

以 Button 為例，若只是調整共用外觀，就先確認原本的連結和動作元素不變；若要修改 type 預設，則需確認呼叫端是否依賴既有行為。兩種改動的影響不相同，不能共用一句「統一按鈕」當成全部驗收條件。

完成後再檢查實際結果，而不是只證明新增檔案存在。型別、建置、HTML 和瀏覽器操作各有範圍；具體驗證分工另見建置與完成界線篇。

這樣的順序也保留了新增功能的空間。若現有結構確實無法承接需求，就在確認缺口和修改授權後新增，不必為了少改檔案而勉強沿用。先讀 repository 的目的，是讓新設計有依據，不是要求永遠不能改架構。

紀錄範圍

本文依據本站目前 Button 的定義與使用點、class 合併 helper、作品頁和已公開的重構取證紀錄整理。按鈕需求、API 缺口與溝通引文是說明示例，不是新的事故、服務或已執行請求；沒有比較不同模型的能力或量測開發效率。

我希望每次修改都能說清楚為什麼接在這裡。看不到證據時，先縮小結論或補齊必要資訊，比寫出另一套完整但不屬於這個專案的程式更有用。