Prompt-as-Code：当 Prompt 不只是"话"，而是可执行的"程序"

你："帮我写一段 Python 代码"
AI："好的，这是代码……"
你："谢谢"
结束。

传统代码：  if (condition) { doSomething(); }
Prompt 代码：如果用户要求创建新功能，先运行 `openspec list` 检查冲突

用户：帮我写一个函数
AI：好的，这是函数……

用户：帮我创建一个新功能

AI：
1. 首先，我需要检查现有功能 → 运行 `openspec list`
2. 发现没有冲突 → 创建 proposal.md
3. 等待用户确认 → 用户说"继续"
4. 创建 tasks.md → 创建 specs/
5. 运行验证 → `openspec validate --strict`
6. 完成！

---
name: /design-doc
description: 从 Jira 需求生成技术设计文档
---

# 技术设计文档生成器

## 触发条件
当用户输入 `/design-doc <JIRA-KEY>` 时触发。

## Workflow

### Step 1: 获取需求上下文
1. 调用 MCP Tool `get_jira_issue` 获取 Jira 票据详情
2. 读取 `openspec/project.md` 了解项目技术栈
3. 运行 `git log --oneline -10` 了解最近的代码变更

### Step 2: 分析并确认范围
1. 总结 Jira 票据的核心需求
2. 列出受影响的模块和文件
3. **询问用户确认**：展示分析结果，等待用户说"继续"或修改

### Step 3: 生成设计文档
如果用户确认，则：
1. 创建 `docs/design/<JIRA-KEY>.md`
2. 按照以下模板生成内容：
   - ## 背景与目标
   - ## 技术方案
   - ## API 设计
   - ## 数据模型
   - ## 风险与缓解措施

### Step 4: 关联与验证
1. 调用 MCP Tool `update_jira_issue` 将文档链接写入 Jira
2. 运行 `markdownlint` 检查文档格式
3. 如果有错误，自动修复

### Step 5: 完成
输出："✅ 设计文档已生成：docs/design/<JIRA-KEY>.md"

┌─────────────────────────────────────────────────────────────┐
│                         AI 大脑                             │
│                    （理解、推理、决策）                       │
├─────────────────────────────────────────────────────────────┤
│                      MCP Protocol                           │
├──────────┬──────────┬──────────┬──────────┬────────────────┤
│ 文件系统  │  终端    │  Jira   │  GitLab  │   浏览器       │
│ 读写文件  │ 执行命令  │ 读写票据 │ 读写 MR  │   自动化测试   │
└──────────┴──────────┴──────────┴──────────┴────────────────┘

# 自动化发布流程

## 触发条件
当用户说"发布 v1.2.3"时触发。

## Workflow

### Step 1: 预检查
1. 运行终端命令：`git status`
   - 如果有未提交的更改，**停止**并提示用户先提交
2. 运行终端命令：`npm run test`
   - 如果测试失败，**停止**并展示失败原因

### Step 2: 准备发布
1. 读取文件：`package.json`
2. 更新版本号为 `1.2.3`
3. 写入文件：`package.json`
4. 读取文件：`CHANGELOG.md`
5. 在顶部插入本次更新内容
6. 写入文件：`CHANGELOG.md`

### Step 3: 提交与推送
1. 运行终端命令：`git add .`
2. 运行终端命令：`git commit -m "chore: release v1.2.3"`
3. 运行终端命令：`git tag v1.2.3`
4. 运行终端命令：`git push && git push --tags`

### Step 4: 创建 GitLab Release
1. 调用 MCP Tool `submit_merge_request`：
   - 标题："Release v1.2.3"
   - 描述：从 CHANGELOG.md 提取
2. 调用 MCP Tool `get_merge_request_info` 获取 MR 链接

### Step 5: 通知团队
1. 调用 MCP Tool（假设有 Slack Tool）：
   - 发送到 #releases 频道
   - 内容："🚀 v1.2.3 已发布！MR: <链接>"

### Step 6: 更新 Jira
1. 调用 MCP Tool `search_jira_issues`：查找 fixVersion=1.2.3 的票据
2. 对每个票据，调用 `update_jira_issue`：状态改为"已发布"

## 完成
输出："✅ v1.2.3 发布完成！"

┌────────────────────────────────────────────────────────────┐
│                   MCP Tools (外部工具)                      │
│     Jira / GitLab / 文件系统 / 终端 / 浏览器 / API          │
├────────────────────────────────────────────────────────────┤
│                    Commands (指令)                         │
│       /blog-write, /design-doc, /release 等                │
│       定义 Workflow：步骤 + 条件 + 工具调用                  │
├────────────────────────────────────────────────────────────┤
│                      Rules (规则)                          │
│       始终生效的约束：代码风格、人设、安全限制                 │
└────────────────────────────────────────────────────────────┘

---
alwaysApply: true
---

# AI 行为约束

## 安全限制
- 永远不要执行 `rm -rf /` 或类似危险命令
- 在执行任何删除操作前，必须先询问用户确认
- 不要在 Prompt 中暴露敏感信息（API Key、密码）

## 代码风格
- 使用 TypeScript 严格模式
- 所有函数必须有类型注解
- 错误处理使用 try/catch，不要静默失败

## 工具使用偏好
- 优先使用 MCP Tools 而不是手动操作
- 如果 MCP Tool 失败，回退到终端命令

---
name: /code-review
description: 自动化代码审查流程
---

# Code Review 助手

## 触发
当用户输入 `/code-review` 或 `/code-review <file>` 时触发。

## Workflow

