需求實現（資料夾結構 + 工作日誌）

需求實現（資料夾結構 + 工作日誌） 是做什麼的？

在開始建構已分析完畢的需求時應用的通用指示 （不適用於分析階段）。根據已在 RV2-054-132-019_Integración proceso ADG（CONSUBANCO）中使用的模式重建，該模式首次應用於此。 此技能是可攜的：無論在哪個專案/客戶中使用都同樣適用，遵循 §0 的錨定規則。

0. 這份文件的位置（專案間的可攜性）

此提示不假定絕對路徑或特定客戶的名稱。在任何使用此技能的專案中，有效的錨定規則如下：

• 始終存在一個資料夾，用於彙整該專案/客戶的所有需求——實際名稱可能有所不同（Req\、Requerimientos\，或使用者在首次處理新專案時指定的其他名稱）——並且在該資料夾內，每個需求一個子資料夾，以其代碼命名（例如 RV2-054-132-019，有時後面跟著 _<簡短名稱>，例如 RV2-054-132-019_Integración proceso ADG）。
• 此文件中的所有其他內容（README.md、Compartidos\、EchasXC\、SCRIPTS\...）都是相對於該特定需求的子資料夾，無論上層容器資料夾的名稱為何。無需每次都詢問容器資料夾的名稱——如果專案中已存在一個（Req\ 或 Requerimientos\），則使用該名稱；如果尚不存在（新專案），則在建立之前詢問使用者希望如何命名。
• 一個新的、獨立的需求（參見 §10）的判斷標準是：它擁有（或需要）其在該容器資料夾下的自己的子資料夾，並帶有自己的代碼——永遠不要放入另一個現有需求的資料夾中，即使它們屬於同一個客戶/模組。

具體的樹狀結構（§1-§4 中的所有內容都直接掛在需求資料夾下，沒有任何內容存在於此樹狀結構顯示層級之上或之下）：

