Communitygithub.com

Speccanvas

產生與維護 Spec Canvas 規格文件，可輸出為可攜式 YAML 檔案，或透過設定的 MCP 伺服器進行持久化儲存。

Speccanvas 是什麼？

此技能專為 AI 代理（如 Claude Code、Cursor、Codex）設計，用於建立與維護「Spec Canvas」規格文件。其核心理念是規格應作為產品意圖與實作之間的輕量橋樑，專注於捕捉語意層面的變更，而非瑣碎的實作細節。支援 UI 規格與資料規格兩種文件類型，並可透過 MCP 伺服器進行專案、文件、版本與實作狀態的管理。 該技能強調「規格優先」的工作流程：當需求改變產品的語意結構、使用者旅程或領域模型時，優先更新規格再進行實作；而對於單純的外觀或佈局微調，則直接修改程式碼，無須更動規格。技能內建嚴格的「粒度閘門」，協助判斷哪些變更應納入規格。 技能支援多種工作模式，包括可攜式 YAML 規格（適用於 Git 儲存庫、IDE 或終端機代理）以及透過 MCP 伺服器進行的即時協作。提供完整的 YAML 格式定義檔案、JSON Schema 與驗證腳本，確保產出文件的結構正確性與一致性。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add riffi/speccanvas-skills
查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

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

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

Speccanvas 是做什麼的？

使用此技能來產生與維護 Spec Canvas 工件，可輸出為可攜式 YAML 規格，或透過已設定的 SpecCanvas MCP 伺服器進行持久化儲存。

將規格視為結構與意圖的真理來源。傾向於精簡、可重複使用的規格，這些規格無需額外說明即可直接貼入 Spec Canvas、IDE、終端機代理或儲存庫中使用。

以此技能中的 format-description YAML 檔案作為撰寫指南。使用此技能中捆綁的 JSON Schema 副本以及本機驗證邏輯作為最終檢查。

核心理念

Spec Canvas 規格是產品意圖與實作之間的精簡橋樑。它們應幫助代理與人類在程式碼變更之前就產品樣貌達成共識，但不應成為每個 CSS、佈局或元件微調的執行日誌。

  • UI 規格描述意圖與結構。 捕捉畫面、主要區塊、導航、關鍵使用者任務、重要狀態以及有意義的回應式結構。
  • 資料規格描述邏輯領域。 捕捉實體、欄位、列舉、關係與領域限制；避免提及實體資料庫或框架細節。
  • 規格優先原則適用於語意變更。 當請求改變產品意義、使用者旅程或領域結構時，應先更新規格再進行實作。
  • 實作微變更可跳過規格。 如果請求僅是外觀、佈局調整或對使用者不可見，則直接修改實作，無需更動規格。
  • 精簡的規格才是好規格。 傾向於用簡短的用途說明來解釋畫面/區塊存在的原因，而非描述其建構方式的實作細節。

粒度閘門

在編輯 UI 規格之前，先判斷請求的變更是否具有足夠的語意重要性，從而應納入規格中。

當請求改變以下項目時，更新 UI 規格：

  • 畫面、畫面群組或主要區塊；
  • 使用者旅程、導覽、進入點或可用操作；
  • 重要的面向使用者的狀態、模式、權限，或空白/錯誤/復原流程；
  • 主要元件的用途或行為；
  • 有意義的回應式結構，例如明顯不同的桌面/行動體驗；
  • 產品術語或標籤，當其意義改變時；
  • 公開、管理、編輯、玩家、入門等產品區域之間的邊界。

不要因實作微調而更新 UI 規格：

  • 間距：padding、margin、gap、line-height；
  • 確切尺寸：像素值、font-size、width/height，除非它們表達高階佈局意圖；
  • CSS 類別、Tailwind 類別、元件名稱、檔案名稱或特定框架的結構；
  • 確切顏色、漸層、陰影、border-radius、圖示或裝飾性樣式；
  • 在已描述的區塊內的局部對齊、排序、換行或外觀重新排列；
  • 動畫時序、防反彈時序、淡入淡出秒數、toast 位置、載入轉動指示器機制；
  • 瀏覽器/平台實作細節，除非是核心面向使用者的功能；
  • 不改變意義的局部文案編輯；
  • 對使用者不可見的重構。

如果使用者要求的是外觀或佈局微調，請直接進行程式碼變更，並明確避免觸碰 UI 規格。

