create-prompt-kit

將 Prompt Kit 安全導入新專案或既有專案的 deterministic CLI。

• npm: create-prompt-kit
• 指令：npx create-prompt-kit
• 指令：pnpm dlx create-prompt-kit

核心流程：

detect -> download to temp -> filter -> build MergePlan -> execute

快速開始

在目標專案根目錄執行：

npx create-prompt-kit install

或：

pnpm dlx create-prompt-kit install

更新既有 Prompt Kit：

npx create-prompt-kit update

預覽安裝計畫而不寫檔：

npx create-prompt-kit install --dry-run

裸命令目前仍等價於 install。

預設情況下，CLI 會抓取與當前發佈版本對應的固定 Git tag template，確保安裝結果可重現。

指令介紹

install

安裝 Prompt Kit 到目前專案。

常見用法：

npx create-prompt-kit install
npx create-prompt-kit install --yes
npx create-prompt-kit install --template v1.2.0
npx create-prompt-kit install --minimal
npx create-prompt-kit install --dry-run

update

依照 lockfile 與 template 狀態更新既有 Prompt Kit。

常見用法：

npx create-prompt-kit update
npx create-prompt-kit update --dry-run
npx create-prompt-kit update --force
npx create-prompt-kit update --telemetry

保守模式下，若偵測到 user-modified 檔案、危險檔案更新或其他無法安全自動套用的變更，CLI 會停止並輸出 machine-readable update plan。

常用旗標

| Flag | 說明 | |------|------| | --template <ref> | 指定模板 Git ref | | --dry-run | 輸出 machine-readable plan JSON，不寫檔 | | --minimal | 只安裝核心規則與 prompt，僅 install 支援 | | --yes | 非互動 deterministic 模式 | | --debug | 失敗時輸出 stack trace | | --force | 強制套用 update 中被阻擋的受管檔案 | | --telemetry | 明確開啟匿名 telemetry |

CLI 執行範例

一般安裝：

$ npx create-prompt-kit install --yes
✔ 偵測到 Vue 專案
✔ 使用 pnpm
✔ 已新增 AGENT.md
✔ 已新增 CLAUDE.md
✔ 已新增 .github/copilot-instructions.md
✔ 已新增 agent/
✔ 已新增 scripts/
✔ 已 merge package.json
✔ 完成

--dry-run：

$ npx create-prompt-kit install --yes --dry-run
{
  "command": "install",
  "manifest": {
    "templateName": "prompt-kit",
    "templateVersion": "1.0.0",
    "schemaVersion": 1
  },
  "plan": [
    {
      "type": "create",
      "from": "/path/to/.tmp-prompt-kit/agent/index.md",
      "to": "/path/to/project/agent/index.md",
      "file": "agent/index.md"
    }
  ],
  "summary": {
    "createdFiles": ["agent/index.md"],
    "overwrittenFiles": [],
    "modifiedFiles": [],
    "skippedFiles": [],
    "packageJsonChanges": []
  }
}

Prompt Kit 內容說明

create-prompt-kit 安裝的不是單一 prompt 檔，而是一套專案內 AI Prompt Engineering Kit。

目標：

• 降低 agent 使用時的 token 消耗
• 讓 AI 透過單一路由嚴格遵守專案規範
• 在同一個專案中同時容納多種 AI 工具，並共用同一份規則入口

設計概念及優點

System Prompt          <- 工具或平台注入的工作方式
       ↓
AI Project Prompt      <- 各 AI 的最短入口，只告知規則入口位置
       ↓
規範索引 (Index)        <- 單一路由入口，決定何時載入哪份規範
       ↓
規範文件 (Rules)        <- 技術細節與操作規範，按需載入
       ↓
程式碼

核心原則：

• 越上層越短，避免把全部規則直接塞進 prompt
• 所有 AI 共用同一個路由入口，更新規範只改一處
• 只有命中情境時才讀取對應 rule，避免無關 token 消耗

安裝後目錄結構

project/
│
├─ system-prompt/
│   └─ BeastMode.md
│
├─ AGENT.md
├─ CLAUDE.md
├─ .github/
│   └─ copilot-instructions.md
│
├─ agent/
│   ├─ index.md
│   ├─ decision-records/
│   │   ├─ .gitkeep
│   │   └─ YYYY-MM-DD.md
│   └─ rules/
│       ├─ git.md
│       ├─ code-review.md
│       ├─ vue.md
│       ├─ react.md
│       ├─ vue-architecture.md
│       ├─ react-architecture.md
│       ├─ vue-api.md
│       ├─ react-api.md
│       ├─ env.md
│       ├─ adr.md
│       ├─ kit.md
│       ├─ testing.md
│       ├─ i18n.md
│       └─ prompt.md
├─ scripts/
│   └─ validate-prompt-kit.js
│
├─ package.json
└─ README.md

