Windsurf Rules（自定义规则）

.windsurfrules 文件格式

文件格式为纯文本，支持 Markdown 格式，推荐使用章节标题组织不同类别的规则：

# React + TypeScript 项目规则
# 文件名：.windsurfrules
# 放在项目根目录，提交到 Git

## 技术栈
- React 18，使用函数组件和 Hooks，不使用 class 组件
- TypeScript 5.3，严格模式（"strict": true），不允许 any 类型
- 状态管理：Zustand（已安装），不引入 Redux 或 MobX
- 样式：Tailwind CSS 3.x，不使用 CSS-in-JS 方案
- 测试：Vitest + React Testing Library，不使用 Jest
- 包管理器：pnpm，不使用 npm 或 yarn

## 代码风格
- 缩进：2 个空格
- 引号：单引号（JavaScript/TypeScript），双引号（JSX 属性）
- 分号：不加分号（ASI 风格）
- 文件命名：组件用 PascalCase（UserCard.tsx），工具函数用 camelCase（formatDate.ts）
- 组件文件结构：类型定义 → 默认导出组件 → 样式（无需独立文件）

## 禁止事项
- 不允许使用 useEffect 处理数据获取（使用 React Query 的 useQuery）
- 不允许直接修改 state 对象（必须用 setState 的函数式更新）
- 不允许在组件内部定义内联对象作为 props（会导致不必要的重渲染）
- 不允许直接使用 fetch，只允许通过 @src/lib/api.ts 的封装实例
- 不允许在代码中硬编码 API URL，使用 import.meta.env.VITE_API_URL

## 测试要求
- 每个新函数都需要对应的单元测试
- 测试文件放在与源文件相同目录的 __tests__ 子目录中
- 测试用例描述用中文
- 覆盖：正常路径 + 边界情况 + 错误情况

## 注释规范
- 代码注释和 JSDoc 用中文
- 每个 exported function 必须有 JSDoc（描述、参数、返回值）
- 复杂算法需要在关键步骤旁注释说明思路

## 安全规范
- 绝对不要在代码中包含 API Key、密码、Token 等敏感信息
- 用户输入在使用前必须通过 zod 验证
- XSS 防护：不允许使用 dangerouslySetInnerHTML

示例规则集：各类项目模板

Python FastAPI 后端规则

## Python FastAPI 项目规则

## 技术栈
- Python 3.12，使用 Poetry 管理依赖
- FastAPI 0.111+，Pydantic v2，SQLAlchemy 2.x
- 数据库：PostgreSQL + asyncpg（异步驱动）
- 迁移：Alembic
- 测试：pytest + httpx（异步测试）

## 代码规范
- 所有函数参数和返回值必须有类型注解
- 使用 Pydantic BaseModel 定义所有 API 的输入/输出 schema
- 数据库操作使用 async def，禁止同步数据库调用
- 错误处理：使用自定义 HTTPException，包含 error_code 字段

## 目录结构（不要改变）
- app/routers/     → 路由处理器（薄层，只做请求解析和响应序列化）
- app/services/    → 业务逻辑（核心逻辑在这里，可测试）
- app/models/      → SQLAlchemy ORM 模型
- app/schemas/     → Pydantic 请求/响应模型

## 禁止事项
- 不允许在 router 层直接写 SQL 或业务逻辑
- 不允许使用 print 调试，使用 logging 模块
- 不允许忽略异常（except: pass）

Go 微服务规则

## Go 微服务规则

## 规范
- Go 1.22+，使用 Go modules
- HTTP 框架：chi（已安装），不使用 gin 或 echo
- 错误处理：使用 fmt.Errorf("函数名: %w", err) 包装错误，保留调用栈
- 日志：使用 slog（标准库），结构化 JSON 格式
- 所有 goroutine 必须有对应的 context 参数，遵守 context 取消

## 代码风格
- 遵循 Effective Go 规范
- 接口定义在消费方（不在实现方）
- 测试文件：xxx_test.go，同包测试优先

## 禁止
- 不使用 panic（除非是不可恢复的初始化错误）
- 不忽略 error 返回值
- 不使用 init() 函数（依赖注入替代）

全局规则推荐配置

## 我的全局 Windsurf 规则（Settings → AI → Global Rules）

## 回复语言
- 用中文解释和注释，代码保持英文变量名和函数名

## 代码风格偏好
- 函数体不超过 50 行，超过时主动提示拆分
- 优先使用声明式/函数式风格，减少副作用
- 注重可读性，变量命名要有意义（不用 a、b、tmp）

## 任务执行风格
- 修改现有代码时，先解释"将要做什么和为什么"，再执行
- 对于有多种实现方案的任务，先列出方案对比，再执行我选择的方案
- 当我的需求不清晰时，主动提问而不是猜测

## 安全习惯
- 生成代码时，主动标注可能的安全风险（SQL注入、XSS等）
- 不要在代码示例中使用真实的 API key 或密码格式的占位符

与 .cursorrules 的迁移

如果你从 Cursor 迁移到 Windsurf，原有的 .cursorrules 文件内容几乎可以直接复用：

迁移命令（如果你之前用 Cursor）：

# 在项目根目录执行
cp .cursorrules .windsurfrules
# 然后可以保留 .cursorrules（Cursor 用）+ .windsurfrules（Windsurf 用）
# 两个文件内容保持同步即可

团队共享规则最佳实践

1. 将 .windsurfrules 加入 Git 版本控制，和代码一起 review。规则变更应该有 PR 记录和讨论。
2. 在项目 README 中说明"这个项目的 AI 规则在 .windsurfrules 中，使用 Windsurf 前请阅读"。
3. 定期 review 规则的有效性——有些规则 AI 会忽略（太宽泛），有些需要更精确的描述。
4. 不要把规则写得过于复杂。测试表明：规则文件超过 500 词后，遵循率开始下降。优先写最重要的约束。
5. 新加入团队的成员可以通过 .windsurfrules 快速了解项目的"不成文约定"——这也是它的文档价值。