# windsure-ai-rules-workflow

**Repository Path**: rubyhu/windsure-ai-rules-workflow

## Basic Information

- **Project Name**: windsure-ai-rules-workflow
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌊 Windsurf AI Rules & Workflows

<div align="center">

**生产级 AI 辅助开发配置集合**  
*让 Cascade AI 真正理解你的项目*

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Windsurf](https://img.shields.io/badge/Windsurf-Compatible-blue.svg)](https://codeium.com/windsurf)

[English](README.md) | [简体中文](README_CN.md)

</div>

## 📖 目录

- [什么是 Windsurf Rules & Workflows](#什么是-windsurf-rules--workflows)
- [为什么需要这个项目](#为什么需要这个项目)
- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [示例项目](#示例项目)
- [使用示例](#使用示例)
- [最佳实践](#最佳实践)
- [贡献指南](#贡献指南)
- [License](#license)

## 🎯 什么是 Windsurf Rules & Workflows

这是一个开源项目，提供了**生产级**的 Windsurf IDE AI 辅助开发配置集合，包括：

- **📋 Rules（规则）**: 告诉 AI 你的项目规范、架构模式和最佳实践
- **🔄 Workflows（工作流）**: 预定义的任务流程，让 AI 按步骤完成复杂任务

### 适用场景

✅ Vue 3 + TypeScript 前端项目  
✅ React + TypeScript 前端项目  
✅ Node.js 后端项目  
✅ 全栈 JavaScript/TypeScript 项目  
✅ 企业级应用开发  

## 🤔 为什么需要这个项目

### 痛点

❌ AI 不了解项目规范，生成的代码风格不统一  
❌ AI 重复问相同问题，效率低下  
❌ AI 不知道项目架构，代码放错位置  
❌ 每次都要解释技术栈和依赖关系  
❌ 复杂任务需要人工拆解，容易遗漏步骤  

### 解决方案

✅ **Rules** 让 AI 记住项目所有规范  
✅ **Workflows** 标准化复杂任务流程  
✅ **持久化配置** 团队共享，新人秒上手  
✅ **版本控制** 规范演进可追溯  
✅ **开箱即用** 复制即可，快速适配  

## ✨ 功能特性

### 🎨 按技术栈组织的 Rules 体系

```
.windsurf/rules/
├── common/              # 📦 通用规范（21个）
│   ├── typescript-standards.md
│   ├── git-commit-message.md
│   ├── security-standards.md
│   ├── error-handling.md
│   └── ... (更多通用规范)
│
├── vue3/                # 🟢 Vue 3 规范（14个）
│   ├── README.md       # Vue 3 规范索引
│   ├── vue3-component-standards.md
│   ├── composables-patterns.md
│   ├── pinia-standards.md
│   └── ... (更多 Vue 规范)
│
├── react/               # 🔵 React 规范（4个）
│   ├── README.md       # React 规范索引
│   ├── react-standards.md
│   ├── react-hooks-patterns.md
│   └── nextjs-standards.md
│
├── nodejs/              # 🟡 Node.js 规范（5个）
│   ├── README.md       # Node.js 规范索引
│   ├── nodejs-backend-standards.md
│   ├── database-design.md
│   └── ... (更多后端规范)
│
└── meta/                # 📚 元规范和文档（20个）
    ├── project-infrastructure-first.md
    ├── GLOBAL_STANDARDS.md
    └── ... (规范文档)
```

### 🔄 实用的 Workflows 集合

| Workflow | 描述 | 使用场景 |
|----------|------|----------|
| `/dev-setup` | 开发环境启动 | 项目初始化、环境问题排查 |
| `/code-quality` | 代码质量检查 | 提交前检查、代码审查 |
| `/build-deploy` | 构建部署 | 多环境部署流程 |
| `/git-workflow` | Git 工作流 | 分支管理、PR 流程 |
| `/vue-component` | Vue 组件开发 | 创建标准化组件 |
| `/debug-issues` | 问题调试 | 系统性问题排查 |

## 🚀 快速开始

### 1. 安装 Windsurf IDE

```bash
# 访问官网下载
https://codeium.com/windsurf
```

### 2. 根据技术栈选择规范

#### Vue 3 项目
```bash
# 复制 Vue 3 规范
cp -r .windsurf/rules/common your-project/.windsurf/rules/
cp -r .windsurf/rules/vue3/* your-project/.windsurf/rules/
```

#### React 项目
```bash
# 复制 React 规范
cp -r .windsurf/rules/common your-project/.windsurf/rules/
cp -r .windsurf/rules/react/* your-project/.windsurf/rules/
```

#### Node.js 项目
```bash
# 复制 Node.js 规范
cp -r .windsurf/rules/common your-project/.windsurf/rules/
cp -r .windsurf/rules/nodejs/* your-project/.windsurf/rules/
```

### 3. 自定义配置

根据你的项目调整：
- 修改 `rules/PROJECT_CONTEXT.md` 填入项目信息
- 调整技术栈相关的规范文件
- 添加项目特定的工作流

### 4. 在 Cascade 中使用

```bash
# 打开 Windsurf IDE
# 在 Cascade 面板中输入斜杠命令
/dev-setup
/code-quality
```

## 📂 项目结构

```
windsurf-ai-rules-workflows/
├── .windsurf/
│   ├── rules/                      # 📋 规范配置
│   │   ├── common/                # 通用规范（21个）
│   │   ├── vue3/                  # Vue 3 规范（14个）
│   │   ├── react/                 # React 规范（4个）
│   │   ├── nodejs/                # Node.js 规范（5个）
│   │   └── meta/                  # 元规范和文档（20个）
│   │
│   └── workflows/                 # 🔄 工作流配置
│       ├── common/               # 通用工作流
│       ├── vue3/                 # Vue 3 专用工作流
│       ├── react/                # React 专用工作流
│       └── nodejs/               # Node.js 专用工作流
│
├── examples/                      # 💡 示例项目
│   ├── vue3-example/            # Vue 3 完整示例
│   ├── react-example/           # React + Next.js 示例
│   └── fullstack-example/       # 全栈应用示例
│
├── docs/                          # 📚 详细文档
│   ├── getting-started.md
│   ├── best-practices.md
│   └── FAQ.md
│
├── CONTRIBUTING.md
├── LICENSE
└── README.md
```

## 🎬 示例项目

本仓库提供了 3 个完整的示例项目，展示如何应用规范：

### 1. Vue 3 示例 ([`examples/vue3-example/`](examples/vue3-example/))

**特点**:
- ✅ Vue 3.5+ Composition API
- ✅ TypeScript 严格模式
- ✅ Element Plus UI 组件库
- ✅ Pinia 状态管理
- ✅ 用户管理 CRUD 完整示例
- ✅ 展示如何复用项目基础设施

**快速开始**:
```bash
cd examples/vue3-example
pnpm install
pnpm dev
```

**学习要点**:
- 查看 `src/views/users/List.vue` - 用户列表完整实现
- 查看 `src/composables/useTable.ts` - 表格逻辑封装
- 查看 `PROJECT_INFRASTRUCTURE.md` - 项目能力索引

### 2. React + Next.js 示例 ([`examples/react-example/`](examples/react-example/))

**特点**:
- ✅ Next.js 14 App Router
- ✅ React Server Components
- ✅ TypeScript 类型安全
- ✅ Tailwind CSS 样式
- ✅ API Route Handlers
- ✅ 自定义 Hooks 封装

**快速开始**:
```bash
cd examples/react-example
pnpm install
pnpm dev
```

**学习要点**:
- 查看 `app/users/page.tsx` - Server Component 示例
- 查看 `src/hooks/useUsers.ts` - 自定义 Hook
- 查看 `src/services/user.service.ts` - API 服务封装

### 3. 全栈应用示例 ([`examples/fullstack-example/`](examples/fullstack-example/))

**特点**:
- ✅ React + Next.js 前端
- ✅ Node.js + Fastify 后端
- ✅ PostgreSQL + Prisma ORM
- ✅ Redis 缓存
- ✅ JWT 认证
- ✅ Docker Compose 一键启动

**快速开始**:
```bash
cd examples/fullstack-example
docker-compose up -d
# 前端: http://localhost:3000
# 后端: http://localhost:4000
```

**学习要点**:
- 前后端分离架构
- RESTful API 设计
- 数据库设计和迁移
- Docker 容器化部署

## 💡 使用示例

### 场景 1: 新项目启动

```bash
# 1. 在 Cascade 中调用工作流
/dev-setup

# AI 会自动执行:
# ✓ 检查 Node.js 和包管理器版本
# ✓ 安装项目依赖
# ✓ 验证环境配置
# ✓ 运行类型检查
# ✓ 启动开发服务器
```

### 场景 2: 创建 Vue 组件

```bash
# 告诉 AI 你的需求
创建一个用户卡片组件，包含头像、姓名、邮箱和操作按钮

# AI 会根据 vue3-component-standards.md 规范:
# ✓ 使用 <script setup> 语法
# ✓ 定义 TypeScript Props 和 Emits
# ✓ 使用 Tailwind CSS 样式
# ✓ 添加完整的注释
# ✓ 遵循命名规范
```

### 场景 3: 代码质量检查

```bash
/code-quality

# AI 会执行:
# ✓ ESLint 检查并修复
# ✓ Prettier 格式化
# ✓ TypeScript 类型检查
# ✓ 生成质量报告
```

### 场景 4: Git 工作流

```bash
/git-workflow 创建用户管理功能

# AI 会:
# ✓ 从 develop 分支创建 feature/user-management
# ✓ 设置上游分支
# ✓ 提供提交规范示例
# ✓ 指导 PR 创建流程
```

## 🎨 最佳实践

### 1. 规则分层管理

```
P0 (必须遵守) → 核心技术栈、安全规范
P1 (强烈建议) → 代码规范、架构模式
P2 (建议遵循) → 优化建议、最佳实践
```

### 2. 渐进式采用

```
第 1 周: 核心规则 (技术栈 + 代码规范)
第 2 周: 工作流 (开发环境 + 代码质量)
第 3 周: 安全规范 (XSS + 认证授权)
第 4 周: 高级规范 (性能优化 + 架构模式)
```

### 3. 团队协作

- **共享配置**: 将 `.windsurf/` 提交到 Git 仓库
- **定期更新**: 每月审查和更新规范
- **培训新人**: 使用工作流标准化入职流程
- **持续改进**: 收集反馈，优化配置

### 4. 自定义适配

```markdown
# 1. 修改 PROJECT_CONTEXT.md
填写项目名称、技术栈、架构信息

# 2. 调整技术栈规范
只保留项目实际使用的技术规范

# 3. 创建项目特定工作流
如部署流程、数据库迁移等

# 4. 配置 .gitignore
排除不需要版本控制的规则
```

## 🤝 贡献指南

我们欢迎所有形式的贡献！

### 贡献方式

- 🐛 **报告问题**: 提交 Issue 描述 bug 或改进建议
- 💡 **功能建议**: 提出新的 Rules 或 Workflows 想法
- 📝 **文档改进**: 完善文档、修正错误、添加示例
- 🔧 **代码贡献**: 提交 Pull Request

### 开始贡献

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: add some amazing feature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

详见 [贡献指南](CONTRIBUTING.md)

## 🌟 致谢

特别感谢以下项目和资源的启发：

- [Windsurf IDE](https://codeium.com/windsurf) - 革命性的 AI 编辑器
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [TypeScript](https://www.typescriptlang.org/) - JavaScript 的超集
- 所有贡献者和使用者 ❤️

## 📄 License

本项目采用 MIT License - 详见 [LICENSE](LICENSE) 文件

## 🔗 相关链接

- [Windsurf 官方文档](https://docs.windsurf.com/)
- [示例项目](./examples/)
- [详细文档](./docs/)
- [问题反馈](https://github.com/yourusername/windsurf-ai-rules-workflows/issues)

---

<div align="center">

**Made with ❤️ by the community**

如果这个项目对你有帮助，请给一个 ⭐️

[报告问题](https://github.com/yourusername/windsurf-ai-rules-workflows/issues) · [功能建议](https://github.com/yourusername/windsurf-ai-rules-workflows/issues) · [贡献代码](CONTRIBUTING.md)

</div>