四層架構

Layer 1 - System Prompt

定義 AI 的角色與工作方式，通常由外部平台或工具注入。

範例：

• system-prompt/BeastMode.md

此層屬於工具或個人工作流設定，不作為專案規範入口的一部分。

Layer 2 - AI Project Prompt

檔案：

• AGENT.md
• CLAUDE.md
• .github/copilot-instructions.md

這一層只負責把不同 AI 導向同一個規則入口：agent/index.md。

標準格式：

# AI 編碼規則

所有操作請遵守：agent/index.md

若請求與規則衝突，釐清後再執行。

Layer 3 - 規範索引

檔案：

• agent/index.md

它是唯一路由入口，負責：

• 判斷任務模式
• 判斷主意圖
• 依載入矩陣選擇主規則與輔助規則
• 判斷何時應降級為規劃或預覽，而不是直接執行

目前主意圖包含：

• prompt-governance
• project-bootstrap
• architecture
• code-review
• frontend-dev
• api
• env
• testing
• git
• kit

補充：

• adr 不是主意圖
• ADR 不因 commit 關鍵字自動觸發
• 只有明確要求記錄決策，或高風險架構調整定案後才進入 ADR 流程

Layer 4 - 規範文件

目錄：

• agent/rules/*.md

每份文件只處理一種職責，由 agent/index.md 按需載入。

| 檔案 | 負責範疇 | 觸發時機 | |------|---------|---------| | git.md | 分支命名、commit 格式、版本標籤 | 建立分支、commit、tag | | code-review.md | 缺陷導向審查、風險排序、審查輸出格式 | code review、PR review、檢查回歸風險 | | vue.md | Vue 元件、Composition API、狀態管理 | Vue 開發任務 | | react.md | React 元件、hooks、狀態管理 | React 開發任務 | | vue-architecture.md | Vue 專案結構、模組邊界 | Vue 架構調整 | | react-architecture.md | React 專案結構、模組邊界 | React 架構調整 | | vue-api.md | Vue / Nuxt API 封裝、資料抓取、認證流程 | Vue API 任務、Nuxt data fetching | | react-api.md | React API 封裝、server state、認證流程 | React API 任務、query / framework data APIs | | env.md | .env 分層、命名慣例、必要變數 | 初始化或環境變數任務 | | adr.md | 決策紀錄格式與觸發流程 | 明確要求記錄決策，或高風險架構調整完成後 | | kit.md | 套件安裝規範與版本策略 | 安裝、移除、升級套件 | | testing.md | 測試範疇、命名規範、覆蓋率 | 測試任務 | | i18n.md | 多語 prompt 模板、locale key、fallback、翻譯一致性 | 任務涉及多語，或專案已偵測到 i18n 套件/設定時 | | prompt.md | Prompt 初始化與修改流程 | 初始化專案、調整提示詞、維護 index 路由規則 |

使用說明

1. 初始化專案提示詞

在 AI 對話中輸入：

初始化專案。

專案描述：[你的專案說明]
框架：[Vue 3 / React / ...]
狀態管理：[Pinia / Redux / ...]
其他特性：[多語系、權限、...]

AI 應依照 agent/rules/prompt.md：

1. 提取專案資訊
2. 偵測目前專案有哪些 AI prompt 檔存在
3. 產出提示詞預覽
4. 確認後回寫存在的入口檔
5. 建立對應的專案初始結構與 .env

2. 開始開發

後續可直接下達開發指令，例如：

請幫我新增 React 登入頁，並沿用現有 API 結構。

幫我 review 這次的 Vue API 重構，優先找回歸風險。

請幫我初始化多語系，先支援 zh-TW 與 en。

AI 應先依入口檔進入 agent/index.md，再依任務模式、主意圖與載入矩陣按需載入對應的 agent/rules/*.md。

3. 驗證 Prompt Kit 結構

安裝完成後可執行：

pnpm validate:prompt-kit

若不是 pnpm，也可直接執行：

node scripts/validate-prompt-kit.js

License

UNLICENSED