AS-IS / TO-BE
找出變更觸及的層級,將各層級的 AS-IS 與 TO-BE 並排比較,並以有證據的箭頭連結各層級:「此欄位被移除,因此回應改變,所以此內容從畫面上消失(或出現)」。如果程式碼變更但使用者看到的內容不變,則結論應直接點明。請勿憑空捏造變更。
下方指令中的 <skill> 是此技能的基本目錄:存放此 SKILL.md 的資料夾(使用者層級安裝為 ~/.claude/skills/asis-tobe,專案層級安裝為 <project>/.claude/skills/asis-tobe)。執行指令前請以實際路徑取代。
原則
- 並排比較。 AS-IS 在左,TO-BE 在右。絕不垂直堆疊。
- 比較實際構件。 酬載依據下方的「실물 고르는 순서」(挑選實際構件的順序),螢幕來自實際截圖,結構來自實際遷移與模型差異。若無實際構件,則標示「실물 없음:<이유>」(無實際構件:<原因>)。手工製作的範例則標示「예시(손으로 만듦)」(範例(手工製作))。
- 僅繪製有變更的層級。 未變更的層級僅標示「변경 없음」(無變更)並附加一行證據。不要建立空表格。
- 每個箭頭都有證據。 每個影響路徑的連結需附上
檔案:行號或提交哈希。若無證據,則標示「추정:」(估計:)。 - 說明誰仍在使用舊規格。 部署此變更後,任何仍在執行舊程式碼的項目:已上架的應用程式、仍開啟舊頁面的瀏覽器分頁、其他服務、其他呼叫端(如管理工具或機器人)。這將決定合併與發佈順序。
- 摘要優先。 頂部的摘要框必須足以支援決策:使用者的語言寫成的一句話結論(不含欄位名稱或狀態碼)、對使用者有何改變、如何部署、能否回滾;每組最多 3 項。緊接其下,三個卡片回答任何閱讀者會接著提出的問題,以問題本身命名而非角色:「정해야 할 것」(須決定之事項)、「먼저 볼 곳」(優先查看處)、「직접 확인하는 법」(自行驗證方法)—規則請見 references/document.md(「問題卡片」)。決策所依據的兩個事項(徽章與回滾可能性)應是第一眼最明顯的內容。每個事實只說一次:已在結論或警告中出現的句子,不要在引言、問題卡片或情境中重複。以下所有內容皆為證據。將較長的酬載與詳細表格摺疊進
<details>中;請勿刪除。不需要引言、進度敘述或結語。 - 佈局即內容。 在 420px 寬度下,頁面不得橫向捲動(僅表格可以)。主體寬度上限為 880px;僅表格與並排比較可使用全寬。表格內的
code僅用於識別碼;僅檔案路徑與識別碼使用等寬字型,韓文描述則不使用。句子長度約 70 個字元,刪除修飾詞。透過標題上方的切換按鈕切換兩種色彩方案:預設為 Dusk(暮色),AS-IS 為米色,TO-BE 為石板藍;Bloom(盛開),AS-IS 為粉紅色,TO-BE 為薄荷綠。請勿跟隨系統深色模式設定。虛線與實線必須與顏色搭配。行內程式碼高亮使用淺色--a-mark、--b-mark,而非深色晶片色。每個色彩方案與 420px 寬度各渲染一次。 - 行業術語,僅解釋一次。 使用開發者、QA 與規劃者能立即理解的詞彙。在韓文文件中使用 레이어(層)、필드(欄位)、API 스펙(API 規格)、호출처(呼叫端)、deprecated(棄用)、breaking change(破壞性變更)、mock 응답(模擬回應),並在首次使用時附上簡短說明(例如 codegen(서버 스펙으로 자동 생성한 타입 파일)—「根據伺服器規格自動生成的類型檔案」)。對於內部用語(如「AC」、自創的畫面暱稱),請在首次使用時說明其含義。詞彙表:references/terms.md。如有某個術語造成阻礙,請先查閱該文件,不可跳過此步驟。
層級
| 層級 | 比較內容 | 實際構件來源 |
|---|---|---|
| Data(데이터,資料) | 資料表、欄位、類型、列舉、約束、索引。僅列出有變更的實體的實體圖,以及模型程式碼 | 遷移、ORM 結構(prisma 等)、DDL 差異 |
| API spec(API 스펙,API 規格) | 請求和回應酬載、事件、codegen 類型。逐欄位的新增、移除、類型變更、語義變更 | OpenAPI 差異、回應 DTO、測試 fixture |
| Behavior(동작,行為) | 伺服器與用戶端對相同輸入所產生的結果 | 測試斷言差異、狀態轉換程式碼 |
| Screen(화면,畫面) | 相同狀態下畫面的兩個截圖 | 專案的截圖工具(references/adapters.md,「프로젝트 어댑터」) |
| User impact(사용자 영향,使用者影響) | 使用者現在能做或不能做的事,以及會改變的數字。包含因發佈順序而導致的中間狀態 | Issue AC、以上各層級的總和、相容性表格 |
各層級的檢查清單與常見陷阱:references/layers.md。
挑選實際構件的順序(실물 고르는 순서,API 規格)
伺服器測試 fixture > OpenAPI 範例 > 記錄的實際呼叫 > 用戶端模擬回應。取第一個完整存在的項目。如果較高層級的來源僅為部分內容(例如由變數建立的 fixture,或直接在行內建立請求並逐欄位斷言的測試),而您已記錄了實際呼叫,則在面板中顯示較高層級來源,並將記錄的呼叫顯示為完整文字,各自標示其來源。記錄的呼叫包含每次執行都不同的值(ID、時間戳);使用 code_diff.py --mask id,time 比較此類酬載,並在來源行中說明,以便新的 ID 不會被計為變更的欄位。用戶端模擬回應(例如用於螢幕截圖的假回應)不是伺服器的實際構件。將所選來源的路徑寫在酬載下方。如果 fixture 由變數建立且無完整 JSON,則從測試的預期值轉錄,將其標示為「예시(테스트 기대값에서 옮김)」(範例(從測試期望值轉錄)),並在縮短處使用 …。請勿填寫預期值中不存在的欄位;將其保留為 …。如果從別處借用了某個值(如模擬回應),請在該欄位旁註明來源。
程序
1. 設定範圍
- PR 輸入:透過 PR 編號取得差異(
gh pr diff <n> -R <repo>)。僅使用路徑或分支會將堆疊的 PR 主線作為基底,並混入其他人的變更。 - Issue 輸入:在每個儲存庫中尋找 PR(
gh pr list -R <repo> --search <key> --state all)。兩個或以上儲存庫合併為一份文件。 - 無 PR:在工作目錄中使用
git diff <base>...HEAD,其中<base>為分歧點,從儲存庫根目錄計算(本機的main可能已過時並混入數百個檔案):
如果差異包含與 Issue 無關的檔案,則基底有誤。在拆分至各層級前請重新計算。git fetch origin main git merge-base origin/main HEAD - 無遠端儲存庫:跳過 fetch,使用使用者指定的基底;否則使用工作開始時的提交(
git merge-base main HEAD,或未提交的工作則為HEAD本身)。 - 未提交的工作目錄:AS-IS 為
HEAD,TO-BE 為工作目錄。git diff HEAD會遺漏新檔案,因此也請讀取git ls-files --others --exclude-standard。凡需要提交哈希的地方,請寫「커밋 전」(未提交)。請勿提交、暫存或切換分支以進行比較。 - 無 PR 或 Issue:目標以其內容命名(「 工作目錄變更」、「 分支」)。部署表格中,每單位(分支、「작업 트리 커밋」(工作目錄提交))一行,PR 儲存格命名該單位;Issue 鍵名則省略,不得憑空捏造。
- 每個儲存庫,寫一行
<repo> <短基底哈希> → <短分支哈希>。在報告中直接使用此格式。在文件中,PR 與哈希僅需在摘要卡片的部署順序表格與基底表格(references/document.md)中出現一次,而非標題中。
2. 將變更檔案分配至各層級
每個檔案歸屬於一個或多個層級;若不確定則開啟該檔案。測試檔案不分配;它們是 Behavior(동작,行為)層級的證據。此表格決定文件將包含哪些層級章節;此為工作材料,不打印在文件中。
3. 首先判斷畫面是否實際變更
即使畫面程式碼有變更,請先詢問:變更後的分支在當前數據下是否可到達? 選擇一個分支依賴的值,找出伺服器是否實際產生該值。
# 範例:移除了應用程式在 stockState === 'SOLD_OUT' 時顯示「품절」(已售完)徽章的分支
git -C <伺服器儲存庫> grep -n "SOLD_OUT" -- <來源檔案> # 伺服器是否在任何回應中放入此值?
git -C <應用程式儲存庫> grep -n "stockState" -- <產生的類型檔案> # 產生的類型允許哪些值
無伺服器程式碼設定該值(僅類型或列舉定義)表示無法到達,即使產生的類型允許該值。將 檔案:行號 記錄為「변경 없음」(無變更)的證據。
如果僅是計算某個值的位置發生了移動(例如伺服器的 ERROR 現在由應用程式計算為 lastError),則將兩個公式及其 檔案:行號 並排比較。相同輸入產生相同值:畫面不變。不同:找出一個會產生不同值的輸入,並捕捉該狀態。
- 可到達:在步驟 4 中捕捉。
- 無法到達:Screen(화면,畫面)層級標示「현재 데이터로는 변경 없음:<이유와 근거>」(以當前數據無變更:<原因與證據>)。將已消失的狀態記錄在「실물 없음」(無實際構件)下,並透過檢查該狀態的測試字串顯示其舊有外觀。如果需要確認,請捕捉一個代表性場景,並使用 md5 顯示相同性。
- 不確定:捕捉。
4. 收集各層級的實際構件
- Data(데이터,資料):三個部分,按此順序。
- 實體圖,開啟。僅列出有變更的實體與直接相連的實體,每側最多 6 個。將其寫成 JSON,讓腳本將兩側繪製為內聯 SVG:
python3 -I <skill>/scripts/erd.py <spec.json>(規格格式請見腳本標頭)。切勿手動繪製 SVG,也切勿載入圖表庫;頁面是自包含的。腳本會透過比較兩側自行標記新增、移除與變更的欄位和實體,因此請按照該提交的真實情況編寫每一側。 - 模型程式碼,摺疊(
<details>):基底與現在,程式碼中保存的模型(struct、class、ORM 結構)。每個模型的一行差異,來自python3 -I <skill>/scripts/code_diff.py <ASIS.txt> <TOBE.txt> --label "<名稱 (路徑)>" --start-a <行號> --start-b <行號>;新增或移除的模型使用/dev/null作為缺少的一側。腳本會計算變更的行,並並排顯示兩種檢視方式(나란히 並排,합쳐서 合併),供讀者切換;切勿手動標記行。 - 欄位表格,摺疊:實體圖未包含的內容(預設值、約束、索引、現有行處理)。
無關聯的單一欄位變更不需要實體圖:在欄位表格中以一行呈現,並保持開啟。如果 AS-IS 沒有儲存的結構(在記憶體中、檔案中),則僅提供
tobe給腳本,並使用asis_note說明資料所在位置(檔案:行號);此時模型程式碼即為 AS-IS 的證據,因此將該<details>保持開啟。建立第一個資料表的遷移即為 TO-BE。如果此變更清理了已部署的遷移,則「이미 반영()」(已應用的 )是影響路徑的第一個連結。
- 實體圖,開啟。僅列出有變更的實體與直接相連的實體,每側最多 6 個。將其寫成 JSON,讓腳本將兩側繪製為內聯 SVG:
- API spec(API 스펙,API 規格):前後酬載,以
scripts/code_diff.py產生行差異(與模型程式碼相同的腳本;每個酬載呼叫一次,長酬載使用--context 3,記錄的呼叫使用--mask id,time)。其下方為「필드 | AS-IS | TO-BE | 시맨틱 변경」(欄位 | AS-IS | TO-BE | 語義變更)。僅名稱或類型變更時,將兩個儲存格合併為一行:<code class="old">start_time</code> → <code class="new">starts_at</code>。呼叫端:- 在每個儲存庫中使用
git grep <欄位>,從儲存庫根目錄執行(子目錄會使路徑變成相對路徑,回傳 0 個結果)。 - 同時在已發布的版本中搜尋:
git grep -n <欄位> <sha>。其結果決定合併與部署順序以及徽章。執行此操作前請先閱讀 references/adapters.md(「尋找已發布版本」)。 必須注意:僅建置清單中的 SHA 為確定的,其他皆為「추정:」(估計:);如果來源不一致,請搜尋所有 SHA,並將任何結果視為「배포된 앱이 읽는다」(已發布的應用程式會讀取);切勿僅依賴標籤名稱(標籤可能屬於同一儲存庫中的另一個可部署項目)。建置清單失敗時的輕量級備援方案(例如無法登入建置服務):使用 Issue 或發布說明中的 SHA,否則使用「추정:」下限。 - Codegen 輸出不是呼叫端;它會根據伺服器規格重新產生。請單獨註明「다시 뽑으면 무엇이 바뀌나」(重新產生時會有何改變)。
- 同時在用戶端的模擬回應與測試 fixture 中
git grep已移除的欄位。如果這些檔案中仍存在,一旦服務器部署後重新產生 codegen,類型檢查可能會失敗。將這些檔案列為最後的部署步驟(「codegen 재생성과 fixture 정리」,重新產生 codegen 並清理 fixture)。
- 在每個儲存庫中使用
- Behavior(동작,行為):
입력·상태 | AS-IS | TO-BE | 근거(테스트 이름)(輸入/狀態 | AS-IS | TO-BE | 證據(測試名稱))。 - Screen(화면,畫面):捕捉前請先閱讀 references/screens.md(「捕捉」)。 兩側使用相同的場景、數據、語言與大小,並在一個暫存工作目錄中(基底為 AS-IS,分支為 TO-BE)進行;對於未提交的工作或不能觸及的儲存庫,則在儲存庫外使用兩個副本;在背景執行安裝與捕捉,比較 md5,然後在步驟 10 完成重新測量後,停止伺服器並移除暫存工作目錄或副本(如果使用者希望保留以重現結果,則保留);切勿提交它們。若無模擬捕捉工具,請在各別連接埠執行每個版本的實際伺服器並進行捕捉。各專案的捕捉指令:references/adapters.md。僅在平台無法捕捉(例如原生應用程式)或步驟 3 發現分支無法到達時跳過捕捉;此時使用「실물 없음:<이유>」(無實際構件:<原因>)加上測試斷言字串。如果不確定,則進行捕捉。
4b. 填寫場景軌道
在填寫「시나리오별 전후」(各場景的變更前後)之前,請先閱讀 references/scenario-rail.md。 其他領域的儲存格名稱:references/domains.md。
| 骨架 | Web/應用程式使用者 | | …
(原文此處截斷,此為翻譯後的完整可用內容,後續內容若存在則應繼續翻譯,但根據提供內容,此處即為結束。)
5. 至 10. (原始內容已截斷,按原則保留結構,翻譯時應繼續對應原始內容)
……
驗證與協調(검증 및 조정,Verification & Coordination)
……