Feature Spec Builder
把「隻言片語」變成「研發級特性需求」。
核心不是寫文件,而是系統性地把一句話裡沒說清楚的東西挖出來、補完整。一句「我需要 XX 功能」通常缺失 80% 的研發必需資訊:角色、場景、邊界、能力歸屬、介面、依賴、驗收。本技能用「固定維度掃描 + 互動式逐問澄清」的方式補齊這些缺口,最終產出一份過得了研發評審的特性需求。
本技能產出止於特性需求——包含介面契約草案和驗收標準,但不做任務拆分和實現計劃,任務拆分交給研發團隊。
配置區(首次使用前請填寫)
本技能依賴一套產品自有座標系與團隊約定做歸類與協同。請把佔位符替換成你團隊的真實定義;按主題分組,未用到的組可留預設。
A. 能力座標系
L1 = <例如 原子能力 / 底層運動與感知介面>
L2 = <例如 組合能力 / 應用級開發包>
L3 = <例如 完整方案 / 場景交付>
五域:域1=<…> 域2=<…> 域3=<…> 域4=<…> 域5=<…>
B. 介面約定
API 預算 = <例如 300 個方法上限> 語言/綁定約定 = <例如 C++ core + pybind11>
C. 整合商與型態
整合商分級 = <例如 Associate / Professional / Expert> 型態 = <模擬 / 真機 / 兩者>
產出輸出目錄 = <預設 feature-specs/;產出寫到 <此目錄>/<特性名>/<特性名>.md>
D. 產品原則(決定產出前自檢 gate 的尺子)
採用內建預設原則:是 / 否(預設=是,全文見 references/product-principles.md)
團隊自定義/補充原則:<可留空;填了則與內建預設合併,衝突以團隊為準>
衝突優先級:<兩條硬約束不可覆蓋:安全預設、向後相容均為紅線,二者相撞必須升級人工拍板;其餘原則的相對優先序請在此填,留空則相撞時一律拋回用戶拍板,不自動排序>
破壞性變更簽字人:<判定為 break 時需誰簽字,例如 平台架構負責人>
E. 實現層 × 部門映射(第 4 步跨層分解指派 owner 用;與 L-Tier 正交——L-Tier 管對外抽象多高,實現層管對內動哪些技術棧、幾個部門)
實現層 → 負責部門/角色 owner → 跨層簽字人
執行時層:
二開 SDK 層 → <填,如 SDK/平台組> → <簽字人>
底層軟體(韌體·中介軟體) → <填,如 嵌入式/韌體組> → <簽字人>
演算法服務(感知·演算法) → <填,如 演算法組> → <簽字人>
硬體(機械·電子) → <填,如 硬體/電子組> → <簽字人>
非執行時層(生態/整合/文件類特性會落這裡,別硬塞給韌體/演算法/硬體組):
文件入口層 → <填,如 DevRel/文件/站點前端> → <簽字人>
建置/分發基建層 → <填,如 SDK 建置/DevOps> → <簽字人>
跨部門升級路徑 = <例如 層 owner → 部門負責人 → 跨部門架構評審會 → CTO>
配置區未填怎麼辦: 至少補齊 A 組(能力層級 + 五域),這兩項直接決定歸類準確度。其餘各組的降級處理——
- A/B/C 未填:歸類(自動歸類步)時顯式宣告「以下 L 層級/域/預算/綁定為我的推斷」並給依據;正文凡用到這套座標系的欄位(層級、能力域、API 預算、綁定約定,分佈在《能力定位》《影響評估·相容·發佈策略》《介面契約草案》各節)一律打
[待確認],絕不把推斷值當已確認寫;把「配置區真實值待補」寫進《遺留待確認》節。- D 未填:預設套用 references/product-principles.md 的內建預設 10 條,並在《產品原則自檢》節註明「本次採用內建預設產品原則」。產品原則自檢 gate 任何情況下都要跑,絕不因配置區空著就略過。
- E 未填:第 4 步跨層分解裡的 owner/部門/簽字人一律打
[待確認·需指派],提示用戶補,絕不臆造部門名——把推斷的部門責任誤派給錯誤的團隊是最危險的失敗。
F. 組織與流程(本地私有配置,公司級協作用)
各公司的「誰負責什麼、過哪些流程 gate、版本怎麼排」不同且私有,不寫進本 skill。用於公司級協作時,把
references/org-process-config.md的模板複製成本地org-process.local.md(或跑scripts/init-org-config.sh生成),按你公司填角色地圖 / 交付 gate / 版本節奏與管道容量。本地私有、勿提交(已在.gitignore)。
- 有此配置:產出時按角色地圖把 owner 落到真實責任人、在《影響評估·相容·發佈策略》列出必過 gate 與交付件、標註目標版本與工作量(人天)vs 管道容量、需求鎖定後變更提示走 CCB(細則見 references/org-process-config.md)。
- 無此配置:用通用角色佔位(如
[產品經理·待指派]),並提示用戶可生成一份本地配置。任何情況下都不要把真實人名/內部流程寫進 skill 或產出到要公開傳閱的文件裡。
工作流
收到一段零散需求後,嚴格按這條主鏈路推進:
接收片段 → 需求分流(識別隱含多特性) → 自動歸類 → 跨層分解與路由(識別各層改動·owner·依賴序) → 第一層澄清(定位·粗) → 第二層澄清(功能細節·細) → 產出文件(過原則自檢 gate)
第 1 步:接收與複述
讀入用戶給的片段。先用一句話複述你的理解(「我理解你要的是……,對嗎?」),讓用戶確認或糾正。這一步防止從一開始就跑偏。
第 2 步:需求分流(識別是否隱含多特性)
一段零散訴求裡常常裹著不止一個需求——尤其是從群聊/郵件原文粘來的片段,主訴求最顯眼,但旁邊還散落著別的訴求、被對話帶偏的提問、或由目標反推出的隱含能力。別一頭扎進最顯眼的那個就開做,先做一次分流掃描:
- 通讀片段,列出其中每一個可獨立成立的訴求(一個動作/一個能力 = 一個候選特性)。特別留意四類常被漏掉的:① 被追問帶偏的「最初那個提問」;② 與主訴求無關、只是同段對話順便提到的獨立訴求;③ 研發已回「暫不支援/自己實現」的點(往往是被埋掉的隱藏需求);④ 由客戶終極目標反推、但當前沒明說的組合能力。
- 異構交付物啟發式: 當一句訴求裡同時出現不同交付物型態(可執行代碼/介面契約/文件內容/站點結構/分發包)時,優先懷疑是多特性——不同交付物型態往往對應不同 owner、不同驗收方式、不同維護週期,混寫會讓一份 md 裡評審對象和驗收標準打架(如「給個 ROS 範例 + 官網加個板塊」= 程式碼特性 + 文件特性,owner 與驗收根本不同)。
- 共享真相源的關聯特性簇: 拆出的多個特性若共享單一真相源(如文件 tutorial = 範例倉代碼 = 主特性契約的對外投影),仍各自獨立成文,但須在每份《依賴與前置》/關聯特性裡顯式釘死真相源歸屬(哪份文件/倉庫擁有定義權,其餘為投影/引用),並給一張簇內依賴圖——複用《層間交接契約》的「定義權歸屬」範式,避免多份文件各寫一版對不上。
- 若確實只有一個訴求,記一句「已確認單一特性」,直接進歸類。
- 若有多個,畫一張需求分流表(候選特性 | 來源原話 | 性質 | 現狀 | 與主訴求的關係/依賴),然後讓用戶拍板本輪細化哪些——這是範圍取捨,絕不自作主張替他圈定。未選中的,在《遺留待確認》節留「關聯特性佔位」,便於後續單獨立項。
- 多特性一起做時,每個特性各自產出一份獨立的特性需求文件,絕不把多個需求混寫進同一份——逐個走完後續步驟,彼此只用「關聯特性」互相指向、標清依賴(如 D 依賴 A+B)。(注意:一個特性哪怕跨層,也只出一份 md、內部分閱讀對象成節,不拆成多個檔案;這是「同一特性內部分層/分閱讀對象」,與「多特性各自獨立成文」不衝突。)
這一步是整條鏈路裡最容易被跳過、卻最影響交付正確性的一環:跳過它,研發拿到的需求可能只覆蓋了客戶訴求的一部分,或把幾個該獨立的特性糊成一個。
第 3 步:自動歸類
把需求釘到座標繫上:它落在 L1/L2/L3 哪一層、屬於五域中的哪一域、是否跨域。歸類本身就會暴露第一批隱含問題——如果你無法乾淨地歸類,說明片段在某個維度上資訊不足,這正是後面要澄清的缺口。把歸類不確定的地方記下來。
注意:歸類釘的是對外抽象層級(L-Tier)和能力域,不回答「這事對內要動哪些實現層、歸哪個部門」——那是下一步第 4 步的事。一個 L1 介面可能只動二開層,也可能一路動到韌體/演算法/硬體。
L-Tier 對非執行時特性的 N/A 出口: 若特性本質是既有能力的交付/分發/安裝/文件型態(非新執行時能力、不暴露 API、不佔 API 預算,如離線安裝包/範例倉/官網板塊——原型 H/I),L-Tier 顯式標
N/A(非能力特性,僅落實現層軸)、五域可標 N/A,不硬塞一個 L 值。判定訊號:交付物是「分發包/文件/站點結構」而非「執行時 API/行為」;其重心轉到建置/分發基建層 或 文件入口層 + 外部依賴軸(第 4 步)。
第 4 步:跨層分解與路由(跨層特性必做)
歸類只回答「落在 L 幾、哪個域」;本步進一步回答**「這個需求要動哪些實現層、各層歸誰、誰先誰後、是不是光靠二開就能獨立交付」**。很多客戶需求看似落在二開 SDK 層,實則強依賴更底層——韌體/中介軟體、演算法服務、甚至硬體——而這些層往往歸不同部門。
按 references/cross-layer-routing.md 的判定問題做五件事:
-
逐層判定要不要動:對二開 SDK 層 / 底層軟體(韌體·中介軟體) / 演算法服務層 / 硬體層四個執行時層,逐層問「這一層需要改什麼」。另外必問兩類非執行時層(生態/整合/文件類特性重心常在這裡):文件入口層(官網板塊、範例倉、文件 IA——owner 是 DevRel/文件/站點,不是研發)與建置/分發基建層(打包、多環境 CI、ABI/預編譯——owner 是 SDK 建置/DevOps)。⚠ 交付物是範例/打包/安裝/分發/文件時(原型 H/I),即使技術觸底=純二開,也不要預設派給二開 SDK 組——按配置區 E 組路由到對應 owner(硬塞給韌體/演算法/硬體組、或預設丟給二開組,都是高危錯派)。能乾淨答「只動二開層、無入口/基建改動」的,記「單層特性(二開 SDK)」,直接進第 5 步。
-
定最底改動層(硬 gate)+ 可行性證偽:找出需要改動的最底層。一旦某層答「不支援/不確定」,沿 二開→韌體→演算法→硬體 逐層下探,直到觸底(找到能支援的層 或 判定物理不可行)。給出層級觸底結論(三選一):A 純二開可交付 / B 跨層可交付 / C 當前層級不可交付(下層未排程或物理限制)。若最底改動層不是二開 SDK 層,本特性就不是二開層能獨立交付的——在文件顯著位置打標:
⚠ 非二開層可獨立交付:本特性最底改動落在 <層>,需 <owner 部門> 先交付 <能力>,二開層才能封裝,並寫進《能力定位》節與 DoR。觸到硬體/物理限制時,立即停止在二開層細化介面簽名——繼續寫一個做不出來的契約草案是評審拒稿高頻原因。 -
畫跨層分解表 + 排依賴序 + 定層間交接契約:列出每層要改什麼、owner 部門、是否阻塞上層;排出自底向上的依賴鏈;為每條跨層依賴釘一份「下層向上層暴露什麼」的交接契約(含定義權歸屬——避免兩部門各寫一版對不上)。
-
識別 owner 與跨部門待確認項(每項必須帶歸屬三元組):哪些層的「要不要動/能不能支援」是你判斷不了、必須找對應部門確認的(如「韌體到底支不支援波束成形」),列成跨部門待確認項。本技能的使用者(通常是產品/SDK 側)在對話裡拿不到下層部門的真實答覆,所以不能只打 [待確認] 丟進清單了事——每一項必須帶三元組:
驗證 owner(誰去對接該部門)|需在哪個評審節點前有答案|未及時答覆的預設假設/降級方案(與閾值類 [待確認] 的「定責人+定法+期限」同一範式)。它們往往是整個需求的關鍵路徑阻塞點。 -
結論 B/C 必做:把真實可交付物回寫主敘述(堵死「假就緒」):一旦層級觸底結論=B 或 C,必須回改《一句話定義》與 P1 故事,使其只描述本輪真實可交付物(如「本輪交付 SDK 樁+簽名,波束實際能力依賴韌體 Q4」),絕不按客戶原始訴求的完整能力寫 P1——否則研發/客戶讀到的就緒文件和實際能交付的對不上,正是最危險的假就緒。下層「不支援且未排程」時,必須在《跨層實現與跨部門協同》節給降級/分期方案(mock 樁 / 有限檔位 / 模擬先行),不能只掛待確認。
結論 C 且二開層本輪無任何可獨立交付物(含樁)的早停出口: 若證偽確認本特性當前實為下層/硬體改動、二開側連樁都沒意義,不要繼續走第 5、6 步逐維澄清(那只會產出一份滿是 [待確認] 的空殼,浪費互動預算、也違背範圍紀律本身)。直接產出一份精簡「跨層路由結論」:層級觸底結論 + 跨層分解表 + 跨層阻塞與升級路徑 + 給客戶的口徑,並顯式標註「本需求當前不是二開層任務,建議轉 <部門> 立項」。
產出型態:一個特性 = 一份 md(分閱讀對象)。 無論單層還是跨層,一個特性都只產出一份特性需求文件;跨層/跨部門內容不拆成多個檔案,而是在這同一份 md 內分閱讀對象成節(產品/評審、二開 SDK、韌體、演算法、硬體),並在文件頂部給一張《閱讀指引》把「閱讀對象 → 該讀哪些節 → 各自負責什麼」列清,便於在一份需求文件裡全程追蹤。分閱讀對象的節模板與閱讀指引模板見 references/cross-layer-routing.md《九》。
產出填進輸出模板的《跨層實現與跨部門協同》節。
本步結論會改寫第 5、6 步要問的問題清單:例如客戶要
set_microphone_beam_angle波束介面,本步若核實出韌體尚不支援波束成形,第 5 步就要先澄清「是否接受級聯到演算法/硬體、本輪範圍是否僅做 SDK 佔位」,而不是直接去問介面簽名。為什麼單獨成步、且排在定位之前: 一個「其實要動韌體」的需求若被當普通二開特性走完,產出的會是一份「看著研發能接手、實則下層沒這能力」的假就緒文件——這是最危險的失敗模式。把這一步前置,就是在 DoR 之前先堵住「偽二開特性」。
仍遵守《互動式澄清規則》: 跨層分解表裡凡 owner、某層是否需改、底層是否已支援屬推斷的,一律打
[待確認]並作為澄清問題逐個拋回用戶(一次一問、帶候選),絕不把推斷的部門/owner/依賴當已確認填表——這一步天然誘導你一口氣列滿 owner 表,那等於替用戶拍板「誰是 owner、哪層要改」。
第 5 步:第一層澄清——定位(粗粒度)
拿《第一層 · 定位維度》當清單,逐條對照片段,把沒回答的維度列出來,按《互動式澄清規則》逐個問清。這一層定的是特性的形狀:它是什麼、歸哪層哪域、邊界在哪、什麼型態。一次只問一個問題。
把缺口分成兩類:
- 阻塞性缺口:不補就沒法繼續歸類或定義邊界(例如:服務於哪類角色、核心行為是什麼)。
- 非阻塞缺口:影響完整度但不影響主幹(例如:某個邊緣錯誤碼、文件形式)。
第 6 步:第二層澄清——功能細節(細粒度)
定位清楚後,特性的形狀已知,但研發還不能動手——因為還不知道它「具體怎麼動」。這一層用《第二層 · 功能細節維度》深挖行為規格:正常流程怎麼走、有哪些狀態、異常怎麼處理、邊界場景怎麼辦、參數取值多少。
第二層的提問要因特性類型而異:導覽類要問路徑與到點邏輯,感知類要問誤檢與置信度,資料類要問 schema 與量級。具體的分類型提問庫見 references/detail-probes.md——先判斷這個特性屬於哪個原型,再調對應的探針清單。
第 7 步:產出特性需求文件(含產品原則自檢 gate)
阻塞性缺口補齊後,先過產品原則自檢 gate,再按《輸出模板》產出。
模板選擇: 純二開單層、缺口少的小特性走精簡模板(《一句話定義》《來源背景》《能力定位》《範圍邊界》《故事+MVP》《行為規格》《介面契約》《依賴》《影響評估》《產品原則自檢(一行結論)》《決策記錄》《遺留待確認》,跳過《跨層實現與跨部門協同》和大部分按需 NFR);跨實現層或重大特性走完整模板。兩者共用同一套必答項與 DoR。
產出前必過:產品原則自檢 gate。 取配置區《D. 產品原則》(未填則用 references/product-principles.md 的內建預設 10 條),對照本特性逐條給三態結論:✓符合 / ⚠違背-有取捨 / —不適用。三態判定細則、常見紅旗清單、衝突優先級見 references/product-principles.md。任一條 ⚠ 必須在《產品原則自檢》節寫清取捨,並在《關鍵決策記錄》節落一行(來源標「產品原則衝突取捨」,註明第幾條);全 ✓/— 的輕量特性可把自檢壓成一行結論,不必舖空表。
gate 不是 skill 自己打勾通過,而是把不達標項轉成澄清問題或
[待確認]拋回用戶。 凡涉及取捨(要不要為相容犧牲某能力、預算超了砍哪個、危險動作要不要加權限門),必須按《互動式澄清規則》一次一問、帶候選,拋回用戶拍板。
DoR 硬性要求:
- 任一原則標 ⚠ 而文件裡找不到對應取捨說明 + 決策記錄 → 不過 DoR,不得標「研發可接手/待評審」。
- 第 4 步驟層級觸底結論為 B/C,而《一句話定義》或 P1 仍承諾下層未就緒的完整能力 → 不過 DoR(必須先按第 4 步第 5 小點回寫為真實可交付物)。
通過 gate 後按選定模板生成文件,寫入標準輸出目錄 feature-specs/<特性名>/<特性名>.md(不是隻貼在對話裡;位置約定見《輸出模板》);仍未解決的非阻塞缺口放進《遺留待確認》節,對正文受影響欄位標 [待確認],絕不憑空編造。
兩層為什麼分兩個 pass: 一次對話問太多會讓人疲勞(見澄清規則的總量上限)。建議第一層(第 5 步)問完先出一版「定位已定、行為待補」的草案,第二層(第 6 步)作為後續深挖 pass 再把行為規格補全、升級成研發級 v1.0。兩層各自遵守總量上限,互不擠佔。如果需求很小、缺口不多,也可以一口氣兩層跑完。
第一層 · 定位維度(粗粒度)
定特性的「形狀」。對照片段逐條檢查,缺失的就是要澄清的。分兩組。
A 組 · 需求本質(What / Why / 邊界)
- 角色與場景:誰在用?在什麼場景下觸發?(終端用戶 / 整合商開發者 / 運維…)
- 核心行為:這個功能具體做什麼動作?輸入什麼、產生什麼結果?
- 範圍邊界:包含什麼、明確不包含什麼(這一條最容易被忽略,也最能防止研發自行腦補範圍)。
- 成功判據:怎樣算「做對了」?用什麼可觀測的指標衡量?
B 組 · SDK 工程定位
- 能力層級歸屬:落在 L1 / L2 / L3 哪一層?
- 五域定位:屬於哪個能力域?是否跨域?跨域會牽動誰?
- 介面影響面:需要新增/修改哪些介面?是否衝擊 API 預算上限?
- 底層依賴:依賴哪些已有能力、哪些尚不存在需要先建?
- 適用型態:模擬、真機,還是兩者都要?兩者的驗收判據可能不同。
- 整合商可用性:目標是哪一級整合商能用?對應的封裝/文件複雜度不同。
- 向後相容:是否會破壞現有介面約定?是否需要版本化或遷移路徑?若判定會 break,需順便問清受影響的存量整合商/版本範圍與可接受的棄用週期,不能只記一句「是否 break」。
- 文件與認證影響:是否需要新的開發者文件?是否進入整合商認證考核範圍?
- 安全與權限(含物理改裝):這個能力對哪一級整合商/角色開放?是否涉及危險或高權限動作?安全風險有兩類,都要強制問一次、不得預設放開——
- 危險軟體呼叫:解鎖速度/力矩上限、解除急停、直接底盤/關節控制、越過安全圍欄 → 問「誰有權調、是否需二次確認/審計/權限門」。
- 危險物理改裝(硬體末端/改裝類特性,原型 J):客戶把自製硬體接到會運動、會傷人的機器人上 → 問 承重/力矩/供電紅線與超限後果、禁改區(哪些介面動了會解除急停/安全機制)、改末端後是否需負載重標定、改裝授權/資質門檻、保修與責任邊界、免責與合規宣告、資料開放範圍(角色分級/門控)。給錯一個物理紅線數字 = 人身安全 + 法律責任。
第二層 · 功能細節維度(細粒度)
定特性「具體怎麼動」。這是讓需求真正達到研發級的關鍵——下面每一條不定清,研發動手時都得自己拍腦袋。這些是通用維度,對照特性類型從 references/detail-probes.md 取分類型探針來具體提問。
- 正常流程分步:把核心行為拆成有序步驟,每步的輸入、輸出、前置條件分別是什麼。
- 狀態與生命週期:有哪些狀態?狀態機怎麼轉?
start / pause / resume / stop / cancel各自的語義、各狀態下允許哪些操作。 - 觸發與前置條件:什麼條件下能啟動?對系統/資源的前置要求?重複觸發、併發觸發怎麼處理。
- 異常與失敗處理:列出每一步可能的失敗點,逐個定對策——重試 / 降級 / 中止 / 上報,以及由誰善後、狀態如何收尾。
- 邊界與邊緣場景:空輸入、極值、中途打斷、資源不足(電量/算力)、外部條件突變時的行為。
- 參數細則:每個可配置項的單位、取值範圍、預設值、非法值如何校驗。
- 時序與效能約束:響應時間、超時閾值、吞吐、即時性要求。
- 併發與可重入:能否並行多實例?呼叫方多次呼叫同一介面怎麼辦?
- 可觀測性:呼叫方需要哪些狀態查詢、事件/回呼、日誌或指標,才能感知特性的執行情況。可觀測性分兩層都要問——面向呼叫方(狀態查詢/事件回呼/可定位日誌,服務整合商感知執行狀態)與面向平台運營(上線後用哪些指標/埋點判斷這個特性健康度、被採用率、失敗分佈,服務排障與決策),後者常被漏掉。
不必把 9 條全部問完才罷休。判斷哪些對這個特性是關鍵的(異常處理對長時任務幾乎總是關鍵,參數細則對純查詢類可能很輕),抓關鍵的問,其餘合理留預設或打
[待確認]。
三條正交的軸,疊加使用: 上面九維 + detail-probes 的「特性原型 A~J」是按特性類型切的一條軸(H = 生態整合/參考實現/文件類;I = 打包/分發/離線安裝/部署類;J = 硬體末端/物理介面規格與改裝資料類,對外契約是機械/電氣物理介面);某特性還要不要跨實現層分解(動了二開層以外的層,含「文件入口層 / 建置·分發基建層」兩類非執行時層,以及外部依賴/EOL 軸)是第二條軸,見第 4 步與
references/cross-layer-routing.md;有哪些非功能性需求(NFR) 與產品原則要過是第三條軸,見references/product-principles.md。三者不互相替代,命中即疊加。
互動式澄清規則
這是把「簡單」變「完整」的引擎,務必遵守:
- 一次一個問題。 問完一個,停下,等用戶回答,再問下一個。不要一次甩出一串問題。
- 阻塞優先。 先問阻塞性缺口(角色、核心行為、範圍邊界、能力歸屬),再問非阻塞的。
- 每個問題都帶「為什麼問」和候選答案。 形如:「這個功能主要服務於哪類角色?(這決定了它該封裝到哪一層)A. 終端用戶直接用 B. 整合商二次開發用 C. 內部測試用」。給候選答案能大幅降低回答成本,用戶也可以選「以上都不是」並補充。
- 控制總量,防止疲勞。 每一層單次對話儘量不超過 7~8 個問題(兩層各自計,互不擠佔)。如果缺口太多,先補齊阻塞性的,其餘打
[待確認]標記,告訴用戶「剩下的我先標記出來,你後續可以再補」。第二層細節問題尤其容易超量,挑對這個特性關鍵的問。 - 答完即複述確認。 用戶回答後,用一句話複述你的理解再繼續,確保沒聽岔。
- 絕不替用戶拍板。 涉及取捨的問題(做不做某個邊界、用哪種型態、誰是 owner、哪層要改)必須問,不能預設。把「還沒確認的」顯式標成
[待確認],而不是悄悄填一個看起來合理的值。
寫作與可讀性(產出必須做到)
需求文件是給人讀、要過評審的,不是把想到的點堆上去。產出前對照這三條:
- 說人話、邏輯連貫。 句子通順、段落有主線,別「想一塊寫一塊」地堆碎片。第一次出現的術語/縮寫,要麼就地一句點破,要麼收進《名詞解釋》——別讓讀者卡在生詞上。寧可多一句白話解釋,少一句行話。
- 總背景 + 角色分節 + 術語,三段式。 一份文件 = ① 總背景(所有人先讀:這是什麼、為什麼、給誰、交付什麼 =《一句話定義》+《來源與背景》+《名詞解釋》)+ ② 角色分節(《閱讀指引》把後續各節按閱讀對象分開,各角色只讀自己那塊,別讓某個團隊淹在跟他無關的細節裡)+ ③ 《名詞解釋》(術語單獨講清,面向看不懂的人)。
- 限對外交付型態、放開內部技術細節。 需求釘死「對外交付什麼」——介面簽名、產品型態、交付物形式、支援的平台/環境、驗收標準;但不過度規定「內部怎麼實現」——用哪個庫、什麼架構、哪種打包/編譯工具,留給研發。每寫一條問自己:「這是對外契約,還是內部實現?」是內部實現就改成「由研發定」或降級為「建議(非強制)」,別把需求寫成設計方案。
- 大白話是為了好懂,不是為了含糊——對外契約必須嚴謹。 行文用大白話,但凡涉及對外輸出標準的——介面定義(簽名/參數/返回/錯誤)、訊息與資料格式、支援的平台矩陣要逐格列全、交付物形式、驗收標準——必須精確、無歧義、可據以驗收,該給簽名給簽名、該逐行列矩陣就列全。通俗歸通俗,契約不能鬆。 按角色分章時,把這些嚴謹的契約集中在「對外契約」類章節,讓研發/測試能照著實現和驗證。
輸出模板
阻塞性缺口補齊後(且過了第 7 步產品原則自檢 gate),嚴格按此模板產出。模板內建一條 Definition of Ready——只有每一節都填實(或顯式標記 [待確認]),這份需求才算「研發能接手」。
約定:
- 節不再硬編號,統一按節名引用,避免插節後節號錯位。
- 精簡模板=去掉《跨層實現與跨部門協同》與按需 NFR 維度後的同一套節,給純二開單層小特性用;完整模板給跨層或重大特性用。
- 介面/參數命名全程遵循:全小寫底線(snake_case)、詞意完整準確、禁用縮寫(如
mic→microphone、cfg→config、num→count),並與同域既有介面保持一致。 - 一份文件只承載一個特性,且一個特性只出一份 md;多個特性各自獨立成文(絕不混寫),但一個特性哪怕跨層也不拆成多檔案——跨層/跨部門內容在同一份 md 內分閱讀對象成節。
- 產出落盤位置(標準輸出目錄,必須遵守):產出寫入檔案(不是隻貼在對話裡)——落到輸出目錄
feature-specs/<特性名>/<特性名>.md(相對當前工作目錄/倉庫根;預設根feature-specs/,團隊可在配置區改)。一個特性一個子目錄(便於放該特性的附圖/子產物),檔名 = 特性名。多個特性各自獨立子目錄;關聯特性之間用相對連結互指。 - 跨層(結論 B/C)特性:在本模板頂部加一張《閱讀指引(分閱讀對象)》,並在《跨層實現與跨部門協同》節把各層內容按【閱讀對象:X組】分節承載(模板見 references/cross-layer-routing.md《九》)——全部在這一份 md 內,不另拆檔案。
# 特性需求:[特性名稱]
> 狀態:草稿 / 待評審 / 已確認 | 提出方:[客戶/合作夥伴] | 日期:YYYY-MM-DD | 模板:完整 / 精簡
## 閱讀指引(分閱讀對象)
> **怎麼讀**:先讀**總背景**(《一句話定義》《來源與背景》《名詞解釋》,所有人都讀);其餘各節按下表**各讀各的**、不必讀全篇。跨層/跨部門特性務必填此表;純單層小特性表可精簡,但總背景與《名詞解釋》仍要有。
| 閱讀對象 | 重點讀哪些節 | 你負責什麼 |
| --- | --- | --- |
| 產品 / 評審 | 一句話定義、來源背景、能力定位、範圍邊界、故事+驗收、影響評估、產品原則自檢、決策記錄、遺留 | 確認範圍/優先級/取捨 |
| 二開 SDK 組 | 介面契約、行為規格、《跨層實現與跨部門協同》·二開節 | 對外封裝與介面契約 |
| 韌體組 | 《跨層實現與跨部門協同》·韌體節、層間交接契約 | 確認/開放下層能力介面 |
| 演算法組 | 《跨層實現與跨部門協同》·演算法節 | 演算法能力就緒/適配 |
| 硬體組 | 《跨層實現與跨部門協同》·硬體節 | 硬體型態/物理邊界 |
| 測試 / QA | 驗收標準、對外契約(介面/訊息/平台矩陣)、待確認 | 照驗收標準與契約設計測試、覆蓋全平台矩陣 |
(角色**按特性類型選**:執行時特性=各實現層;交付/整合/安裝類=打包·DevOps/文件/測試 等。**測試/QA 始終作為一個角色納入**——它關心驗收怎麼測、要覆蓋哪些平台、對外契約是否可測。不涉及的角色整行刪去。**正文儘量按角色分章**,讓每個角色能整塊讀自己那部分。)
## 一句話定義
[What —— 這個特性做什麼,一句話講清。⚠ 若第 4 步層級觸底結論為 B/C,這裡只寫本輪真實可交付物,不寫下層未就緒的完整能力]
## 來源與背景(Why)
- 原始訴求:[客戶/合作夥伴最初那句話,照原意保留]
- 業務場景:[誰、在什麼場景下、要解決什麼問題]
- 價值:[為什麼值得做]
## 名詞解釋(術語)
> 文件裡會用到、非本領域讀者可能看不懂的術語/縮寫,一詞一句白話講清(面向不同角色,別預設大家都懂);沒有生詞寫「無」。
| 術語 | 一句話說明 |
| --- | --- |
| … | … |
## 能力定位
- 層級:L1 / L2 / L3 [配置區 A 組未填則打 [待確認];**若為交付/分發/安裝/文件類非執行時特性則標 `N/A(非能力特性,僅落實現層軸)`**]
- 能力域:[五域之一,或「跨域:X + Y」,或 N/A]
- 跨域影響:[會牽動哪些其他域/團隊]
- 跨層結論(第 4 步):單層特性(二開 SDK) / ⚠ 非二開層可獨立交付:最底改動落在 <層>,需 <部門> 先交付 <能力>,二開層才能封裝
## 範圍邊界
- 包含(In Scope):
- …
- 明確不做(Out of Scope): ← 必填,防止研發誤擴範圍
- …
- 關聯特性佔位(來自需求分流、本輪不做):
- …
## 跨層實現與跨部門協同
> 僅當第 4 步判定本特性跨實現層(動了二開 SDK 層以外的層)時必填;純二開單層寫「單層特性(二開 SDK),無跨層協同」並跳過本節(精簡模板直接不含本節)。
> **產出型態:** 一個特性只出一份 md;本節承
…
[truncated for translation]