跳至主要内容

ADR-015: 需求來源與開發規格目錄分層

狀態: 已採納 (Accepted) 提案日期: 2026-09-14 決策日期: 2026-09-14 決策者: 團隊第 2 輪 peer review 確認 最後修訂: 2026-09-14 範圍: ADR-014 發布前目錄修訂、來源文件路由、BR 路徑相容性

背景與決策方向​

ADR-014 已通過 P4 審閱並提交於 edfeb53c，尚未發布。發布前使用者確認：第一部分保存需求來源與整理後的 BR；第二部分是開發團隊使用的 Roadmap、Feature List、Epic、US、SBE。將兩者放在同一 specs 目錄會混淆來源材料與開發規格。

本修訂已於第 2 輪 peer review 通過；採納依據為本次獨立審閱，不沿用 ADR-014 的通過結論。核心契約以 .claude/rules/m-business-requirements.md 為單一事實來源。

目錄分工​

docs/
  requirements/               # 第一部分，按實際內容建立
    research/                 # 研究材料
    interviews/               # 需求訪談與逐字稿
    meetings/                 # 需求討論與範圍澄清
    agreements/               # SOW、報價功能項目、範圍約定
    business-requirements/     # 整理後的 BR，選用
  specs/                      # 第二部分及其規格管理資料
  design/                     # 設計文件
  testing/                    # 測試與驗收文件

原始材料可以先於 BR 存在，不強制套用 BR schema、編號或 draft／published 生命週期。只有需要整理及追溯業務需求時才建立 BR；不要求先完成 BR 才能撰寫內部規格。原始材料仍可存外部系統，以穩定 identity、revision 與 locator 追溯，無須全部複製進文件站。

需求訪談與需求會議的 transcribe 產出分別路由到 interviews／meetings；技術設計會議放 docs/design/meetings/，進度、回顧及其他非需求會議放 docs/meetings/。混合或用途不明者先確認分類，不以所有會議都是需求來源處理。

requirements 使用獨立於 specs 的 category 與 autogenerated 導覽；實際材料首次成功落檔後才建立入口，不預建五個空目錄。既有人工 README 保留；二進位材料以說明或 locator 引用。此框架目前沒有實際 BR／原始需求材料需搬移，因此本次不在 app-docs 新增空目錄或空 sidebar。

路徑與遷移​

BR 新路徑固定為 requirements/business-requirements/BR-{NNN}.md（相對 docs），US 的 depends_on 使用此路徑。BR ID、語意 projection 與 sidecar schema 1 維持原定義。

舊 specs/business-requirements/ 下仍有 BR，或 US 仍引用舊 BR 時，共用 parser 明示 migration error，consumers 不得視為無 BR。next-id 同時計入新舊目錄及可用 Git 歷史，避免已刪除舊 BR 編號被回收。

既有專案遷移須盤點來源、引用、相對連結、導覽與 llms 索引，再搬移並更新定位；不重編 BR，不改來源 identity／revision 或事件歷史。US 來源核對 sidecar 留原位置，BR coverage sidecar 隨 BR 搬移。讀取接受 generator 1.0.0／1.1.0 的合法歷史快照，新寫入使用 1.1.0；舊快照中的路徑與新輸入不符而 stale，必須明示 acknowledge／cover 重核，不以字串替換 JSON 假造 current。其他 generator 版本仍 unsupported。

未提供自動遷移命令；helper 負責偵測與驗證，文件搬移及導覽修改依 skill 執行。UAT 的全檔輸入契約維持不變，來源搬移後需依既有 UAT 流程重新產生證據。

Scaffold 與原始材料​

filtered copy 在複製前排除整個 docs/requirements/，包含未列在五分類的自訂來源目錄；亦保留舊 BR／研究／逐字稿位置與非需求會議材料的排除。來源不先複製到下游再刪除。既有 gitignore、symlink 與目標路徑檢查保留。

