03b - 规则文件编写指南

~/.claude/CLAUDE.md              ← 全局规则（所有项目通用）
项目根目录/CLAUDE.md              ← 项目级规则（当前项目通用）
项目根目录/packages/api/CLAUDE.md ← 子目录规则（特定模块专用）

# CLAUDE.md
 
## 项目概述
[1-2 句话说明项目是什么、做什么]
 
## 技术栈
- 语言：[语言和版本]
- 框架：[框架和版本]
- 数据库：[数据库类型]
- 包管理：[包管理工具]
 
## 项目结构

## 常用命令
- 构建：`[构建命令]`
- 测试：`[测试命令]`
- 格式化：`[格式化命令]`
- Lint：`[lint 命令]`

## 编码规范
- [规范 1]
- [规范 2]
- [规范 3]

## 禁止事项
- 不要 [禁止事项 1]
- 不要 [禁止事项 2]

## 错误处理
[错误处理约定]

## 测试规范
[测试编写约定]

# CLAUDE.md
 
## 项目概述
TaskFlow 是一个团队任务管理 SaaS，使用 Next.js 14 App Router + Prisma + PostgreSQL。
 
## 技术栈
- 语言：TypeScript 5.5（严格模式）
- 框架：Next.js 14 (App Router)
- ORM：Prisma 5
- 数据库：PostgreSQL 16
- 认证：NextAuth.js v5
- 样式：Tailwind CSS 3.4
- 测试：Vitest + Playwright
- 包管理：pnpm
 
## 项目结构

## 常用命令
- 开发：`pnpm dev`
- 构建：`pnpm build`
- 测试：`pnpm test`（Vitest）
- E2E 测试：`pnpm test:e2e`（Playwright）
- 数据库迁移：`pnpm prisma migrate dev`
- 格式化：`pnpm format`
- Lint：`pnpm lint`

## 编码规范
- 所有组件使用函数式组件 + hooks，禁止 class 组件
- API 路由使用 Zod 验证所有输入
- 数据库操作只在 server components 或 API 路由中执行
- 使用 `@/` 路径别名引用 src 目录
- 错误处理使用自定义 AppError 类，不要用裸 throw
- 所有公共 API 返回统一的 { success, data, error } 格式

## 禁止事项
- 不要使用 `any` 类型，使用 `unknown` + 类型守卫
- 不要在客户端组件中直接调用 Prisma
- 不要使用 `console.log`，使用项目的 logger 工具
- 不要硬编码环境变量，使用 env.ts 中的类型安全配置

# CLAUDE.md
 
## 项目概述
rustsync 是一个跨平台文件同步 CLI 工具，支持本地和云存储同步。
 
## 技术栈
- 语言：Rust 1.82 (edition 2024)
- 异步运行时：tokio
- CLI 框架：clap 4
- 序列化：serde + serde_json
- HTTP：reqwest
- 测试：内置 #[test] + proptest（属性测试）
 
## 项目结构

## 常用命令
- 构建：`cargo build`
- 测试：`cargo test`
- Clippy：`cargo clippy -- -D warnings`
- 格式化：`cargo fmt`
- 发布构建：`cargo build --release`

## 编码规范
- 错误处理：公共 API 使用 thiserror 定义领域错误，内部使用 anyhow
- 所有公共函数必须有文档注释（/// 格式）
- 使用 tracing crate 记录日志，不要用 println! 或 eprintln!
- 优先使用 &str 而非 String 作为函数参数
- 异步函数使用 tokio，同步代码不要引入异步依赖

## 禁止事项
- 不要使用 unwrap()，使用 ? 操作符或 expect() 并附带说明
- 不要使用 unsafe 代码，除非有充分理由并添加 SAFETY 注释
- 不要忽略 clippy 警告

# .cursorrules
 
## 项目信息
你正在开发 [项目名]，一个 [项目描述]。
 
## 技术栈
- [技术栈列表]
 
## 代码风格
- [风格规则 1]
- [风格规则 2]
 
## 架构规则
- [架构规则 1]
- [架构规则 2]
 
## 命名规范
- [命名规则]
 
## 禁止事项
- 不要 [禁止事项]
 
## 偏好
- 优先使用 [偏好 A] 而非 [偏好 B]

你是一个 React + TypeScript 专家。
 
## 技术栈
- React 19 + TypeScript 5.5
- Vite 6 构建
- Zustand 状态管理
- React Query 数据获取
- Tailwind CSS 样式
 
## 代码风格
- 使用函数式组件和 hooks
- 组件文件使用 PascalCase 命名
- 工具函数使用 camelCase 命名
- 每个组件一个文件，与同名 .module.css 配对
- 使用 named export，不要 default export
 
## 架构规则
- 组件按功能分目录（components/auth/、components/dashboard/）
- 自定义 hooks 放在 hooks/ 目录
- API 调用封装在 api/ 目录
- 类型定义放在 types/ 目录
 
## 禁止事项
- 不要使用 any 类型
- 不要使用 class 组件
- 不要在组件中直接调用 fetch，使用 React Query
- 不要使用 inline styles，使用 Tailwind 或 CSS Modules

你是一个 Python FastAPI 后端专家。
 
