建卡 spec 撰寫——共同說明(三支 subagent 都讀)

工作目錄:/Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be。只准寫你負責的 docs/features/FR-114-2609-security-fix-dispatch/cards/spec-<批>.json,不改其他檔、不建卡(建卡由首腦統一跑)、不 commit、不切 branch、不派 subagent。

§1

你在做什麼

FR-114 資安修正派工計畫已把 145 件拆成 46 張卡,每張的修法、入口清單、手測都寫在 batches/plan-b<N>.md。你把你負責那批的每張卡翻成 Notion 建卡 JSON spec——runner 拿到卡不讀其他文件就能開工。

§2

讀什麼(🔴 每次 Read ≤150 行;plan 檔用 grep -n "^## 卡" 定位後只讀該卡那段)

  1. batches/_card-common.md(共同段:title 格式、開頭 quote、工作區段、回寫報告段、紀律段)——逐字併入每張卡,不改寫。
  2. batches/plan-b<N>.md 你負責那批:每張卡的「範圍/每件的修法/入口清單/功能不能壞/手測/需決策者先裁」。
  3. docs/claude/card-templates/fix-card.json(JSON 格式範例,看 blocks 的 type 有哪些:quote/h2/h3/p/bullet/code/divider)。
§3

spec 格式

[
  {"title": "FR-114.1-1 <做什麼一句話>(SUMMARY #37,中)", "requirement": "FR-114",
   "blocks": [ ... ]},
  ...
]

每張卡的 blocks 順序固定:

  1. quote:照 _card-common.md 的開頭 quote 格式填。
  2. h2 問題是什麼(白話)→ p:每件一段,在哪裡/誰做什麼/發生什麼(從 plan 的「#號 一句」與 SUMMARY 問題欄抄,白話),再 p「首腦核對:」+ bullet 列 plan 裡「開檔看到什麼」的證據。
  3. h2 工作區 → 從 _card-common.md 抄,只留本卡用到的那幾條(BE 側/套件側/跨 repo/FE)。
  4. h2 在哪裡 → code(lang text):plan 入口清單的每一個 file:line 一行+一句說明。這是驗收清單,一個都不能漏;不准自己補行號,plan 沒寫的不寫。
  5. h2 怎麼修 → bullet ①②③…:從 plan「修法」抄,具體到函式;含「先查再寫」提示。plan 標「需決策者先裁」的:寫 p「🔴 先回寫本卡問決策者:<問題>/建議:<plan 的建議>——回寫後停,狀態留 Not started,不要自己選」。決策者已裁「照建議」的 D 項(各批檔末段有建議的),直接把建議當定案寫進修法,不再問。
  6. h2 手測 → bullet:從 plan「功能不能壞」與「手測總清單」抄,每條「DEV:做什麼 → 期待看到什麼」。
  7. h2 做完要回寫報告 → 從 _card-common.md 抄,把 M<NN> 與 #號 填成本卡實際的。
  8. h2 連帶(有才寫)→ FE i18n/其他 consumer/migration 的「出貨基線待重產」。
  9. h2 紀律 → 從 _card-common.md 逐字抄整段。
§4

硬規則

  • 白話第一段,術語首次出現括號註解;卡名寫「做什麼」不寫代號。
  • 不得出現任何憑證值(第 4 批尤其:只寫檔案路徑與「用該 key 名 grep」)。
  • 一張卡的 blocks 不超過 90 個(建卡腳本 >100 會分批但容易出錯);plan 太長的卡把入口清單 code block 合併成一個。
  • JSON 用 python3 -c "import json;json.load(open('...'))" 驗過再回報。
  • 卡的順序=plan 卡片清單的順序。plan 說「拆兩張」的(1-4a/1-4b、1-5 若拆)照拆;plan 說「沿用 CM-1998」「不開卡」「驗證卡」的照 plan(驗證卡照樣建、title 標「驗證」)。
§5

回報

只要:spec 檔路徑、幾張卡、哪幾張帶「先回寫問決策者」、JSON 驗證結果。不貼內容。