copy helper 不修改 sidebar／首頁／llms；scaffold skill 接著移除指向已排除內容的入口並建置核對。選擇保留的示意 BR 必須在過濾後重新編寫、去識別化並標記 reference，不複製原始業務承諾或核對 sidecar。

考量的方案​

方案決策理由
BR 留 specs，原始材料另放 requirements同屬第一部分卻分散，未採用。
原始材料與 BR 都移到 requirements採本方向，使來源整理與開發規格有清楚邊界。
所有會議都移到 requirements會混入進度及技術紀錄，改依用途分流。
搬移時自動改 sidecar 路徑並保留 current路徑為已核對輸入的一部分，改採保留快照並明示重核。

不搬動 specs 既有 domain-model、checklist、progress；這些並非本次第一部分來源材料的問題範圍。BR 仍選用，沒有 BR 的現行開發流程不增加要求。

驗證與審閱​

  • BR 自動化套件 54 項通過，含 8 項目錄修訂案例：舊引用、舊目錄、兩種舊 sidecar 重核、舊 Git 編號、僅原始材料、整個 requirements 排除、未知 generator。
  • UAT 回歸 9 項、文件站 build:docs-only、llms 索引（281 文件／283 條目，MISSING 0／STALE 0）通過。
  • 拋棄式 Docusaurus 驗證無第一部分、獨立 requirements 導覽及 filtered copy 後移除入口的建置均通過；導航由 skill 層處理，非 native helper 自動化。
  • Codex audit → sync → validate 通過：12 個 AGENTS、59 個 skill adapters；skill 格式與版本、方法論引用紀律及 diff 檢查完成。
  • 第 2 輪審閱通過，狀態改 Accepted；提交與 fleet publish 另依使用者授權執行。

第 1 輪處置​

第 1 輪提出 R1-01（major）：共用 docs 模組偵測仍只搜尋 specs，與 requirements-only 支援不一致。已修訂 m-skill-execution.md，同時搜尋 workspace／模組相對的 specs 與 requirements 四個路徑；正規化並按模組去重，多候選交由使用者選擇，偵測全程唯讀。

從規則文字擷取四個 Glob，於隔離目錄驗證六個情境通過：requirements-only 的 workspace、兄弟模組、docs 模組三種執行位置；兩部分共存去重；specs-only 相容；多模組保留全部候選。前三種均確認未建立 specs。此為規則演練，不宣稱已新增原生模組偵測工具。第 1 輪處置時 ADR 維持 Proposed，後續確認見下節。

第 2 輪結論與收尾​

2026-09-14 第 2 輪通過。審閱方核實 R1-01 修正，重跑六個偵測情境、Codex validate（12 AGENTS／59 adapters）與 git diff --check 均通過，並查閱本輪文件建置成功紀錄。無新增意見，無 open blocking／major。

決策與驗證摘要保存於本 ADR，契約與共用偵測分別保存在 m-business-requirements／m-skill-execution，FU-96 保留提交及發布待辦。本次暫時簡報完成結論落點後關閉；後續從本 ADR 接續，不依賴暫時簡報。審閱通過不等同 fleet publish 授權。

發布紀錄​

2026-09-14，使用者授權 commit & publish。框架成果提交 d9b5f0cd；8 個下游的 117 個 canonical 檔案均對齊此 SHA，各更新 37 個方法論檔案，並另行提交 3 個 Codex 衍生配置檔。各下游 validate 通過，最終 canonical drift 為 0、工作區乾淨。ICT 的專案延伸規則保留；沒有遷移或修改下游 docs 文件。

下游方法論提交Codex 提交推送
almanac-g1b6d2b77567d8f7無 remote，僅本機提交
crm-v275c5825ce1a747完成
florae-g11f1346c888761e07完成
ictf8253013425c4646完成
nbsos37dc92a2686b6109完成
tms7e5aaf1134fa2b完成
tps-g100273b1bbea2be完成
tts-v11430dff77c3710完成