## 技术栈
- Python 3.12 + FastAPI 0.115
- SQLAlchemy 2.0 + Alembic
- Pydantic v2 数据验证
- Poetry 包管理
- Pytest 测试
 
## 代码风格
- 使用 type hints 标注所有函数参数和返回值
- 使用 async def 定义所有路由处理函数
- Pydantic model 用于请求/响应验证
- 使用 dependency injection 管理数据库会话
 
## 架构规则
- 路由定义在 app/routers/
- 业务逻辑在 app/services/
- 数据模型在 app/models/
- Pydantic schemas 在 app/schemas/
- 每个路由模块对应一个 service 模块
 
## 命名规范
- 文件名：snake_case
- 类名：PascalCase
- 函数名：snake_case
- 常量：UPPER_SNAKE_CASE
 
## 禁止事项
- 不要在路由函数中直接写 SQL
- 不要使用 print()，使用 logging 模块
- 不要硬编码配置值，使用 pydantic-settings

.kiro/
└── steering/
    ├── coding-standards.md      ← 始终包含：全局编码规范
    ├── api-patterns.md          ← 条件包含：API 开发时加载
    ├── testing-guide.md         ← 条件包含：测试文件时加载
    └── deployment-guide.md      ← 手动激活：部署时手动引用

~/.kiro/steering/
├── personal-preferences.md     ← 个人编码偏好
└── common-patterns.md          ← 通用设计模式

# 项目编码规范
 
## 技术栈
- [技术栈信息]
 
## 编码规范
- [规范列表]
 
## 项目结构
[结构说明]

---
inclusion: fileMatch
fileMatchPattern: "src/api/**"
---
 
# API 开发规范
 
## 路由规范
- [API 特定规则]
 
## 错误处理
- [API 错误处理约定]

---
inclusion: manual
---
 
# 部署指南
 
## 部署流程
- [部署步骤]

# API 开发规范
 
请遵循以下 OpenAPI 规范：
#[[file:docs/api-spec.yaml]]
 
请遵循以下数据库 schema：
#[[file:prisma/schema.prisma]]

# TaskFlow 编码规范
 
## 项目概述
TaskFlow 是团队任务管理 SaaS，使用 Next.js 14 + Prisma + PostgreSQL。
 
## 通用规范
- TypeScript 严格模式，禁止 any
- 使用 named export
- 文件名使用 kebab-case
- 组件名使用 PascalCase
- 所有异步操作必须有错误处理
 
## 常用命令
- 开发：pnpm dev
- 测试：pnpm test
- 构建：pnpm build
- 数据库迁移：pnpm prisma migrate dev

---
inclusion: fileMatch
fileMatchPattern: "src/app/api/**"
---
 
# API 开发模式
 
## 路由规范
- 所有 API 路由使用 Route Handlers（app/api/ 目录）
- 请求体使用 Zod schema 验证
- 返回统一格式：{ success: boolean, data?: T, error?: string }
- 使用 NextResponse.json() 返回响应
 
## 认证
- 需要认证的路由使用 getServerSession() 检查
- 未认证返回 401，无权限返回 403
 
## 错误处理模式
```typescript
try {
  const body = await req.json();
  const validated = createTaskSchema.parse(body);
  const result = await taskService.create(validated);
  return NextResponse.json({ success: true, data: result });
} catch (error) {
  if (error instanceof ZodError) {
    return NextResponse.json({ success: false, error: "验证失败" }, { status: 400 });
  }
  return NextResponse.json({ success: false, error: "服务器错误" }, { status: 500 });
}

### 示例 2：Rust 项目的 Steering 文件集

**`.kiro/steering/rust-conventions.md`（始终包含）：**

```markdown
# Rust 项目规范

## 项目信息
rustsync — 跨平台文件同步工具，Rust 1.82，edition 2024。

## 错误处理
- 公共 API：thiserror 定义领域错误枚举
- 内部实现：anyhow::Result 简化错误传播
- 禁止 unwrap()，使用 ? 或 expect("说明")

## 日志
- 使用 tracing crate（info!, warn!, error!）
- 禁止 println! / eprintln!

## 测试
- 单元测试放在同文件的 #[cfg(test)] mod tests 中
- 集成测试放在 tests/ 目录
- 属性测试使用 proptest crate

---
inclusion: manual
---
 
# Unsafe 代码审查指南
 
当需要审查或编写 unsafe 代码时，遵循以下规则：
 
## 必须条件
- 每个 unsafe 块必须有 // SAFETY: 注释说明为什么是安全的
- 必须有对应的测试覆盖
- 优先寻找 safe 替代方案
 
## 常见场景
- FFI 调用：确保指针有效性和生命周期
- 性能关键路径：先用 safe 代码验证正确性，再优化

# Claude Code
touch CLAUDE.md
 
# Cursor
touch .cursorrules
 
# Kiro
mkdir -p .kiro/steering
touch .kiro/steering/coding-standards.md

分析当前项目的代码库，为我生成一份 [CLAUDE.md / .cursorrules / Kiro Steering 文件]。

请包含：
1. 项目概述（1-2 句话）
2. 技术栈和版本
3. 项目目录结构
4. 常用开发命令
5. 从现有代码中推断的编码规范（至少 5 条）
6. 基于代码模式推断的禁止事项（至少 3 条）

格式要求：简洁明确，每条规则一行，避免冗长解释。