預設檔案放置位置

除非使用者明確要求不同的位置，否則請在專案根目錄下的 spec/ 目錄中建立與更新 Spec Canvas 檔案。

  • UI 規格路徑：spec/ui-spec.yaml
  • 資料規格路徑：spec/data-spec.yaml

如果 spec/ 目錄不存在，請建立它。當僅要求一個工件時，只建立相關的檔案。

MCP 模式

當使用者要求與即時的 SpecCanvas 專案、文件、修訂版、實作存檔進行協作，或環境中明確存在 MCP 工具時，使用名為 speccanvas 的已設定 MCP 伺服器。

  • 如果 MCP 可用，請在建立或更新即時 SpecCanvas 資料之前先閱讀 references/mcp-workflow.md。
  • 如果任務是建立或更新 UI 規格，也請閱讀 references/ui-spec-workflow.md。
  • 如果任務是建立畫面實作，也請閱讀 references/implementation-workflow.md。
  • 如果 MCP 不可用，請不要憑空發明連線細節。請使用可攜式 YAML 檔案，或要求使用者設定 speccanvas MCP 伺服器。
  • 請勿將 MCP URL、Bearer Token、暫存主機或本機機密儲存在此技能中。這些應屬於代理的 MCP 設定與環境變數。

MCP 模型身分規則

當透過 MCP 儲存代理編寫的畫面實作時，請始終提供穩定的模型身分，格式為 { identityKey, provider, model, version }。

  • 在呼叫 add_implementation 之前，從全域代理規則、環境變數或當前工作階段解析作用中模型。
  • 對於 add_implementation，直接傳遞 modelIdentity。請勿將其替換為 agentName。
  • agentName 僅是手動/舊版後備方案。僅在實作由人類上傳或模型身分故意無法使用時，搭配 modelIdentity: null 使用。
  • 如果作用中模型未知、不明確或未註冊，請停止並要求澄清，而不是在 agentName 下默默儲存。

工作流程

  1. 界定工件邊界。 判斷任務需要：

    • 僅 UI 規格
    • 僅資料規格
    • 兩個規格
    • 對現有規格進行說明、審查、清理或驗證
    • 完全不需要變更規格，因為請求是實作微調
    • 對專案、規格、修訂版、實作或存檔進行即時 MCP 持久化

  2. 應用粒度閘門。 對於 UI 工作，判斷請求是否變更產品意圖/結構，或僅變更實作細節。如果只是微調，則保留現有規格。

  3. 收集來源材料。 僅使用定義結構的輸入：

    • 產品構想或功能請求
    • 現有螢幕截圖或 UI 描述
    • 程式碼庫結構
    • 目前的 YAML 規格
    • 實體列表、API 筆記或領域規則

  4. 閱讀所需的工作流程與格式參考資料。

  5. 草擬或修訂規格。 保持文件為有效的 YAML，並停留在格式欄位內。除非格式明確允許，否則不要發明自訂的頂層區段。進行最能保留意圖的最小語意更新；不要用像素級實作註解來擴充規格。

  6. 驗證結果。 如果 scripts/validate-spec.mjs 可用，請在傳回結果之前對最終的 YAML 執行該腳本。在傳回規格之前修正驗證錯誤。

  7. 傳回結果。 傳回驗證過的 YAML，或者對於審查任務，先列出問題，然後再提供修正後的片段或檔案。

核心規則

使用格式檔案作為撰寫來源

格式描述的 YAML 檔案是此技能的主要編寫參考。請優先遵循它們的結構、欄位命名、範例與指引。對於 UI 規格，references/ui-spec-format-0-0-3.yaml 是當前的本機真理來源，並應與捆綁的 Schema 和驗證器保持一致。

使用 Schema 驗證作為最終檢查

Schema 驗證不是撰寫指南。它是最後的驗證步驟。

  • 從格式檔案撰寫規格。
  • 使用 scripts/validate-spec.mjs 驗證已撰寫的規格。
  • 在傳回最終的 YAML 之前，修正 Schema 和驗證規則的失敗。

schemas/ 中捆綁的 Schema 應與 Spec Canvas 實作以及此技能中的格式描述參考保持同步。如果它們看起來不一致，請將其視為技能錯誤，並明確指出，而不是默默發明妥協方案。

保持 UI 與資料一致

