Communitygithub.com

flriancu/claude-code-setup

啟動新專案、工具、功能、設計或調查工作,先進行需求釐清,撰寫一份 REQUIREMENTS.md 合約與階段性計畫,然後依指示逐階段執行。

claude-code-setup 是什麼?

這個技能(skill)專為需要結構化初始階段的 AI 代理(如 Claude Code)設計。它的核心是避免一次性猜測式建構(one-shot build),改以「先釐清、後執行」的合約式開發流程。當使用者啟動一個開放式任務(例如新腳本、應用程式、硬體啟動、文件轉換),或明確要求「需求釐清」、「提出釐清問題」時,此技能會引導代理進行:快速閱讀現有資訊 → 提出編號問題(附推薦預設值)→ 撰寫 REQUIREMENTS.md 合約(包含目標、功能需求、非功能需求、驗證方法)→ 撰寫階段性計畫(PLAN.md)→ 每次僅執行一個階段。它支援多種平台(Claude Code 等),並特別處理決策記錄、變更追蹤、錯誤回報與最終缺口檢查。此技能適用於任何需要邊做邊調整的軟體工程或設計調查任務。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/flriancu/claude-code-setup/tree/HEAD/plugins/flriancu/skills/requirements-kickoff

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

需求啟動會議

使用者預先明確且低成本地做出決定,然後在經過審查的步驟中逐步建構。一次性建構會將猜測固化,日後還得花力氣拆解。另一方面,在沒有任何書面文件前長時間沉默思考同樣令使用者反感(「不需要一次搞定,為什麼想那麼久?我們先起草一份包含階段的文件吧。」)。因此,快速將問題和計畫寫在紙上,讓使用者來主導方向。

1. 快速蒐集

  • 閱讀已提供的內容:檔案、資料夾、連結、圖片、先前的對話與記憶筆記、儲存庫的 README。記錄哪些事項已經決定,以免重複詢問。
  • 如果仍有輸入尚未提供(例如「連結稍後送上」、「照片之後會到」),仍先開始提問,並標記哪些問題依賴於該輸入。
  • 目前還不要撰寫程式碼或修改檔案。也不要長時間思考:問題本身就是思考的工具。

2. 提出編號問題

  • 一個編號清單,當問題很多時可按主題分組。每個問題一行,並附上您看到的選項以及您建議的預設值,例如: 3. 安裝位置:C: 或 D:?建議:D:,因為 C: 幾乎已滿。
  • 使用者會用編號簡潔回答(例如「1. 兩者 2. 更新至最新 3. 可以」)。仔細對應每個答案。「可以」或「同意」表示接受您的預設值;「前者」和「後者」指的是您選項的順序;跳過編號表示「由您決定,請告訴我您選擇了什麼」。
  • 涵蓋對此工作重要的事項:目標與受眾;範圍與明確的非目標;輸入與輸出(格式、位置);限制條件(平台、允許或禁止的工具、授權、離線使用、硬體);品質標準與驗收測試(「我們如何知道它有效?」);失敗行為(每個部分在任何時刻失敗時會發生什麼:當機、連線中斷、斷電、多個節點中的一個故障);忠實度(哪些內容絕不可更改);存放位置(儲存庫、路徑、遠端);交付(誰接收什麼、多久一次)。
  • 僅針對那些引發了新問題的答案,進行第二輪較短的提問。一旦剩餘的未知事項有了安全的預設值,就停止提問,並列出這些預設值。

3. 撰寫合約:REQUIREMENTS.md

將此檔案放在專案根目錄(如果專案是新的,則建立該資料夾)。保持內容簡潔、簡短並標明日期:

# <專案名稱> 需求

同意日期:<YYYY-MM-DD>。本檔案即為合約;任何變更均在此記錄並附上日期。

## 目標
## 受眾與用途
## 範圍
## 非目標
## 決策
- D-01 <決策> (<日期>)
## 功能需求
- FR-01 ...
## 限制條件與非功能需求
- NFR-01 ...
## 驗證
每個需求一行:說明如何驗證以及證據存放位置。
| ID | 方法(測試 / 檢查 / 分析 / 展示) | 證據(測試案例、腳本、檔案) |
## 未解決問題

穩定的 ID(D-xx, FR-xx, NFR-xx)讓後續的工作、提交和報告可以引用它們。使用使用者自己的說法記錄他們的答案;不要將其轉述得更強或更弱。

為每個需求指定驗證方法和證據位置。這四種方法是需求工程中的標準方法(ISO/IEC/IEEE 29148)。優先使用測試。當需求只能透過檢查或分析來驗證時(例如「無直接 OS 執行緒呼叫」、「每個節點的排程開銷低於 100 微秒」),請將檢查撰寫為一個腳本,該腳本將其輸出儲存為證據,以便證據可以重新執行,而不是重新爭論。

4. 撰寫計畫:階段

將此檔案放在需求檔案旁邊,檔名為 PLAN.md;如果專案較小,也可以放在「階段」章節中。階段 0 通常是用於設定,或是用於證明最風險假設的先導專案。對於每個階段,請說明目標、步驟、交付物、如何驗證,以及它所服務的需求 ID。保持每個階段足夠小,以便能一次性審查完畢,並說明計畫將在過程中調整。

然後停止。用幾行文字報告這兩個檔案,並建議第一個階段。

5. 依要求執行,一次一個階段

  • 僅執行使用者指定的階段(例如「執行階段 0」、「執行階段 0 和 1」、「開始」)。
  • 在每個階段結束時,報告已完成的事項、證明其有效的證據(執行的指令、輸出、測試結果)、與計畫的偏差及原因,以及下一步要做什麼。在計畫中將該階段標記為已完成。
  • 「進度檢查」表示:當前階段、已完成事項、正在執行事項、受阻事項。
  • 新的期望若改變了範圍,在您開始建構之前,需將其寫入 REQUIREMENTS.md 並附上日期。被推翻的決策記錄為一次逆轉;舊行仍保留。
  • 在使用者指示的情況下,修復沿途發現的錯誤;否則僅列出它們。
  • 當最後一個階段完成,或使用者要求時,執行一次缺口檢查:比對需求與程式碼、測試、文件及證據。每個缺口都需報告其需求 ID,依要求逐個修復,並重新執行證據腳本。
  • 不要在每個步驟後都提交或推送。當一個階段完成時提議一次提交;僅在要求時才推送。

變體

  • 無程式碼的決策(例如採購、工具選擇):相同的問題,然後根據商定的標準進行簡短的比較,取代那兩個檔案。
  • 他人的內容(例如作者的書籍、客戶的資料、錄音):事先增加一個忠實度需求。內容不得在未經通知的情況下被更改;每次變更都必須提出、標記並報告以待批准。

相關技能