AI 行为准则

本文档用于定义 AI 在本项目中的行为和遵循的规范。

语言规范

• 所有由 AI 生成或修改的文档、代码注释、版本控制提交信息等，默认使用中文编写。
• 在与用户交流时，应默认使用中文。
• 各领域专有词汇，该用其他语言就用其他语言。

文档

文档原则

• 只保留必要文档
• 文档内容应精准、及时更新
• 重要信息要精确精简，避免冗余

常规文档

• README.md - 项目描述和使用指南
• TESTING.md - 测试指南（如何运行测试、覆盖率要求）
• DEPLOYMENT.md - 部署指南
• DEV_NOTE.md - 开发过程中积累的需要长期关注的事情，比如框架新知识、环境配置等

临时文档

• WIP.md - 开发计划、任务分解、待办事项等，主要面向中短期
• TODO.md - 长期可能需要关注的开发计划

开发流程

• 拿到一个任务，先做计划，分解任务，列出 todo，写入 WIP.md
• 针对目标编写测试用例
• 逐项完成 todo，并确保测试通过
• 如有需要，记录文档以备不时之需
• 测试通过，验收完成之后，清理文档，将重要事项并入常规文档

代码规范

• 除非专门提及，否则默认使用 TypeScript，尽可能把类型写好
• 默认的执行环境是最新版本的 Node.js，可以直接执行 .ts 文件
• 不要用 JSDoc，用 TypeScript 类型系统，不要 any
• 命名
  • 变量和函数使用驼峰命名法（camelCase）
  • 类和接口使用帕斯卡命名法（PascalCase）
  • 常量使用全大写加下划线（UPPER_SNAKE_CASE）
  • 文件和目录使用小写加连字符（kebab-case）
  • 避免使用缩写，除非是广泛认可的缩写
  • 函数使用动词或动宾短语命名，类使用名词命名，bool 变量使用 is/has/can 开头
• 使用图标时，应使用 SaveIcon 而不是 Save，避免引发歧义
• 不要使用 const handleXXX = () => {} 声明函数，使用 function handleXXX() {} 来声明
• 不要内嵌 SVG，使用第三方图标库，比如 lucide
• 单组件、库、脚本的长度不要超过 400 行，尽量控制在 300 行附近

环境约定

• 我使用 node.js >= 24，可以直接运行 ts 文件，即使写脚本也不需要考虑 JS
• 同上，不需要 tsc 或者 ts-node
• 使用 pnpm

安全

• 不要访问项目里面的 .env 文件
• 如果你需要做一些操作，必须 .env，可以通过编写脚本，由我运行。比如，你要从数据库同步一些数据当作参考，就可以这么做。