语言与框架#

• 始终使用 TypeScript，开启 strict 模式
• React 组件使用函数式组件 + Hooks
• 样式使用 TailwindCSS，不使用行内样式或 CSS Module
• 使用 Next.js App Router（不使用 Pages Router）

命名规范#

• 组件文件：PascalCase（如 LoginForm.tsx）
• 工具函数文件：camelCase（如 formatDate.ts）
• 常量文件：UPPER_SNAKE_CASE（如 API_ENDPOINTS.ts）
• React 组件：PascalCase（如 UserProfile）
• 函数和变量：camelCase（如 getUserById）
• 布尔变量：以 is/has/should 开头（如 isLoading）
• 事件处理器：以 handle 开头（如 handleSubmit）

代码风格#

• 优先使用 const，避免 let，禁止 var
• 使用箭头函数，除非需要 this 绑定
• 优先使用函数式编程范式（map/filter/reduce）
• 使用解构赋值
• 每个函数不超过 30 行
• 使用 early return 减少嵌套
• 所有注释使用中文

类型定义#

• 为所有函数参数和返回值添加类型注解
• 使用 interface 定义对象类型（不使用 type 别名定义对象）
• 使用 type 定义联合类型和工具类型
• 导出所有在其他文件中使用的类型

错误处理#

• API 请求必须有 try-catch
• 用户可见的错误信息使用中文
• 控制台日志使用 English
• 使用自定义 Error 类，不使用裸字符串

目录结构#

• components/ —— 可复用组件
• app/ —— 页面路由（Next.js App Router）
• lib/ —— 工具函数和业务逻辑
• types/ —— TypeScript 类型定义
• hooks/ —— 自定义 React Hooks
• constants/ —— 常量定义 三、编写项目上下文规则 创建 .codebuddy/rules/project-context.md：

详细文件内容

项目概述#

这是一个 Vibe Coding 实训项目，使用 Next.js 14 + TailwindCSS + TypeScript 构建。

技术栈版本#

• Next.js: 14.x（App Router）
• React: 18.x
• TypeScript: 5.x
• TailwindCSS: 3.x
• Node.js: 20.x

重要约定#

• 状态管理：简单状态用 useState，复杂状态用 useReducer，跨组件用 Context
• 数据获取：优先使用 Next.js Server Components + fetch
• 表单处理：使用 React Hook Form + Zod 验证
• UI 组件：优先使用 shadcn/ui
• 图标：使用 Lucide React

API 约定#

• RESTful 风格
• 统一响应格式：{ code: number, data: T, message: string }
• 错误码：200 成功，400 参数错误，401 未授权，500 服务器错误

1）代码风格模仿术 如果你已经有一个成熟项目，可以让 AI 学习你的风格：

Step 1：提供代码样本 请阅读以下两个文件，学习其中的编码风格和模式：

@Files src/components/UserCard.tsx @Files src/hooks/useAuth.ts

记住这些文件中的：

1. 组件结构模式
2. Hook 封装方式
3. 类型定义习惯
4. 错误处理方式
5. 注释风格 Step 2：要求风格一致 现在，按照你刚才学到的风格，帮我创建一个 ProductCard 组件， 展示商品信息（图片、标题、价格、标签），点击跳转到详情页。 要求和 UserCard 保持完全一致的代码风格。 Step 3：对比验证 请对比 UserCard 和你刚生成的 ProductCard， 列出在编码风格上的差异点，并修正不一致的地方。 2）Prompt Template（模板化提示词） 为常见任务准备好模板，每次使用时填空即可：

模板 0：任务上下文（前置必填） 项目技术栈：[框架 / 语言 / 主要依赖版本] 目录规范：[组件 / 接口 / Hooks 的存放路径和命名约定] 代码规范：[ESLint/Prettier 配置 / 团队编码风格] 现有依赖限制：[是否可以引入新依赖 / 允许的依赖白名单] 关联模块：[当前任务依赖的已有模块或接口] 约束 / 禁忌：[明确禁止的操作]