### Step 1: 确定审查范围
- 如果用户指定了文件 → 审查该文件
- 如果没有指定 → 运行 `git diff --name-only HEAD~1` 获取最近修改的文件

### Step 2: 读取代码
对于每个文件，使用文件系统 Tool 读取内容。

### Step 3: 审查维度
按以下维度审查每个文件：
1. **正确性**：逻辑是否正确？边界情况是否处理？
2. **可读性**：命名是否清晰？结构是否合理？
3. **性能**：是否有 N+1 查询？是否有不必要的循环？
4. **安全性**：是否有 SQL 注入、XSS 等风险？

### Step 4: 输出报告
使用 Markdown 表格输出审查结果：
| 文件 | 问题 | 严重程度 | 建议 |
|------|------|----------|------|
| ...  | ...  | 🔴/🟡/🟢 | ...  |

### Step 5: 可选：自动修复
如果用户说"帮我修"，则：
1. 读取有问题的文件
2. 应用修复
3. 写入文件
4. 运行 `npm run lint --fix` 格式化

用户输入 /design-doc JIRA-12345
        ↓
Cursor 加载 Commands 定义
        ↓
AI 解析 Workflow 步骤
        ↓
Step 1: 调用 MCP Tool (get_jira_issue)
        ↓
Step 2: 读取文件 (project.md)
        ↓
Step 3: 执行终端命令 (git log)
        ↓
Step 4: 生成内容 + 写入文件
        ↓
完成

## Three-Stage Workflow

### Stage 1: Creating Changes
**触发条件**：用户要求添加新功能、做破坏性变更、修改架构

**Workflow**：
1. 运行 `openspec list` 和 `openspec list --specs` 了解当前状态
2. 选择唯一的 `change-id`（kebab-case，动词开头）
3. 创建目录：`openspec/changes/<id>/`
4. 生成文件：`proposal.md`, `tasks.md`, `design.md`（可选）
5. 起草 spec 增量：`## ADDED|MODIFIED|REMOVED Requirements`
6. 运行 `openspec validate <id> --strict` 验证
7. **停止**：等待人工批准后再继续

### Stage 2: Implementing Changes
**触发条件**：proposal 已被批准

**Workflow**：
1. 读取 `proposal.md` 了解要做什么
2. 读取 `design.md`（如果有）了解技术决策
3. 读取 `tasks.md` 获取实施清单
4. **按顺序**实施每个任务
5. 每完成一个任务，更新 `tasks.md` 状态
6. 全部完成后，标记为 `- [x]`

### Stage 3: Archiving Changes
**触发条件**：实施完成，已部署

**Workflow**：
1. 运行 `openspec archive <change-id> --yes`
2. 如果是纯工具变更，加 `--skip-specs`
3. 运行 `openspec validate --strict` 确认归档成功

### Decision Tree

New request?
├─ Bug fix restoring spec behavior? → Fix directly (不需要 proposal)
├─ Typo/format/comment? → Fix directly
├─ New feature/capability? → Create proposal
├─ Breaking change? → Create proposal
├─ Architecture change? → Create proposal
└─ Unclear? → Create proposal (safer)

### CLI Commands

# Essential commands
openspec list                  # 列出活跃变更
openspec list --specs          # 列出规格
openspec show [item]           # 查看详情
openspec validate [item]       # 验证格式
openspec archive <change-id>   # 归档变更

# Debugging
openspec show [change] --json --deltas-only
openspec validate [change] --strict

---
name: /daily-report
description: 自动生成工作日报
---

# 日报生成器

## 触发条件
用户输入 `/daily-report` 或 `/daily-report --send`

## Workflow

### Step 1: 收集 Jira 数据
1. 获取当前用户信息：调用 MCP Tool `get_current_user`
2. 搜索今天完成的任务：
   - 调用 MCP Tool `search_jira_issues`
   - JQL: `assignee = currentUser() AND status changed to "Done" after startOfDay()`
3. 如果没有找到任务 → 输出"今天没有完成的 Jira 任务"，但继续流程

### Step 2: 收集 Git 数据
1. 运行终端命令：`git log --author="$(git config user.email)" --since="00:00" --oneline`
2. 解析输出，提取 commit 列表

### Step 3: 生成日报
按以下格式生成 Markdown：

```markdown
# 工作日报 - YYYY-MM-DD

## 今日完成
### Jira 任务
- [JIRA-123] 任务标题
- [JIRA-456] 任务标题

### 代码提交
- abc1234: commit message 1
- def5678: commit message 2

## 明日计划
（留空，等待用户补充）

## 遇到的问题
（留空，等待用户补充）

### 6.3 这个 Command 用到了什么？

| 能力 | 具体实现 |
|------|----------|
| **MCP Tool 调用** | `get_current_user`, `search_jira_issues`, Slack |
| **终端命令执行** | `git log --author=...` |
| **文件读写** | 创建目录、写入 Markdown 文件 |
| **条件分支** | `--send` 参数判断、无任务时的处理 |
| **模板生成** | 按固定格式生成日报内容 |

---

## 七、常见误区与最佳实践

### 误区 1：Workflow 步骤太细

❌ 错误：
```markdown
1. 打开终端
2. 输入 git
3. 输入空格
4. 输入 status
5. 按回车

1. 运行 `git status` 检查工作区状态

1. 运行 `npm run build`
2. 运行 `npm run deploy`

1. 运行 `npm run build`
   - 如果失败 → **停止**，输出错误信息
2. 运行 `npm run deploy`
   - 如果失败 → **回滚**，运行 `git reset --hard HEAD~1`