mk-spec-master · AI 規格大師 — 規格進、場景出

範圍

這「不」是什麼

mk-spec-master 站在規格來源跟測試 runner 之間。它不是編輯器、不是 runner、不是 LLM。

規格編輯器

→ Linear / JIRA / Notion / Markdown——規格寫在你原本就用的地方

測試 runner

→ mk-qa-master（pytest / Jest / Cypress / Go test / Maestro）

issue tracker UI

→ Linear / JIRA / Notion 各自的原生介面

spec → code 生成器

→ GitHub Spec Kit、AWS Kiro

LLM

→ 推理交給你的 AI client（Claude / Cursor / Codex / Gemini）

Tool 表

18 個 tool、分 7 個角色

按角色分組。每組是 spec → test → coverage → coach 流水線的一層。

Meta — 暖機

get_spec_source_info — 目前用哪個 adapter、有哪些可用——session 第一個叫

Discovery — 找跟讀規格

list_specs — 依 status / label / limit 過濾
fetch_spec — 依 id 拉單一 spec 完整內容
parse_spec — 啟發式抽 AC（en + zh-TW + zh-CN 標題格式），回傳 ac_hash

Generation — 規格變可測物件

extract_scenarios — AC → 場景，分 happy / edge / error
generate_test_plan — 一鍵 markdown 計畫，可直接餵 mk-qa-master

Coverage & drift — 追蹤層

link_test_to_spec — 記錄某 test 對應某 spec，存 title / source / ac_hash
auto_link_tests — 掃 test 檔抓 @spec: tag。Python / JS / TS / Go
get_coverage_matrix — 「哪些 spec 沒被測」一次回答
get_drift_report — fresh / drifted / unknown / stranded 四格

Coach — 品質 + 排序

analyze_spec_quality — 抓模糊用詞、實作細節洩漏、未定義角色
propose_spec_improvements — PM 可直接照做的 markdown 改寫建議
get_optimization_plan — 三層整合：覆蓋 + 品質 + drift

Knowledge — 領域知識

init_spec_knowledge — 起始 spec-knowledge.md（EARS、INVEST、AC 品質規則）
get_spec_context — 讀方法論檔，可選 section 過濾

Self-reinforcement — 跨時間自我強化（v0.4）

get_spec_history — 覆蓋 / 品質 / drift 的 trend：當下 vs ~7 天前 vs ~30 天前
get_drift_signature — 長期問題偵測：unstable / 長期低品質 / 長期沒 ac_hash
get_telemetry — 工具使用 log：熱門 tool、錯誤率、p50/p95、未被呼叫 tool。不記錄參數內容

來源 adapter

6 個來源、共用一組 tool

用 SPEC_SOURCE 環境變數切。同樣的工具，六種後端。

markdown_local

auth: 不用
since 0.1.0

github_issues

auth: gh auth login 或 GITHUB_TOKEN
since 0.1.0

linear

auth: LINEAR_API_KEY + SPEC_PROJECT_KEY
since 0.2.2

jira

auth: JIRA_BASE_URL + JIRA_EMAIL + JIRA_API_TOKEN
since 0.2.3

notion

auth: NOTION_TOKEN + database id 當 SPEC_PROJECT_KEY
since 0.3.0

figma

auth: FIGMA_TOKEN + file key 當 SPEC_PROJECT_KEY
since 0.3.1

工作流程

四個 prompt 涵蓋 ~90% 的真實用法

一句話給 AI client，工具自動串。

1.

"用 mk-spec-master 抓 LIN-123、抽場景、丟 mk-qa-master 產 Playwright 測試、跑起來、更新覆蓋矩陣。"

fetch_spec → parse_spec → extract_scenarios → mk-qa-master.generate_test (×N) → link_test_to_spec (×N) → mk-qa-master.run_tests → get_coverage_matrix

2.

"把所有 in-progress 的 spec 都做品質檢查，給我優先級改善計畫。"

list_specs(status='in-progress') → analyze_spec_quality → propose_spec_improvements → get_optimization_plan

3.

"我剛重新命名一堆 test 檔——掃 source tree 把 spec ↔ test 索引重建一次。"

auto_link_tests → get_coverage_matrix

4.

"進規格工作前：把 spec-knowledge 方法論載入，告訴我目前用的是哪個 source。"

get_spec_source_info → get_spec_context

範例輸出

你實際會拿到什麼

兩個最常 show 給人看的輸出——markdown 直接 paste 進 Slack / JIRA / sprint planning doc 都能用。

get_optimization_plan

# Optimization plan

_Coverage matrix: 23 spec(s) tracked, 4 untested._
_Spec quality: 23 spec(s) analyzed, 17 finding(s)._
_Drift: 2 drifted, 0 stranded, 5 without ac_hash._

## 🔴 Layer 1 — 覆蓋缺口

**零測試的規格**（先看這些——所有業務風險都藏這裡）：
- `LIN-204` — Apply promo code at checkout
- `LIN-211` — Refund flow

## 🟡 Layer 2 — 規格品質

### `LIN-098` — Checkout latency  (score: 80/100, findings: 4)
- 🟡 `ac-1`: 量化（例如 'response within 200 ms'）  (evidence: `fast`)
- 🔴 `ac-3`: 改寫成使用者能觀察到的行為  (evidence: `redis`)

## 🔵 Layer 3 — 流程飄移

**Drifted**（規格在 link 之後改過——回頭看哪些 test 過期）：
- `LIN-123` — Apply discount at checkout · 4 個 test 可能 stale

get_coverage_matrix

# 覆蓋矩陣

- 追蹤的 spec 數：23
- 顯示中（min_tests=0）：23
- 零測試 spec：4

| Spec      | 標題                            | 測試 | 最後狀態 |
|-----------|--------------------------------|------:|---------|
| `LIN-204` | Apply promo code at checkout   |     0 | —       |
| `LIN-123` | Apply discount at checkout     |     4 | passed  |

加進 MCP client config

重啟 client，然後就用你平常跟 AI 對話的方式講就好。

{
  "mcpServers": {
    "mk-spec-master": {
      "command": "uvx",
      "args": ["mk-spec-master"],
      "env": {
        "SPEC_SOURCE": "markdown_local",
        "SPEC_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

看完整文件 → 姐妹專案 → mk-qa-master

規格進。場景出。