/aor-req — 需求編寫
根據 EARS-12 樣式、INCOSE C1-C9 品質屬性及規範的交叉引用語法，起草 UN、PR 與 SR。輸出為 Markdown 格式。
關於技能與代理的注意事項。 AOR 套件包含位於
.claude/skills/aor-*/SKILL.md的技能（可直接調用，例如本項）以及位於.claude/agents/aor-sme-*.md的SME 代理（僅由aor-review/aor-review-adhoc產生的子代理系統提示）。請勿將代理當作技能調用——這會導致「找不到技能」的錯誤。
操作紀律
全程適用。啟動時逐一陳述，以便使用者了解。
- 模式（啟動時宣告）： 詢問這是探索工作階段（單一需求、對話式、不產生檔案）還是文件工作階段（完整規格編寫、寫入檔案）。若輸入範圍是內嵌文字而非檔案路徑，則預設為探索模式；否則為文件模式。模式控制步驟 5–7 是否寫入磁碟。
- 調用確認： 技能的第一個回應應說明「以
aor-req在 <模式> 模式執行。除非您另有要求，否則檔案將寫入 <輸出路徑>。」消除「技能是否真的執行了？」的模糊性。 - 問答紀律： 一次只問一個釐清問題。等待使用者回答後再問下一個。不要堆疊問題。單次
AskUserQuestion調用提供一個包含多個選項的決定（例如多選選單）視為一個問題；在一次調用中提出兩個不相關的決定則視為堆疊。 - 失敗揭露： 若任何規定的步驟無法完成（檔案寫入被阻擋、子代理調用失敗、參考檔案不可用、部分完成、逾時、權限被拒），請在聊天中說明。揭露後，暫停並詢問是否要重試、退回至揭露的手動模擬，或中止——請勿在未告知的情況下繼續。對於明顯的暫時性失敗（例如網路逾時），在強制揭露前允許重試一次。
工作流程
步驟 1：建立範圍
若使用者傳遞了範圍文字或檔案路徑，則直接使用。否則，透過 AskUserQuestion 詢問：「應指定哪些功能或變更？」
區分範圍文字與檔案路徑（REQ-B）：若輸入符合以下任一條件，則視為路徑：(a) 包含 / 或 \)，(b) 結尾為 .md/.txt/.xlsx/.csv/.docx，或 (c) 透過 Read()` 可解析為磁碟上現有的檔案。否則視為範圍文字——包括多字描述，例如「病患預約掛號系統」。
平局判決： 若只有規則 (c) 符合（無 / 或 \，無識別的副檔名，但 Read() 可解析）且輸入為單一單詞，請在使用者確認後再視為路徑：「我看到一個名為 <input> 的檔案存在。您指的是那個檔案，還是這是一個範圍描述？」
對於 Excel 來源的輸入，請預期主機 LLM 已在此技能執行前將資料列轉錄為工作用 Markdown 緩衝區（此套件不直接解析 Excel）。
步驟 1a：分類層級
若為探索模式，請詢問：
「這是使用者需求 (UN)、產品需求 (PR) 還是軟體需求 (SR)？」
一旦知道層級，跳過未使用的步驟：UN 審查需要步驟 2；PR 審查需要步驟 3 + Echo Gate；SR 審查需要步驟 4–6。
探索模式中的多層級輸入： 若使用者提供一組 UN+PR+SR（或任意多個層級的組合）而非選擇單一層級，則視為多層級審查——依序針對所提供的層級執行步驟 2–4，但維持探索模式的檔案寫入紀律（不自動寫入磁碟；在對話中呈現發現結果）。
若為文件模式，除非使用者另有指定，否則預設遍歷所有三個層級（UN → PR → SR）執行步驟 2–4。
步驟 2：撰寫使用者需求 (UN-NNN)
針對每個不同的利害關係人需求，撰寫一個 UN。規則：
- 技術中立、以利害關係人角度表述
- 純敘述（非 EARS 語法）
- 包含問題陳述（2-3 句）+ 需求陳述
- 透過
traces_to::UN->Persona [<persona-id>]標記人物角色 - 優先級：關鍵 | 高 | 中 | 低
格式請參閱 templates.md。
步驟 3：撰寫產品需求 (PR-NNN)
針對每個 UN，推導出 PR：
- 技術中立、可衡量、客觀
- EARS 語法（參閱
ears-guide.md了解 12 種模式） - 每個 PR 向後追溯：
derived_from::PR->UN [UN-NNN] - 每個 PR 向前追溯：
traces_to::PR->SR [SR-NNN] - 每個快樂路徑 PR 必須至少有一個 If/Then（非預期行為）PR 作為伴隨
- 同樣的 If/Then 伴隨規則也適用於步驟 4 的 SR 層級——每個快樂路徑 SR 必須有一個 If/Then SR 伴隨，指定實作層級的復原措施
- 每個 EARS-N（否定式/
shall not）PR 必須至少有一個正面的伴隨 PR（Ubiquitous、Event-Driven 或 State-Driven），指定預期的正確行為；相同的規則也適用於 SR 層級
「快樂路徑」定義（REQ-E）：若 PR 使用以下正面 EARS 模式之一，則為快樂路徑：Ubiquitous、Event-Driven、State-Driven、Optional、Complex、EARS-E、EARS-T、EARS-P。排除：Unwanted Behaviour、EARS-N（否定式/shall not）、EARS-F（失敗模式宣告）。
對每個 UN 執行對抗性錯誤分解：
- 它如何默默地失敗？
- 它如何有噪音地失敗？
- 它在負載下如何失敗？
- 它在惡意攻擊下如何失敗？
- 它隨著時間如何失敗？
每個失效模式將成為一個 EARS If/Then PR（在標題中標記 [ADV]；識別碼保持規範，例如 PR-007 [ADV]）或存放於單獨風險登錄檔的註記。
實例。 UN：「保留每個上傳的檔案」。失效模式：「當磁碟可用空間耗盡時默默地失敗」。產生的 PR：
### PR-007 [ADV]：在磁碟壓力高時拒絕上傳
如果磁碟可用空間低於 5%，則系統應拒絕新的上傳，回傳 HTTP 507 Insufficient Storage 並附上 Retry-After 標頭。
derived_from::PR->UN [UN-001]
traces_to::PR->SR [SR-014]
請注意，失效模式具體且量化（5%、HTTP 507、Retry-After）——這正是使 PR 具有可驗證性（C7）的關鍵。
步驟 4：撰寫軟體需求 (SR-NNN)
針對每個 PR，推導出 SR：
- 實作特定：命名服務、API、資料庫、錯誤碼
- EARS 語法，包含具體元件名稱
- 每個 SR 向後追溯：
derived_from::SR->PR [PR-NNN] - 每個 SR 向前追溯：
traces_to::SR->TC [TC-NNN] - 使用子句層級粒度（
SR-NNN.c1、.c2）將相關行為整合至單一 SR ID 下 - 每個快樂路徑 SR 必須至少有一個 If/Then（非預期行為）SR 伴隨（步驟 3 中定義了「快樂路徑」）
- 每個 EARS-N SR 必須至少有一個正面的伴隨 SR
步驟 5：欄位規格表
針對具有資料輸入/顯示的功能，在 SR 區段中新增欄位規格表：
| 欄位 ID | 名稱 | 標籤 | 類型 | 最小值 | 最大值 | 單位 | 預設值 | 必填 | UI 暴露 | 驗證規則 | 錯誤訊息 | 父 SR |
|---|
UI 暴露值：editable | display-only | hidden。
步驟 6：Echo Gate
針對每個 SR 子句，撰寫一行可測試的斷言：
VERIFY: [SR-NNN.c1] — [將需求改寫為可測試的斷言]
若無法撰寫該斷言，則表示需求不可測試——請重新改寫。
步驟 7：完整性檢查
在宣告編寫完成前，執行 completeness.md 中的檢查清單。
大量輸入處理
當輸入超過約 200 個來源項目（例如大型 Excel 貼上）時：
- 將輸入拆分為每批 50 列。
- 針對每批： a. 讀取該批次。 b. 根據上述步驟將其轉錄為 Markdown 格式的 UN/PR/SR。 c. 附加至工作檔案（不要覆寫）。 d. 報告進度：「批次 / 完成；已草擬 項需求。」
- 所有批次完成後，對完整檔案執行完整性檢查。
若某批次包含模糊的輸入，請暫停並要求釐清後再繼續——請勿無聲地跳過任何列。
輸出路徑
預設：對於整合的 UN/PR/SR，輸出至 ./requirements/SPECIFICATION.md。使用者可覆寫。
更新現有檔案時，保留現有 ID——以接下來的順序編號附加新的 ID。
交叉引用語法（速查表）
relation_type::SOURCE->TARGET [ID-list]
| 類型 | 方向 | 用途 |
|---|---|---|
traces_to | 向前 | UN→PR, PR→SR, SR→TC, UN→Persona |
derived_from | 向後 | PR→UN, SR→PR, TC→SR |
validates | 驗證 | TC→SR |
mitigates | 風險控制 | SR→RISK |
conflicts_with | 矛盾 | any→any |
識別碼格式
正則表達式：^(UN|PR|SR|TC)-\d{3}(\.[A-Z])?$
- 基本 ID：
UN-001、PR-001、SR-001 - 子 ID（EARS-P 表格）：
PR-010.A、PR-010.B - 子句標記：
SR-001.c1、SR-001.c2
參考檔案
ears-guide.md— 12 種 EARS 模式templates.md— UN/PR/SR 區段的 Markdown 範本completeness.md— 退出檢查清單（UN→PR→SR 涵蓋範圍）