ai-dev-cli 2.0.1 → 2.0.2

package/dist/index.js

@@ -288,7 +288,7 @@ function select(question, options, defaultIndex = 0) {
 }
 
 // src/commands/init.ts
-var VERSION = "2.0.0";
+var VERSION = "2.0.2";
 var DATABASE_OPTIONS = [
   "prisma-sqlite",
   "prisma-pg",
@@ -296,10 +296,10 @@ var DATABASE_OPTIONS = [
   "supabase-cn"
 ];
 var DATABASE_LABELS = {
-  "prisma-sqlite": "Prisma + SQLite      \u2014 zero-config local dev",
-  "prisma-pg": "Prisma + PostgreSQL  \u2014 traditional relational DB",
-  "supabase-cloud": "Supabase (Cloud)     \u2014 BaaS with auth/storage/realtime",
-  "supabase-cn": "Supabase (China)     \u2014 self-hosted for China region"
+  "prisma-sqlite": "Prisma + SQLite      \u2014 \u96F6\u914D\u7F6E\u672C\u5730\u5F00\u53D1",
+  "prisma-pg": "Prisma + PostgreSQL  \u2014 \u4F20\u7EDF\u5173\u7CFB\u578B\u6570\u636E\u5E93",
+  "supabase-cloud": "Supabase (Cloud)     \u2014 \u542B\u8BA4\u8BC1/\u5B58\u50A8/\u5B9E\u65F6\u529F\u80FD\u7684 BaaS",
+  "supabase-cn": "Supabase (China)     \u2014 \u56FD\u5185\u81EA\u6258\u7BA1\u65B9\u6848"
 };
 var DATABASE_CONFIGS = {
   "prisma-sqlite": {
@@ -366,11 +366,11 @@ async function runInit(options) {
     level = parseInt(options.level, 10);
   } else {
     console.log("");
-    console.log("Select initialization level:");
-    console.log("  0) Minimal    \u2014 CLAUDE.md + basic permissions");
-    console.log("  1) Commands   \u2014 + /plan /review /commit");
-    console.log("  2) Quality    \u2014 + Hooks automation");
-    console.log("  3) Full       \u2014 + MCP + Skills + docs");
+    console.log("\u9009\u62E9\u521D\u59CB\u5316\u7EA7\u522B\uFF1A");
+    console.log("  0) \u6700\u5C0F\u5316    \u2014 CLAUDE.md + \u57FA\u7840\u6743\u9650");
+    console.log("  1) \u547D\u4EE4\u5C42    \u2014 + /plan /review /commit");
+    console.log("  2) \u8D28\u91CF\u5C42    \u2014 + Hooks \u81EA\u52A8\u5316");
+    console.log("  3) \u5B8C\u6574\u7248    \u2014 + MCP + Skills + \u6587\u6863");
     console.log("");
     const input = await ask("Level [0-3]", "1");
     level = parseInt(input, 10);
@@ -432,10 +432,14 @@ function initLevel0(vars) {
   appendGitignore(".claude/memory.jsonl");
 }
 function initLevel1() {
-  info("=== Level 1: Core Commands ===");
-  safeWrite(".claude/commands/plan.md", loadTemplate("level-1/plan.md"));
-  safeWrite(".claude/commands/review.md", loadTemplate("level-1/review.md"));
-  safeWrite(".claude/commands/commit.md", loadTemplate("level-1/commit.md"));
+  info("=== Level 1: Core Skills ===");
+  const coreSkills = ["plan", "review", "commit"];
+  for (const skill of coreSkills) {
+    safeWrite(
+      `.claude/skills/${skill}/SKILL.md`,
+      loadTemplate(`level-1/${skill}.md`)
+    );
+  }
 }
 function initLevel2() {
   info("=== Level 2: Quality Gates (Hooks) ===");
@@ -466,16 +470,26 @@ function initLevel2() {
 function initLevel3(vars) {
   info("=== Level 3: Full System ===");
   safeWrite(".mcp.json", loadTemplate("level-3/mcp.json"));
-  safeWrite(".claude/commands/debug.md", loadTemplate("level-3/debug.md"));
-  safeWrite(".claude/commands/doc.md", loadTemplate("level-3/doc.md"));
-  safeWrite(
-    ".claude/skills/code-standards/SKILL.md",
-    loadTemplate("level-3/code-standards.md")
-  );
-  safeWrite(
-    ".claude/skills/spec/SKILL.md",
-    loadTemplate("level-3/spec.md")
-  );
+  const skills = [
+    "debug",
+    "doc",
+    "check",
+    "test",
+    "impact",
+    "code-standards",
+    "spec",
+    "retro",
+    "health-report",
+    "docaudit",
+    "takeover",
+    "ui-page"
+  ];
+  for (const skill of skills) {
+    safeWrite(
+      `.claude/skills/${skill}/SKILL.md`,
+      loadTemplate(`level-3/${skill}.md`)
+    );
+  }
   safeWrite("docs/approved-deps.md", loadAndRender("level-3/approved-deps.md", vars));
   const adrKeep = "docs/adr/.gitkeep";
   if (!import_node_fs4.default.existsSync(adrKeep)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-dev-cli",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "AI Dev Lifecycle — scaffold & audit tool for Claude Code projects",
   "bin": {
     "ai-dev-cli": "dist/index.js"

package/templates/level-0/settings.json.tpl

@@ -15,10 +15,10 @@
     ],
     "deny": [
       "Bash(sudo:*)",
-      "Bash(curl:*|*sh)",
-      "Bash(wget:*|*sh)",
+      "Bash(curl *|*sh)",
+      "Bash(wget *|*sh)",
       "Bash(rm -rf /)",
-      "Bash(git push:*--force*)",
+      "Bash(git push *--force*)",
       "Bash(git reset --hard)",
       "Bash(chmod 777:*)",
       "Read(.env)",

package/templates/level-1/commit.md

@@ -1,17 +1,36 @@
 ---
-description: "Smart commit — generate semantic commit message and execute"
-allowed-tools: Bash, Read
+name: commit
+description: >
+  智能提交。完成功能并通过审查后使用。
+  生成语义化的 commit message 并执行提交。
 ---
 
-Execute a smart commit:
+# 智能提交
 
-1. Run `git status` and `git diff --staged` to see changes
-2. If no staged files, `git add` relevant files individually (never use `git add .`)
-3. Analyze changes and generate Conventional Commits format message:
-   feat|fix|refactor|docs|test|chore(scope): description
+## 步骤
 
-Rules:
-- scope = module name or key part of file path
-- Description in English, under 50 chars, explain WHY not WHAT
-- Never commit .env or key files
-- If changes span more than 10 files, suggest splitting into multiple commits
+1. 运行 `git status` 和 `git diff --staged` 查看变更
+2. 如果没有 staged 文件，先 `git add` 相关文件（不要用 `git add .`）
+3. 分析变更内容，生成 Conventional Commits 格式的 message：
+   `type(scope): 描述`
+   - type: feat / fix / refactor / docs / test / chore
+   - scope: 取模块名
+   - 描述: 英文 50 字符以内，说明 why 而非 what
+
+## 提交前检查
+
+提交前确认以下全部通过：
+- `npm run lint` — 零警告
+- `npx tsc --noEmit` — 零类型错误
+- `npm run test` — 全部通过
+
+任何一项不通过，不允许提交。
+
+## 大变更处理
+
+如果变更超过 10 个文件，建议拆分为多次提交，按逻辑单元分组。
+
+IMPORTANT：
+- 不要 `git add .`，逐个添加相关文件
+- 不要提交 .env 或包含密钥的文件
+- commit message 用英文

package/templates/level-1/plan.md

@@ -1,16 +1,56 @@
 ---
-description: "Requirements analysis and plan design — produce a plan, wait for approval before coding"
-allowed-tools: Read, Grep, Glob, Bash
+name: plan
+description: >
+  需求分析与方案设计。当开始新功能或大改动时使用。
+  输出结构化的实现方案，等待人工审批后再执行。
 ---
 
-Analyze requirement "$ARGUMENTS" and design an implementation plan:
+# 需求分析与方案设计
 
-1. Use AskUserQuestion to confirm requirement details and boundaries
-2. Search the codebase for existing similar features or reusable modules
-3. Output the implementation plan:
-   - Overview (one sentence)
-   - Impact scope (new files, modified files, dependency changes)
-   - Implementation steps (specific to file and function level)
-   - Risk points and mitigations
+## 步骤
 
-IMPORTANT: After outputting the plan, you MUST wait for user confirmation. Do NOT start implementation on your own.
+1. **理解需求**（按规模分路径）
+   使用 AskUserQuestion 向用户确认功能行为、边界、是否有类似功能可参考。
+   - **小功能**（改动 < 3 文件，无新数据模型）：确认需求后直接进入步骤 2
+   - **中大功能**（跨模块/新数据模型/新 API）：如果已有 spec.md，直接基于它设计方案；如果没有，建议先运行 /spec。若用户选择跳过，追加结构化提问：
+     - 目标用户是谁？要解决什么问题？
+     - 核心用户故事（3-7 条）
+     - In scope / Out of scope
+     - 验收标准（每条用户故事的 Given/When/Then）
+
+2. **检查现有代码**
+   搜索代码库中已有的类似功能或可复用模块。
+   列出可复用的组件、工具函数、类型定义。
+
+3. **输出实现方案**
+
+   基础格式（所有功能）：
+
+   ```
+   ## 方案概述
+   [一句话描述实现思路]
+
+   ## 影响范围
+   - 新建文件：[列出]
+   - 修改文件：[列出，标注改动点]
+   - 依赖变更：[列出新增/移除的包]
+
+   ## 实现步骤
+   1. [步骤1 - 具体到文件和函数级别]
+   2. [步骤2]
+   ...
+
+   ## 风险点
+   - [可能出问题的地方及应对措施]
+   ```
+
+   中大功能额外在方案开头包含：
+   - **目标与非目标** + **用户故事与验收标准** + **范围边界**（精简 PRD）
+   - 当存在 API 变更时，先定义 API 契约（路径、方法、请求/响应 schema）
+   - 大功能附加实现顺序：Foundation（数据模型+类型）→ Core（业务逻辑）→ Integration（模块连接）→ Polish（错误处理+日志+文档）
+
+4. **等待确认**
+
+IMPORTANT：
+- 方案输出后必须等待用户确认，不要自行开始实现。
+- 本 Skill 负责需求分析与方案设计（产出方案文档）。代码级实现规划由 Claude Code 内置 Plan Mode 负责。典型流程：/plan → 审批 → Plan Mode → 审批 → 执行。

package/templates/level-1/review.md

@@ -1,19 +1,53 @@
 ---
-description: "Code review — focus on correctness, security, and edge cases"
-allowed-tools: Read, Grep, Glob, Bash
+name: review
+description: >
+  代码审查。完成功能实现后、提交前使用。
+  从正确性、安全性、性能三个维度审查最近变更。
 ---
 
-Review recent git changes:
+# 代码审查
 
-1. Run `git diff HEAD` to see changes
-2. Review dimensions:
-   - Correctness: logic, edge cases, null defense, async error handling
-   - Security: injection risks, input validation, sensitive info exposure
-   - Performance: unnecessary re-renders, N+1 queries, large list pagination
-   - Standards: compliance with CLAUDE.md rules
+## 步骤
 
-3. Output format — categorize by severity:
-   - **Must fix**: security vulnerabilities, logic errors, data loss risk
-   - **Suggested improvement**: code smells, missing error handling, perf issues
-   - **Minor suggestion**: naming optimization, style consistency
-   Each item includes: filename:line, problem description, fix suggestion
+1. 运行 `git diff HEAD` 或 `git diff main..HEAD` 查看所有变更
+2. 按以下清单逐项检查
+
+## 审查维度
+
+### 正确性（Must Check）
+- 逻辑是否正确，边界条件是否处理
+- 空值/undefined 是否防御
+- 异步操作的错误处理是否完整
+- 类型是否严格，有无隐式 any
+
+### 安全性（Must Check）
+- 用户输入是否做了校验（zod schema）
+- 是否有 SQL 注入、XSS 风险
+- 敏感信息是否暴露在响应或日志中
+- 文件上传是否校验了类型和大小
+
+### 性能（Should Check）
+- 是否有不必要的重复渲染（缺少 memo/useMemo）
+- 数据库查询是否有 N+1 问题
+- 大列表是否做了分页
+
+### 规范（Should Check）
+- 是否符合 CLAUDE.md 中的编码规范
+- 命名是否清晰、一致
+
+### 规格对照（当有设计文档时）
+如果存在 prd.md 或 API 契约：
+- 逐条检查验收标准是否都已实现
+- 对照 API 契约，检查接口定义（路径、方法、请求/响应 schema）是否匹配
+- 标记：Pass / Fail / Partial
+
+## 输出格式
+
+按严重程度分类：
+- **必须修复**：安全漏洞、逻辑错误、数据丢失风险
+- **建议改进**：代码异味、缺失错误处理、性能问题
+- **小建议**：命名优化、风格统一
+
+每条包含：文件名:行号、问题描述、修复建议。
+
+IMPORTANT：客观报告，不美化。没有问题就说"审查通过"，有问题就直说。

package/templates/level-3/check.md

@@ -0,0 +1,49 @@
+---
+name: check
+description: >
+  项目合规体检。随时可用，检查代码和配置是否符合体系规范。
+  脚本 check 的智能补充层，处理需要理解代码语义的检查项。
+---
+
+# 项目合规体检
+
+先运行脚本的基础检查（如果可用）：
+`./scripts/ai-dev.sh check 2>/dev/null || true`
+
+然后执行以下 AI 深度检查：
+
+## 1. CLAUDE.md 健康度
+- "架构" 章节是否与实际目录结构一致
+- "命令" 章节是否与 package.json scripts 一致
+- "常见陷阱" 中是否有过时条目
+- 指令条数接近 150 条时给出警告
+
+## 2. 代码规范深度检查
+- 抽查 5 个最近修改的 .ts/.tsx 文件：类型完整性、zod 校验、AppError 使用、裸 throw
+- 检查 services/ 函数是否有返回类型注解
+
+## 3. 依赖合规
+- 对比 package.json 与 docs/approved-deps.md，列出未在白名单中的依赖
+
+## 4. 测试覆盖评估
+- 对比 src/ 模块与测试文件，标出完全没有测试的核心模块（services/, app/api/）
+
+## 输出格式
+
+```
+## 体检报告
+
+### 合规项
+- [列出通过的检查]
+
+### 需要关注
+- [列出警告项，附具体位置和建议]
+
+### 必须修复
+- [列出违规项，附修复建议]
+
+### 建议
+- [可选的改进建议]
+```
+
+IMPORTANT：客观报告，不要美化。没有问题就说没有问题，有问题就直说。

package/templates/level-3/code-standards.md

@@ -1,37 +1,32 @@
 ---
 name: code-standards
 description: >
-  Coding standards guard. Automatically referenced during code generation.
-  Ensures TypeScript type safety, API input validation, unified error handling, and naming conventions.
+  编码规范守卫。任何代码生成请求时自动参考。
+  确保生成的代码符合项目约定的类型安全、错误处理和命名规范。
 ---
 
-# Coding Standards
+# 编码规范
 
-Check these rules before generating code:
+生成代码前强制检查以下规则：
 
 ## TypeScript
-- All functions must have complete type annotations — no `any`
-- Use named exports — no default export
-- Interface names without `I` prefix (use `User` not `IUser`)
+- 所有函数必须有完整类型注解，禁止 any
+- 使用 named export，禁止 default export
+- 优先使用 interface 定义对象类型，type 用于联合/交叉类型
 
 ## API Route
-- All inputs validated with zod schema
-- Unified response format: `{ data, error, meta }`
-- Errors use AppError class with error code
+- 所有输入用 zod schema 校验
+- 统一响应格式：`{ data, error, meta }`
+- 错误使用 AppError 类，不裸 throw Error
 
-## React Components
-- Functional components + hooks
-- Props defined as a separate type (ComponentNameProps)
-- State management priority: useState → useReducer → Zustand → Server State
+## React 组件
+- 函数式组件 + hooks，Props 定义为独立 type
+- 状态管理优先级：useState → useReducer → Zustand → Server State
+- 列表渲染必须有稳定的 key
 
-## Files
-- Single file ≤ 300 lines
-- File naming: kebab-case; Component naming: PascalCase
-- Test files colocated with source or in __tests__ directory
+## 文件结构
+- 单文件不超过 300 行，超出则拆分
+- 文件命名 kebab-case，组件 PascalCase
+- 新增代码优先参考项目中已有的同类实现
 
-## Template Reference
-| Scenario | Reference |
-|----------|-----------|
-| API Route | See existing implementations under /app/api/ |
-| Service | See existing implementations under /services/ |
-| Component | See existing implementations under /components/ |
+IMPORTANT：这些规则在任何代码生成时自动参考，不需要用户手动调用。

package/templates/level-3/debug.md

@@ -1,15 +1,44 @@
 ---
-description: "Bug diagnosis — systematically locate root cause"
-allowed-tools: Read, Grep, Glob, Bash, Edit
+name: debug
+description: >
+  问题诊断。当遇到 Bug、报错或异常行为时使用。
+  系统性定位根因，给出修复方案。
 ---
 
-Diagnose the problem: "$ARGUMENTS"
+# 问题诊断
 
-Steps:
-1. Collect info: read error logs, find related source code
-2. Check recent git changes: `git log --oneline -10`
-3. Trace the call chain upward from the error point
-4. Rank possible root causes by probability
-5. Output: root cause analysis + fix plan + verification method
+## 步骤
 
-IMPORTANT: If unsure about the root cause, say so explicitly. Do NOT speculatively modify code.
+1. **收集信息**
+   - 读取报错信息/日志
+   - 找到相关源代码
+   - 检查最近的 git 变更（`git log --oneline -10`）
+
+2. **定位根因**
+   - 从报错点沿调用链向上追踪
+   - 检查输入数据是否符合预期
+   - 检查是否有最近的代码变更引入了问题
+
+3. **验证假设**
+   - 阅读相关测试用例，确认测试是否覆盖了出错场景
+   - 如果有多个可能原因，按概率排序，逐一排查
+
+4. **给出修复方案**
+
+   ```
+   ## 根因
+   [一句话描述]
+
+   ## 修复方案
+   [具体修改内容]
+
+   ## 验证方法
+   [如何确认修复有效]
+
+   ## 防御措施
+   [如何防止类似问题再次发生]
+   ```
+
+5. **等待确认后执行修复**
+
+IMPORTANT：如果不确定根因，明确告知用户你的不确定性，不要猜测性地修改代码。

package/templates/level-3/doc.md

@@ -1,15 +1,31 @@
 ---
-description: "Check and update project documentation to stay in sync with code"
-allowed-tools: Read, Write, Edit, Glob, Bash
+name: doc
+description: >
+  文档更新。代码变更后使用，确保文档与代码同步。
+  检查并更新 CLAUDE.md、README、API 文档等。
 ---
 
-Check which docs need updating after code changes:
+# 文档更新
 
-1. `git diff --name-only` to see changed files
-2. Check:
-   - New module → update CLAUDE.md "Architecture" section
-   - New command → update CLAUDE.md "Commands" section
-   - New dependency → update docs/approved-deps.md
-   - Major decision → suggest creating an ADR in docs/adr/
-3. Execute necessary updates
-4. If no updates needed, say so explicitly
+## 步骤
+
+1. 运行 `git diff --name-only` 查看本次变更的文件列表
+
+2. 检查以下文档是否需要更新：
+   - 新增模块/目录 → CLAUDE.md "架构" 章节
+   - 新增命令/脚本 → CLAUDE.md "命令" 章节
+   - 新增/修改 API → README 或 API 文档
+   - 新增依赖 → docs/approved-deps.md
+   - 重大技术决策 → docs/adr/ 新增 ADR
+   - 环境变量变更 → README 或 .env.example
+
+3. 执行必要的更新
+
+4. 输出更新摘要：
+   ```
+   ## 文档更新摘要
+   - 已更新：[列出更新的文档及改动点]
+   - 无需更新：[说明为什么不需要更新]
+   ```
+
+IMPORTANT：只更新确实需要更新的文档，不要过度补充。没有需要更新的文档就明确告知。

package/templates/level-3/docaudit.md

@@ -0,0 +1,56 @@
+---
+name: docaudit
+description: >
+  文档体系审计。检查文档完整性、索引一致性和规范合规性。
+  当新增/修改/删除文档后使用，确保索引、CHANGELOG 和规范得到遵守。
+---
+
+# 文档体系审计
+
+## 步骤
+
+1. **索引一致性检查**
+   - 读取项目的文档索引文件（如 README.md 或 docs/ 下的索引）
+   - 扫描文档目录下所有 .md 文件
+   - 比对：索引中列出但文件不存在的条目 → 报错
+   - 比对：文件存在但索引中未列出的条目 → 报错
+
+2. **编号连续性检查**
+   - 提取所有文档的编号前缀（00, 01, 02...）
+   - 检查是否有跳号或重号
+
+3. **CHANGELOG 时效性检查**
+   - 读取 CHANGELOG.md
+   - 检查最新条目的日期是否为最近 7 天内
+   - 如果最近有 git 提交修改了文档目录下的文件，但 CHANGELOG 未更新 → 警告
+
+4. **文档行数检查**
+   - 统计每篇文档的行数
+   - 超过 500 行的文档 → 警告，建议拆分
+
+5. **交叉引用检查**
+   - 扫描文档中的内部链接
+   - 检查链接目标是否存在
+
+## 输出格式
+
+```
+## 文档审计报告
+
+### 通过
+- [列出通过的检查项]
+
+### 警告
+- [列出警告项，附具体位置和建议]
+
+### 错误
+- [列出必须修复的问题]
+
+### 统计
+- 文档总数：N 篇
+- 总行数：N 行
+- 平均行数：N 行/篇
+- 最长文档：[文件名]（N 行）
+```
+
+IMPORTANT：客观报告，不美化。有问题就直说，没有问题就确认通过。

package/templates/level-3/health-report.md

@@ -0,0 +1,52 @@
+---
+name: health-report
+description: >
+  项目健康度报告。定期使用（建议每两周），评估项目可靠性现状。
+---
+
+# 项目健康度报告
+
+执行以下检查并输出报告：
+
+## 1. 测试覆盖评估
+- 列出 services/ 下每个文件是否有对应测试
+- 列出 app/api/ 下每个 Route 是否有对应测试
+- 标注完全没有测试的模块
+
+## 2. 类型安全评估
+- 运行 `npx tsc --noEmit 2>&1 | head -50`
+- 搜索代码中的 `any` 类型使用
+- 搜索 `@ts-ignore` 和 `@ts-expect-error`
+
+## 3. 模块耦合评估
+- 检查是否有组件直接 import prisma
+- 检查是否有跨 Service 的直接调用
+- 检查调用方向是否符合 CLAUDE.md 中定义的架构
+
+## 4. 风险区域识别
+- 最近 30 次提交中修改最频繁的文件（变更热点 = 风险热点）
+  `git log --oneline -30 --name-only | sort | uniq -c | sort -rn | head -10`
+- 超过 300 行的文件
+- 有 TODO/FIXME/HACK 的文件
+
+## 输出格式
+
+```
+## 健康度报告 [日期]
+
+### 得分
+- 测试覆盖: [X/Y] 个核心模块有测试
+- 类型安全: [数量] 处 any / ts-ignore
+- 架构合规: [是否有违反模块边界的情况]
+- 变更热点: [最危险的 3 个文件]
+
+### 本期最大风险
+[一句话说明当前最大的可靠性风险]
+
+### 建议优先改进
+1. [第一优先]
+2. [第二优先]
+3. [第三优先]
+```
+
+IMPORTANT：客观报告，不美化。用数据说话，不用模糊的"还行"或"不错"。

package/templates/level-3/impact.md

@@ -0,0 +1,61 @@
+---
+name: impact
+description: >
+  改动影响分析。修改现有功能、重构、升级依赖前使用。
+  分析改动的爆炸半径，列出所有受影响的模块和风险点。
+---
+
+# 改动影响分析
+
+对改动 "$ARGUMENTS" 进行影响分析：
+
+## 1. 直接影响
+搜索项目中所有直接引用目标模块/类型/函数的文件：
+- 用 Grep 搜索 import 语句
+- 用 Grep 搜索类型引用
+- 用 Grep 搜索函数调用
+
+列出每个引用点的文件路径和行号。
+
+## 2. 间接影响
+对直接影响的文件，追踪它们的调用者（向上一层）：
+- 如果改的是 Service 层，谁调用了这个 Service？
+- 如果改的是类型定义，哪些 API Route 和组件用了这个类型？
+- 如果改的是数据库 Schema，哪些 Service 和 migration 受影响？
+
+## 3. 测试影响
+列出覆盖该模块的现有测试：
+- 单元测试：哪些测试文件测的是这个模块？
+- 集成测试：哪些测试覆盖了受影响的 API？
+- 标注：哪些受影响的模块**没有**测试覆盖？
+
+## 4. 风险评估
+
+输出格式：
+
+```
+## 影响分析报告
+
+### 直接影响（改了就会影响）
+| 文件 | 引用方式 | 风险 |
+|------|---------|------|
+| [文件路径] | [import/调用/类型引用] | [高/中/低] |
+
+### 间接影响（可能波及）
+| 文件 | 传导路径 | 风险 |
+|------|---------|------|
+
+### 测试覆盖
+- 已覆盖：[列出]
+- 未覆盖（需要补测试）：[列出]
+
+### 建议的改动顺序
+1. [先改什么]
+2. [再改什么]
+3. [每步验证什么]
+```
+
+IMPORTANT：
+- 宁可多列不要漏列
+- 未覆盖测试的模块标注为高风险
+- 建议的改动顺序必须是可以逐步验证的

package/templates/level-3/retro.md

@@ -0,0 +1,62 @@
+---
+name: retro
+description: >
+  会话回顾。完成重要任务或准备结束会话时使用。
+  引导回答三个反思问题，将经验沉淀到 CLAUDE.md，关闭进化闭环。
+---
+
+# 会话回顾
+
+## 步骤
+
+1. **回顾本次会话**
+   快速扫描当前会话的对话历史，总结：
+   - 本次完成了哪些任务
+   - 过程中是否有需要纠正 AI 的地方
+   - 使用了哪些 Skills / 工具
+
+2. **引导三个反思问题**
+
+   逐一向用户提问（使用 AskUserQuestion）：
+
+   ### Q1: AI 犯了什么错？
+   - 是否有需要反复纠正的问题
+   - 是否有生成了不准确/不一致的代码
+   - 是否有理解偏差
+
+   ### Q2: 哪个 prompt 效果好？
+   - 哪条指令让 AI 一次到位
+   - 哪种描述方式最高效
+   - 是否有值得模板化的 prompt
+
+   ### Q3: 需要更新 CLAUDE.md 吗？
+   - AI 犯的错是否需要写入 "常见陷阱"
+   - 好用的 prompt 是否需要固化为规则
+   - 是否发现了新的模式需要记录
+
+3. **执行沉淀**
+   如果用户确认有需要沉淀的内容：
+   - 读取当前 CLAUDE.md
+   - 将新规则/陷阱追加到对应章节
+   - 展示 diff 让用户确认
+
+4. **输出会话摘要**
+
+   ```
+   ## 会话回顾 [日期]
+
+   ### 完成的任务
+   - [任务列表]
+
+   ### 经验沉淀
+   - [新增到 CLAUDE.md 的规则，如果有]
+   - [记录的好 prompt，如果有]
+
+   ### 待办
+   - [下次会话需要继续的事项，如果有]
+   ```
+
+IMPORTANT：
+- 不要自己编造答案，等用户回答每个问题
+- 如果用户说没什么要沉淀的，尊重判断，不要强行凑内容
+- 保持简短，不要把回顾变成负担

package/templates/level-3/spec.md

@@ -1,56 +1,273 @@
 ---
 name: spec
 description: >
-  Requirement analysis and product definition. Use when you have a new idea,
-  feature request, or business need that requires formalization.
-  Produces a structured spec.md through Socratic questioning, as input for /plan.
+  需求分析与产品定义。当有新想法、新功能需求或业务需求需要正式化时使用。
+  通过苏格拉底提问挖掘真实需求，输出结构化的 spec.md，作为 /plan 的输入。
 ---
 
-# Requirement Analysis & Product Definition
+# 需求分析与产品定义
 
-Transform vague ideas into a validated spec.md — the upstream input for /plan.
+将模糊的想法转化为结构化、经过验证的产品规格文档 `spec.md`，作为后续技术设计（/plan）的输入。
 
-## Process
+## 步骤
 
-1. **Capture Raw Idea** — Let user express freely, then summarize back in one sentence
-2. **Socratic Questioning** — 5 Whys to find root problem + probe 3-5 key dimensions:
-   Clarification / Assumptions / Evidence / Perspectives / Implications / Meta-questions
-3. **Clarity Scoring** — Rate requirement on 100-point scale:
-   Business Context /20, Functional Clarity /30, Technical Specificity /25, Scope /25.
-   Must reach ≥ 90 before proceeding.
-4. **Strategy Exploration** — Compare 2-3 approaches (trade-offs, effort). User chooses.
-5. **User Stories** — Given/When/Then acceptance criteria (happy path + errors + edge cases)
-6. **Feature Breakdown** — Dependency graph + data model + API surface (when applicable)
-7. **Multi-Perspective Review** — Engineer / User / Business viewpoints
-8. **Generate spec.md** — Wait for user approval before proceeding to /plan
+### Step 1: 捕获原始想法
 
-## Output
+让用户以任何形式表达想法 — 一句话、一段描述、一个竞品参考。不要过早施加结构。
 
-Single file `docs/spec.md` (or `docs/[feature]-spec.md`) containing:
-- Background & root problem (5 Whys chain)
-- Objectives & anti-goals
-- Target users with pain level
-- Strategy chosen with rationale
-- User stories with acceptance criteria
-- Feature dependency graph
-- Data model & API surface (if applicable)
-- Risks from multi-perspective review
-- Scope boundaries (in/out)
-- Success metrics
+听完后用一句话复述确认：
 
-## When to Use
+> "如果我理解正确，你想要 [摘要]。是这样吗？"
 
-- New feature ideas that are still vague or need validation
-- Medium-to-large features (cross-module, new data models, new APIs)
-- Skip for small changes (< 3 files) — use /plan directly
+### Step 2: 苏格拉底提问 — 挖掘真实需求
+
+#### 5 Whys（追根溯源）
+
+从表面需求开始连续追问"为什么"，直到找到根本问题：
+
+```
+用户："我们需要一个通知系统"
+→ Why? "用户会错过重要更新"
+→ Why? "他们不经常打开应用"
+→ Why? "没有理由回来，除非有变化"
+→ Why? "我们没有主动触达用户的机制"
+→ 根本需求：主动触达系统（通知只是方案之一）
+```
+
+将根本问题呈现给用户，这常常会重新定义整个需求。
+
+#### 6 维度探查（选 3-5 个最相关的问问题，分批进行，每批 2-3 个）
+
+1. **澄清** — "你说的 [X] 具体指什么？能举个例子吗？"
+2. **假设** — "我们在假设用户会 [Y]，如果不是呢？"
+3. **证据** — "什么数据/反馈表明这是真实问题？影响多少用户？"
+4. **视角** — "新用户和老用户体验会有什么不同？"
+5. **影响** — "如果不做这个，代价是什么？做了之后有什么连锁反应？"
+6. **元问题** — "我们在解决正确的问题吗？有什么能让这个需求变得不必要？"
+
+### Step 3: 清晰度评分
+
+对话结束后，对需求进行 100 分制评估：
+
+```
+Business Context        /20  (问题清晰 /7, 目标用户 /7, 成功指标 /6)
+Functional Clarity      /30  (核心功能 /10, 用户流程 /10, 边界情况 /10)
+Technical Specificity   /25  (技术约束 /8, 集成点 /8, 性能需求 /9)
+Scope Definition        /25  (In-scope /10, Out-of-scope /8, 优先级 /7)
+TOTAL                   /100
+```
+
+- **≥ 90**：进入 Step 4
+- **70-89**：针对低分维度追问
+- **< 70**：需要更多对话，回到 Step 2
+
+向用户展示评分和具体差距，例如："你的需求得分 75/100，边界情况（4/10）和性能需求（3/9）需要补充。"
+
+**评分达到 ≥ 90 后才继续。**
+
+### Step 4: 策略探索
+
+不要直接跳到产品定义。先探索 2-3 种实现策略：
+
+```
+策略 A: [名称 — 如"最小可行"]
+  核心方案：[做什么]
+  取舍：[得到什么 vs 放弃什么]
+  工作量：S/M/L/XL
+
+策略 B: [名称 — 如"完整方案"]
+  ...
+
+策略 C: [名称 — 如"平台化"]
+  ...
+```
+
+让用户选择、组合或提出新方向。
+
+**何时跳过**：需求非常明确、方案空间很窄时（Bug 修复、合规要求、有明确规格的直接需求）。
+
+### Step 5: 用户故事与验收标准
+
+为每个核心功能编写用户故事和 Given/When/Then 验收标准：
+
+```markdown
+### Story [N]: [标题]
+**As a** [用户], **I want to** [行为], **so that** [价值]
+**Priority**: P0/P1/P2 | **Complexity**: S/M/L/XL
+
+Acceptance Criteria:
+Happy Path:
+- [ ] Given [前提], when [操作], then [结果]
+
+Validation:
+- [ ] Given [无效输入], when [操作], then [具体错误处理]
+
+Edge Cases:
+- [ ] Given [边界条件], when [操作], then [行为]
+```
+
+**要求**：
+- 每条标准独立可测试
+- 包含具体数值（不是"快速"，而是"200ms 内响应"）
+- 覆盖正常路径、错误路径和边界情况
+
+### Step 6: 特性分解与数据/API 设计
+
+#### 特性依赖图
+
+```
+F1 [基础能力] ──→ F2 [核心功能] ──→ F4 [增强功能]
+  └──→ F3 [辅助功能] ──→ F5 [集成]
+```
+
+#### 数据模型（当涉及新数据实体时）
+
+```markdown
+### Entity: [Name]
+| Field | Type | Constraints | Required | Default |
+|-------|------|-------------|:--------:|---------|
+| id | UUID | PK, auto | Yes | gen_random_uuid() |
+| ... | ... | ... | ... | ... |
+```
+
+#### API 概要（当涉及新 API 时）
+
+```markdown
+| Method | Endpoint | Description | Auth | Request | Response |
+|--------|----------|-------------|:----:|---------|----------|
+| POST | /api/v1/... | ... | Yes | {...} | {...} |
+```
+
+### Step 7: 多视角审查
+
+从三个视角审查，发现盲点：
+
+- **工程视角**：技术可行性？最难的部分？有更简单的替代方案吗？
+- **用户视角**：用户能理解这个功能吗？学习成本多高？
+- **业务视角**：ROI 合理吗？和产品战略一致吗？
+
+记录各视角的担忧，写入 spec.md 的风险章节。
+
+### Step 8: 生成 spec.md
+
+使用下方模板生成 `docs/spec.md`（或 `docs/[feature-name]-spec.md`）。
+
+### Step 9: 等待确认
+
+IMPORTANT：
+- spec.md 输出后必须等待用户确认，不要自行开始技术设计。
+- 下一步引导用户使用 `/plan` 进行技术方案设计。
+
+---
+
+## 输出模板
+
+```markdown
+# Spec: [项目/功能名称]
+
+## Clarity Score: [X]/100
+| Dimension | Score | Notes |
+|-----------|:-----:|-------|
+| Business Context | /20 | |
+| Functional Clarity | /30 | |
+| Technical Specificity | /25 | |
+| Scope Definition | /25 | |
+
+## 1. Background & Root Problem
+
+### Surface Request
+[用户最初提出的需求]
+
+### Root Problem
+[通过 5 Whys 发现的根本问题]
+
+### Why Now
+[触发因素 — 事故、反馈、市场变化、战略调整]
+
+## 2. Objectives
+- **Primary**: [主要目标 — 具体可衡量]
+- **Secondary**: [次要目标]
+- **Anti-Goals**: [明确不做的事]
+
+## 3. Target Users
+
+| Attribute | Description |
+|-----------|-------------|
+| Who | [角色/画像] |
+| Context | [使用场景] |
+| Current workaround | [现在怎么解决] |
+| Pain level | [痛点程度] |
+
+## 4. Strategy Chosen
+[选择的策略及原因，备选策略简述]
+
+## 5. User Stories & Acceptance Criteria
+
+### Story 1: [Title]
+**As a** ..., **I want to** ..., **so that** ...
+**Priority**: P0 | **Complexity**: M
+
+**Acceptance Criteria**:
+- [ ] Given ..., when ..., then ...
+(Happy path + Validation + Edge cases)
+
+## 6. Feature Breakdown & Dependencies
+
+| ID | Feature | Priority | Complexity | Dependencies | Stories |
+|----|---------|----------|------------|--------------|---------|
+| F1 | ... | P0 | M | None | S1, S2 |
+
+### Dependency Graph
+F1 ──→ F2
+
+## 7. Data Model
+[Entity tables with constraints — only if new data entities are involved]
+
+## 8. API Surface
+[Method / Endpoint / Description / Auth / Request / Response — only if new APIs are involved]
+
+## 9. UI/UX Notes
+- Loading / Empty / Error states
+- Responsive / Accessibility requirements
+
+## 10. Risks & Concerns
+
+### Engineering
+- [Concern]: [Mitigation]
+
+### User Experience
+- [Concern]: [Mitigation]
+
+### Business
+- [Concern]: [Mitigation]
+
+## 11. Out of Scope
+- [Item] — Reason: [why]
+
+## 12. Open Questions
+- [ ] [Question] — Owner: [who]
+
+## 13. Success Metrics
+| Metric | Current | Target | How to Measure |
+|--------|---------|--------|----------------|
+| ... | ... | ... | ... |
+```
+
+---
 
 ## Quality Gate
 
-Before moving to /plan:
+进入 /plan 前，以下条件必须满足：
 - [ ] Clarity Score ≥ 90
-- [ ] Root problem identified (not surface request)
-- [ ] ≥ 3 user stories with ≥ 3 acceptance criteria each
-- [ ] Scope boundaries explicit (in AND out)
-- [ ] ≥ 2 measurable success metrics
-- [ ] Multi-perspective review completed
-- [ ] User approved
+- [ ] 根本问题已识别（非表面需求）
+- [ ] 至少 3 条用户故事，每条有 ≥ 3 个验收标准
+- [ ] Scope 边界明确（In-scope AND Out-of-scope）
+- [ ] 至少 2 个可衡量的成功指标
+- [ ] 多视角审查已完成
+- [ ] 用户已审阅并确认
+
+## Tips
+
+- **小功能不需要走这个流程** — 改动 < 3 文件的需求直接用 /plan
+- **用户抗拒提问时** — 提供默认值让对方确认："我先假设 X，你觉得不对再告诉我"
+- **需求文档已有时** — 可以跳过 Step 1-2，直接从 Step 3 评分开始

package/templates/level-3/takeover.md

@@ -0,0 +1,72 @@
+---
+name: takeover
+description: >
+  接管现有项目。接手别人的项目或长期未维护的项目时使用。
+  全面分析代码库，生成 CLAUDE.md 和体系配置。
+---
+
+# 接管现有项目
+
+## 步骤
+
+1. **全局扫描**
+   使用 Explore Agent 遍历项目结构，理解：
+   - 目录组织和架构模式
+   - 核心模块之间的依赖关系
+   - 数据流向（前端 → API → 服务层 → 数据库）
+   - 外部依赖和第三方集成
+
+2. **文档盘点**
+   逐项检查现有文档的存在性和新鲜度：
+   - README、CLAUDE.md、API 文档、Schema 文档、CHANGELOG 等
+   - 标注状态：**Current**（与代码匹配）/ **Stale**（明显落后）/ **Outdated**（严重不匹配）
+   - 缺失的关键文档标注为生成候选
+
+3. **技术栈识别**
+   从配置文件提取：
+   - package.json → 框架、库、scripts
+   - tsconfig.json → TypeScript 配置
+   - .eslintrc / prettier → 代码风格
+   - docker-compose / Dockerfile → 部署方式
+   - prisma/schema.prisma → 数据模型
+
+4. **代码质量快照**
+   快速评估：
+   - 测试覆盖现状（有测试的模块 vs 没有的）
+   - 代码风格一致性
+   - TODO/FIXME/HACK 数量
+   - 超长文件和复杂函数
+
+5. **生成配置**
+   基于分析结果生成：
+   - CLAUDE.md — 项目描述、命令、架构、关键规则
+   - .claude/settings.json — 权限配置
+   - docs/approved-deps.md — 从现有依赖生成白名单
+
+6. **输出分析报告**
+
+   ```
+   ## 项目分析报告
+
+   ### 技术栈
+   [框架、语言、数据库、部署方式]
+
+   ### 架构概览
+   [核心模块及其关系]
+
+   ### 代码健康度
+   [测试覆盖、代码质量、技术债评估]
+
+   ### 风险区域
+   [缺少测试的关键模块、潜在安全问题、过度耦合]
+
+   ### 建议的首要改进
+   1. [优先级1]
+   2. [优先级2]
+   3. [优先级3]
+   ```
+
+IMPORTANT：
+- 生成的配置是草稿，提醒用户必须审阅
+- 不要编造项目中不存在的内容
+- 对推断内容标注置信度：[HIGH] / [MEDIUM] / [LOW]

package/templates/level-3/test.md

@@ -0,0 +1,42 @@
+---
+name: test
+description: >
+  测试生成与验证。新功能完成后或修复 Bug 时使用。
+  根据代码生成单元测试和集成测试，执行并验证结果。
+---
+
+# 测试生成与验证
+
+## 步骤
+
+1. **确定测试范围**
+   - 读取最近变更：`git diff --name-only`
+   - 识别需要测试的模块（Service 函数、API Route）
+   - 检查是否已有测试文件
+
+2. **生成测试用例**
+
+   对每个目标模块，生成三类测试：
+
+   a) **正常路径** — 标准输入产生正确输出
+   b) **边界条件** — 空值、极大值、空数组、特殊字符
+   c) **错误路径** — 无效输入、依赖服务失败、权限不足
+
+   Bug 修复额外要求：
+   d) **回归测试** — 精确复现 Bug 的测试用例
+
+3. **执行测试**
+   ```
+   npm run test              # 全量单元测试
+   npm run test -- --run [文件]  # 指定文件
+   ```
+
+4. **验证结果**
+   - 全部通过 → 报告覆盖的场景清单
+   - 有失败 → 分析是测试写错了还是代码有 Bug
+
+IMPORTANT：
+- 测试代码基于**接口合同**写，不基于内部实现
+- 不要写验证实现细节的测试（如"调用了某个内部方法 3 次"）
+- Bug 修复必须有回归测试，这是不可跳过的
+- 如果发现现有代码没有测试，先补测试再改代码

package/templates/level-3/ui-page.md

@@ -0,0 +1,36 @@
+---
+name: ui-page
+description: >
+  快速生成 UI 页面骨架。新增页面时使用。
+  用 shadcn/ui 默认样式，功能优先不美化。
+---
+
+# 快速 UI 页面生成
+
+生成页面 "$ARGUMENTS"：
+
+## 规则
+- 使用 shadcn/ui 组件，不自定义样式
+- 使用项目现有的 layout 结构
+- 列表用 Table，表单用 Form + zod，弹窗用 Dialog
+- 必须处理三种状态：加载中（Skeleton）、空数据、错误
+- 必须连接真实 API，不用 mock 数据
+- 不做样式美化
+
+## 页面类型速查
+
+| 类型 | 组件组合 |
+|------|---------|
+| 列表页 | Table + Pagination + 搜索 Input + 新增 Button |
+| 详情页 | Card + Tabs + 返回 Button |
+| 表单页 | Form + zod schema + Submit Button + Toast |
+| 仪表盘 | Card 网格 + 数字统计 |
+
+## 步骤
+
+1. 确认页面类型和数据来源（API 接口）
+2. 检查 shadcn/ui 是否已安装需要的组件，未安装则先安装
+3. 生成页面组件 + 对应的 API Route（如果还没有）
+4. 跑通数据流，验证功能正确
+
+IMPORTANT：功能优先。不要花时间在颜色、间距、动画上。