模板 1：创建组件 创建一个 [组件名] 组件： 功能：[功能描述] Props：[接口定义] 状态：[需要管理的状态] 交互：[用户交互行为] 可访问性：[键盘导航 / ARIA 属性要求] 性能约束：[memo / 渲染限制等] 样式参考：[设计参考 / CSS‑Modules / 主题变量] 测试覆盖：[单元测试场景] 验收标准：[完成判定条件]

模板 2：创建 API 接口 创建一个 API 路由 [路径]： 方法：[GET/POST/PUT/DELETE] 入参：[参数说明] 出参：[返回数据结构] 校验：[参数校验规则] 安全设计：[认证、权限、脱敏] 幂等性：[是否需要幂等处理] 错误处理：[异常情况、错误体、状态码、业务错误码] 监控日志：[日志与埋点] 版本控制：[接口版本与兼容性]

模板 3：创建 Hook 创建一个自定义 Hook [Hook 名]： 用途：[解决什么问题、适用场景] 输入：[入参参数定义] 输出：[返回值定义] 副作用：[初始化、依赖变更触发副作用] 清理：[卸载 / 依赖变化需要清理的资源] 重试策略：[失败重试、超时控制] 类型约束：[泛型、类型推导] 使用示例：[调用示例代码]

模板 4：Bug 修复模版 查看从终端输出日志定位 bug： 解析该 bug：[该 bug 是什么什么类型的错误，复现步骤、影响范围、阻塞等级] 撰写修复方案：[定位 bug 的位置文件并写出修复方案给用户验证] 优化方案：[用户提出修改意见优化方案，代码异味与预防机制] 执行修复：[按照方案来编排任务修复顺序骨架，进行修复，回归测试点，回滚预案]

模板 5： 代码重构模板 整合架构：[识别并整理旧项目使用的技术，框架和架构骨架和业务分层特点写成文档，梳理代码异味清单] 重构架构：[重构所需的技术，设计模式和业务拆解与分层模式，模块接口契约] 可行性分析：[从技术债务密度、团队熟悉度、业务窗口期、测试覆盖几个方面进行重构的可行性分析，输出风险矩阵] 优先级表：[构建重构项目的优先级任务骨架，任务、负责人、工时、依赖、阶段门禁] 骨架搭建：[搭建项目骨架的形式，目录结构、CI/CD 基础设施] 模块描述：[针对每个模块进行风格和技术选型描述] 兼容性约束：[接口兼容、数据迁移、灰度发布计划] 验收标准：[质量门禁、性能基准、Review 机制]

模板 6：通用验收标准（后置检查）

•  功能正确：核心功能通过手动验证
•  测试通过：新增 / 现有单元测试、集成测试全部通过
•  类型安全：TypeScript 编译无错误，无 any 滥用
•  代码规范：通过 ESLint/Prettier，符合团队风格
•  无回归：未破坏原有功能（关键路径验证通过）
•  文档更新：README / 接口文档 / CHANGELOG 已同步更新
•  性能达标：无内存泄漏 / 无显著性能退化
•  可访问性：键盘可访问 / 语义化标签正确（如适用）
•  安全性：无敏感信息硬编码 / 无安全风险（如适用）

二、规则编写的 5 个原则 原则 说明 示例 具体 避免模糊表述 不推荐：“代码要简洁”；推荐：“每个函数不超过 30 行” 可验证 能客观判断是否遵守 不推荐：“写好代码”；推荐：“启用 TypeScript strict 模式” 有优先级 冲突时知道听谁的 “性能和可读性冲突时，优先可读性” 有例外 说明何时可以破例 “除非是第三方库的回调，否则都用箭头函数” 有示例 给出正反面代码示例 在规则中附上 Good/Bad 代码对比 三、常见反模式 反模式 1：规则太多，AI 记不住