當兩個規格都存在時：

  • 匹配畫面、實體和操作之間的命名
  • 確保 UI 操作暗示真實的實體或工作流程
  • 確保資料規格關係支援 UI 結構
  • 指出差異，而不是默默發明後端概念

保持格式的可攜性

產出純 YAML 檔案，使其可以存在於儲存庫中並被任何代理重複使用。請勿讓規格依賴於 Spec Canvas UI 狀態、隱藏元數據或僅限於聊天的假設。

保持 UI 規格高於實作細節

請勿將 UI 規格用作 CSS、元件文件或變更日誌的替代品。好的 purpose 是從使用者的角度解釋畫面或區塊的用途。它不應列舉確切的間距、類別名稱、像素大小、暫時的實作機制或每個小型控制項，如果這些細節不改變產品意義的話。

任務模式

建立新的 UI 規格

  • 從 docType、format_version 和 metadata 開始。
  • 在 UI 規格中，metadata.description 是必填的，應承載頂層產品意圖。
  • 一旦主應用程式樣貌確定，立即加入 screens。
  • 當使用者想要可見結構時加入 blocks；在探索階段可以省略 blocks。
  • 僅在它們實質上有幫助時加入 templates、navigation 或回應式欄位。
  • 當前本機格式支援的 UI 回應式編寫包括 metadata.breakpoints、自適應 screen.template、自適應 block.columns 和 block.visible。
  • 保留原始格式檔案的慣例，包括 UI 格式檔案中的引號指引。
  • 在可用時使用 scripts/validate-spec.mjs 驗證完成的檔案。

建立新的資料規格

  • 描述邏輯領域模型，而非實體資料庫。
  • 僅在共享控制詞彙重要時加入 enums。
  • 使用具有業務意義的 fields 定義 entities。
  • 使用 relations 來表達跨實體的邏輯結構。
  • 避免洩漏僅與實作相關的關注點，如索引、遷移或 ORM 特定的語法，除非使用者明確要求在規格之外使用它們。
  • 在可用時使用 scripts/validate-spec.mjs 驗證完成的檔案。

審查或修復現有規格

檢查：

  • 無效或不支援的欄位
  • 缺少必要的區段
  • 損壞的畫面、範本或導覽引用
  • 資料規格中的列舉、外鍵或關係錯誤
  • 由本機驗證規則引發的自訂驗證失敗
  • 原始格式檔案與當前本機實作之間的 Schema 格式不匹配
  • 描述實作機制而非產品意圖的過於詳細的 UI purpose 文字

修復時，保留原始產品意圖，並進行能恢復清晰度的最小修正。

壓縮過於詳細的 UI 規格

  • 除非產品結構真的改變，否則保持現有畫面、範本、區域和區塊 ID 穩定。
  • 將冗長的 purpose 段落替換為一句話的使用者面向意圖摘要。
  • 保留畫面、主要區塊、導覽、重要狀態和有意義的模式。
  • 移除 CSS/佈局微細節、平台怪癖、確切時序、日誌記錄行為和元件內部機制。
  • 避免整個檔案的 YAML 重新格式化；使用目標編輯，以便 diff 保持可審查性。
  • 編輯後進行驗證。

從現有應用程式重建規格

  • 從可見的工作流程推斷畫面
  • 從重複的區域和使用者任務推斷區塊
  • 從領域名詞和狀態變更推斷實體
  • 區分觀察到的和猜測的內容
  • 當來源材料不完整時，明確指出不確定性

驗證

在可用時使用 scripts/validate-spec.mjs。

  • 輸入：YAML 規格檔案的路徑
  • 從 docType 偵測文件類型
  • 針對此技能捆綁的 JSON Schema 進行驗證
  • 執行相關的自訂驗證規則
  • 將警告視為建議
  • 將錯誤視為最終輸出時的阻塞項（當您正在傳回修正後的規格時）

如果由於缺少本機 Spec Canvas 依賴項而無法執行腳本，請簡短說明，並回退到使用格式檔案和驗證規則參考進行手動審查。

輸出預期

當傳回規格時：

  • 提供有效的 YAML
  • 在格式預期的地方保持 ID 為 snake_case
  • 保持欄位名稱完全符合格式檔案的定義
  • 提及對結構有重大影響的假設
  • 提及是否已執行驗證

當傳回審查結果而不是重寫的檔案時：

  • 先列出結構性問題
  • 然後提供具體修正
  • 如果有的話，提供修正後的程式碼片段或完整規格

相關技能

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community