Req\                                     (或 "Requerimientos\"，專案已使用的名稱)
└─ RV2-054-132-019_Integración ADG\     ← 需求資料夾（§0），所有其他內容的錨點
   ├─ README.md                          ← §1，工作日誌
   ├─ Compartidos\                       ← §2，使用者故事/圖片/證據/金鑰
   ├─ EchasXC\                           ← §4，Claude 生成的所有非正式交付物
   │  └─ SCRIPTS\                        ← §3，Claude 的工作資料夾（非根目錄）
   │     ├─ ORG\                        ← 回滾，獨立編號
   │     └─ MOD\
   │        ├─ ALTERS\                  ← 僅限資料表
   │        ├─ SP\                      ← 僅限預存程序
   │        ├─ FN\                      ← 僅限函數
   │        └─ VI\                      ← 僅限檢視表
   ├─ SCRIPTS\                           ← 由使用者整理的根目錄資料夾（§3），未經許可不得觸碰
   ├─ Analisis_Impacto_[CÓDIGO].docx    ← 分析階段的交付物（如有要求）
   ├─ Estimacion_tiempos_[CÓDIGO].xlsx
   └─ Plan_Implementacion_[CÓDIGO].docx

1. 變更工作日誌——需求資料夾根目錄中的 README.md

一個單一的、活躍的檔案，每次建構/修改某些內容、解決或新增待處理問題，或任何事物的狀態變更時都會更新。固定結構如下：

• 包含需求代碼和名稱的標題 + "最後更新：YYYY-MM-DD"。
• 這是什麼——2-4 行的需求摘要。
• 總體狀態——已建構的內容——每個階段/模組一個項目符號，標記為已建構 / 部分完成 / 待處理。
• 架構（每項內容的位置）——畫面路徑、關鍵 SP（及其標誌）、作業、關鍵資料表、設定檔。資料庫存取（伺服器、資料庫名稱、使用者名稱和密碼）不記錄在此處或任何檔案中——它會根據入口網站/專案而變化，使用者在需要時提供，同時提供密碼（參見 §7）。
• 待辦事項——分為 "客戶問題"（解決後用 ~~文字~~ 劃掉，不要刪除）和 "待開發事項"。
• 變更工作日誌——每次會話/日期的條目（**YYYY-MM-DD（簡短標題）**），最新的在上方，包含：發現了什麼實際漏洞/錯誤、決定了什麼以及為什麼、哪些檔案變更了、使用者還需要做什麼（執行腳本、重新編譯、在畫面上測試）。

此檔案不會取代 Analisis_Impacto_[CÓDIGO].docx 或 Plan_Implementacion_[CÓDIGO].docx（這些是分析階段的交付物）——此 README 是建構過程的即時狀態。

當檔案過大時進行輪換——如果 README.md 接近或超過 ~200KB，請在繼續新增之前，先歸檔較舊的會話（已發生的真實案例：一個 README.md 超過 256KB，導致閱讀工具無法打開）。機制：將最舊的工作日誌條目移到一個新的 README_historico_AAAA.md 檔案（每年一個，或視需要而定），在活躍的 README.md 中只保留最近的 ~10-15 個會話 + 2-3 行已歸檔內容的摘要（以便僅閱讀活躍檔案時不會失去連續性）。其他部分（這是什麼、總體狀態、架構、待辦事項）永遠不會被歸檔，始終保留在活躍檔案中——只有會話工作日誌會輪換。

2. Compartidos\ 資料夾

所有與客戶/外部供應商共享的輸入材料或證據，而非程式碼：使用者故事及其附件、從文件中提取的嵌入式圖像/螢幕截圖、金鑰（PGP/憑證）、資料對映檔案、接收自或發送給第三方的測試檔案（例如 CDC）。

如果在 Compartidos\ 中出現一個主題與當前需求不符的文件（例如，"整合 ADG 流程"資料夾中的 "日誌/稽核"使用者故事）：不要假設兩種簡單的處理方式——既不要因為它存在於此就將其視為此需求的證據，也不要自行忽略/移動它。詢問使用者以下三種情況是哪一種：

• 位置錯誤——屬於其他資料夾，被錯誤地複製過來。
• 尚未建立自己資料夾的新且獨立的需求——為其建立一個具有相同結構的資料夾，如果與當前需求共用資料庫物件/畫面，則在兩者的 "相關需求"（§10）中記錄。
• 有意歸入單一客戶資料夾的需求組（此模式在傳送給 QA 的電子郵件範本中有先例，該範本明確包含 "需求組"）——如果是這種情況，請確認是否仍應為每個代碼建立子資料夾。

3. 腳本資料夾——SCRIPTS\ORG\ 和 SCRIPTS\MOD\

在需求資料夾中有兩個不同的 SCRIPTS 資料夾：<requerimiento>\SCRIPTS\（根目錄）和 <requerimiento>\EchasXC\SCRIPTS\。**Claude 在構建腳本時會將其放入的工作資料夾是 EchasXC\SCRIPTS\。**根目錄 SCRIPTS\ 資料夾由使用者手動整理，當他認為某個腳本已完善時，會從 EchasXC\SCRIPTS\ 提升過來——除非使用者明確要求，否則不要觸碰該根目錄資料夾。

MOD\——每個物件類型一個子資料夾，不進行分組，每個都有自己獨立且互不依賴的序號（彼此不共用編號）：

• MOD\ALTERS\——僅限資料表（CREATE TABLE / ALTER TABLE）。
• MOD\SP\——僅限預存程序。
• MOD\FN\——僅限函數（CREATE FUNCTION）。
• MOD\VI\——僅限檢視表。
• 如果出現一個沒有專用資料夾的物件類型（索引、觸發器、作業等），詢問使用者希望如何命名該資料夾，而不是自行假設它應該放在哪裡或將其放入 "看起來像" 的資料夾中。（曾經犯過一個實際錯誤：一個函數先被放在 SP\ 中，然後又被放在 ALTERS\ 中，直到使用者要求建立專用的 FN\。）
• 所有資料夾的命名模式：已存在且被修改的物件 → N_NOMBRE_MOD.sql；完全新的物件（在資料庫中不存在）→ N_NOMBRE_NEW.sql。

ORG\——被修改物件的回滾（_NEW 物件在此沒有對應項：新物件的回滾就是直接刪除它，沒有先前內容需要捕獲）。在觸碰現有物件之前，提取其當前在資料庫中的實際定義並儲存在此——該檔案就是回滾。

• **ORG\ 不是 MOD\ 的數字鏡像。**很容易假設如此，但這是錯誤的——它們有獨立的編號。甚至可以在自身內部按類別編號（例如，在一個批次中，尊重依賴關係，針對所有 MOD\ALTERS 的整合回滾，以及針對每個被觸碰的 SP 的單獨回滾）。在假設 "與 MOD 中的編號相同" 之前，請先與使用者確認 ORG\ 的編號方案——已經因為一次錯誤假設而修正過。
• 每次觸碰/部署物件時，明確告知使用者它（的名稱），以便清楚哪個被移動了。

本節中任何腳本的一般規則：

• DDL 始終是冪等的（IF NOT EXISTS / COL_LENGTH(...) IS NULL）。
• 一個呼叫另一個新 SP 的新 SP，應與其依賴項定義在同一個檔案/批次中，絕不在後面的檔案編號中。
• 如果稍後 "統一"/清理增量腳本（稍後透過獨立的 ALTER 新增的列被折回到原始的 CREATE 中）：備份的 ALTER 仍保留在已完成的 CREATE 下面（兩條路徑共存，不選擇其一）；如果相應的 ORG 已經完全 DROP 了該物件，則不需要更改——如果 ORG 是逐列回滾，則檢查順序（在回滾中觸碰列之前先刪除索引/約束，在設定最終可為空性後再建立）。

4. 非交付物的工作材料——EchasXC\

Claude 為支援建構而生成但不正式交付給客戶或團隊的所有內容（驗證查詢、手動測試、技術表、草稿電子郵件）：放在 EchasXC\ 子資料夾中，與 Compartidos\ 和正式交付物分開。

5. 編碼——無論如何都不要修改檔案中已設定的編碼

在編輯任何包含重音符號的檔案之前（.aspx/.aspx.vb/.master/腳本等），**不要僅僅因為它聲明為 UTF-8 或 file 命令報告為 UTF-8 就假定它是 UTF-8。**一些舊版入口網站的舊檔案內部實際上是 ISO-8859-1/Windows-1252（重音符號為單個高位元組），而標準的 Edit/Write 工具會將整個檔案解碼/重寫為 UTF-8——檔案中任何既有的重音符號（不僅僅是編輯附近的部分）都會被轉換為亂碼（U+FFFD，在瀏覽器中顯示為 "�" 或類似字元），這種轉換在儲存時是無聲且永久的。

• 在觸碰此類檔案之前，驗其實際編碼（file archivo.aspx，注意：一個之前已損壞的檔案可能會報告為 "UTF-8"，但實際上並非如此）。
• 如果是 ISO-8859-1，透過 PowerShell 使用 [System.Text.Encoding]::GetEncoding("ISO-8859-1") 進行編輯——使用該編碼解碼原始位元組，在記憶體中替換，然後使用相同編碼重新寫入。對於有此疑慮的檔案，永遠不要使用標準的 Edit/Write 工具。
• 每次編輯後都要驗證，而不僅僅是之前：如果儲存庫中有 git，請在編輯後立即執行 git diff --stat——刪除行數遠大於預期更改量是損壞的跡象，而不是預期的編輯。如果沒有 git，請比較檔案編輯前後的大小。
• 如果檔案已經意外損壞：在重新使用正確方法之前，使用 git checkout -- 檔案 進行還原（恢復完整的原始位元組）——一旦被覆寫，丟失的重音符號就無法恢復。
• 對於 Claude 建立的（而非編輯的）新檔案：如果專案要求（與使用者確認是否適用），則確實需要明確的 UTF-8 BOM。

6. 總體立場——像資深人士一樣行事，永遠不要想當然

不要假設某件事 "應該這樣運作"，某個模式會像在其他地方一樣重複，或者某個資料/結構是記憶或粗略閱讀所暗示的那樣。始終驗證實際流程：

• 在斷言結構、資料或行為之前，先查詢實際的資料庫（DEV）——不要假設，要去查詢。
• 在斷言畫面/SP 的功能之前，先查詢實際的程式碼（grep/讀取檔案）——不要相信名稱或第一印象。
• 在新增 "看起來必要" 的內容之前，先查閱使用者故事/需求文件——如果沒有明確說明，就不要慣性地建構。
• 在聲稱完成之前，驗證每次變更的結果（SET PARSEONLY ON、git diff、測試執行），而不是因為邏輯看起來正確就假設編譯/運作良好。

7. 針對資料庫的執行規則（適用於所有情況，不僅是腳本的 DDL）

• **永遠不要對資料庫執行 INSERT/UPDATE/DELETE/DDL，即使在 DEV 環境中，即使有聊天的明確確認。**使用者自行執行寫入資料庫的所有內容；Claude 的角色是準備腳本，並在使用者執行後，使用 SELECT 驗證結果是否符合預期。這與 ORG/MOD 資料夾規則無關——同樣適用於目錄、測試資料、任何寫入操作。
• 唯讀查詢（SELECT、INFORMATION_SCHEMA、sys.sql_modules）則可以自由執行，無需每次請求許可。
• 資料庫伺服器、資料庫名稱、使用者名稱和密碼不得記錄在任何檔案中（README.md、Compartidos\、.sql 腳本、程式碼註解）——特別是資料庫名稱會根據入口網站/專案而變化，因此沒有值得記錄的固定值。使用者在需要時透過聊天提供，同時提供密碼，並且僅在該會話的命令中透過環境變數使用——下次再次請求，不要儲存它們 "以免再次詢問"。如果某個會話已經有密碼/連線...