|
|
@@ -0,0 +1,137 @@
|
|
|
+## 全局规则概览
|
|
|
+- 这是面向 agentic coding agents 的工作指引,覆盖构建、质量、风格、流程与协作。
|
|
|
+- 文件应保持最新,优先在仓库根目录维护。
|
|
|
+- 如遇新工具/工作流,应扩展本文件并在 PR 中同步讨论。
|
|
|
+
|
|
|
+## 构建/ lint/ 测试
|
|
|
+- 常用命令:
|
|
|
+ - 构建: `npm run build` / `pnpm build` / `yarn build`
|
|
|
+ - 静态检查: `npm run lint` / `pnpm lint` / `yarn lint`
|
|
|
+ - 单元测试: `npm test` 或 `npm run test`,可用 `-t` 指定测试名称
|
|
|
+ - 集成测试: `npm run test:integration`(若存在)
|
|
|
+ - 生成报告: `npm run build -- --report`
|
|
|
+- 单个测试定位与执行
|
|
|
+ - 按关键字定位:`npm test -- -t "<testName>"`
|
|
|
+ - 指定文件:`npx vitest run path/to/file.test.ts -t "<testName>"`,Jest: `npm test -- path/to/file.test.ts -t "<testName>"`
|
|
|
+ - PNPM/Yarn 资源:`pnpm test -- -t "<testName>"` / `yarn test -- -t "<testName>"`
|
|
|
+ - Vitest 的完整 CLI:`npx vitest run -t "<testName>"` 或 `npx vitest run path/to/file.test.ts`
|
|
|
+- 运行快速片段测试
|
|
|
+ - 通过关键字快速定位:`npm test -- -t "keyword"`
|
|
|
+- 持续集成与日志
|
|
|
+ - CI 应锚定一次完整测试:测试完成后再进行打包与部署
|
|
|
+ - 日志输出应明确包含:时间戳、测试名称、通过/失败、覆盖率(如有)
|
|
|
+- 提交与钩子
|
|
|
+ - 本地执行前请确保已安装依赖,`node_modules` 不应缺失
|
|
|
+ - 使用 lint/test 流程,确保提交前通过静态检查与测试
|
|
|
+
|
|
|
+## 代码风格指南
|
|
|
+- 导入与模块组织
|
|
|
+ - 外部依赖放在顶部,内部/本地导入放在后
|
|
|
+ - 使用路径别名时,优先正式路径,避免跨根引用
|
|
|
+ - 未使用的导入应清理,静态分析应通过
|
|
|
+ - 使用 `import type` 显式标注类型导入以减少运行时开销
|
|
|
+- 格式化与排版
|
|
|
+ - 统一使用 2 空格缩进
|
|
|
+ - 语句结尾使用分号,除非项目规定不使用
|
|
|
+ - 行宽约 80-120 字符,超出时换行
|
|
|
+ - 尾随逗号可在导入/对象字面量中使用,便于 diff
|
|
|
+- TypeScript 类型
|
|
|
+ - 首选 interface,联合类型使用判别性联合
|
|
|
+ - 使用 readonly 保护不可变数据
|
|
|
+ - 避免 any;若必要,尽量用 unknown,逐步收窄
|
|
|
+ - 函数参数与返回值提供明确的类型签名
|
|
|
+- 命名与风格
|
|
|
+ - 变量与函数采用 camelCase
|
|
|
+ - 类型/类使用 PascalCase,常量使用 UPPER_SNAKE
|
|
|
+ - 避免无意义缩写,含义清晰
|
|
|
+- 错误处理
|
|
|
+ - 不吞错,抛出有意义的错误信息
|
|
|
+ - 自定义错误类型,提供上下文
|
|
|
+ - 保留原始堆栈便于调试
|
|
|
+ - catch 中避免抛出模糊错误
|
|
|
+- 异常与边界
|
|
|
+ - 输入要严格校验,错误信息要具备帮助性
|
|
|
+ - 未覆盖的分支显式抛出未实现错误
|
|
|
+- 日志与追踪
|
|
|
+ - 生产环境应统一日志组件,避免裸 console.log
|
|
|
+ - 日志包含时间戳、级别、信息、上下文
|
|
|
+- 测试友好性
|
|
|
+ - 测试应可重复、可预测,避免随机性
|
|
|
+ - 覆盖边界的测试用例命名应描述性
|
|
|
+ - fixtures 放在 test/fixtures,测试后清理
|
|
|
+- 依赖与版本
|
|
|
+ - 锁定版本,避免不可预测更新
|
|
|
+ - 使用 lock 文件管理依赖
|
|
|
+- 代码审查与提交
|
|
|
+ - 提交前本地执行 lint/test,确保通过
|
|
|
+ - 提交信息遵循一致的风格,可通过 Conventional Commits 风格
|
|
|
+ - 合并冲突后给出清晰的上下文注释
|
|
|
+- 结构与可维护性
|
|
|
+ - 遵循单一职责原则,模块职责清晰
|
|
|
+ - 设计对扩展友好,遵循开闭原则
|
|
|
+ - 重要逻辑应有文档注释
|
|
|
+- 安全性
|
|
|
+ - 不将敏感信息提交到仓库
|
|
|
+ - 使用环境变量来管理机密
|
|
|
+- 性能意识
|
|
|
+ - 延迟加载、按需初始化
|
|
|
+ - 缓存可重复计算结果
|
|
|
+ - 避免在渲染周期执行昂贵计算
|
|
|
+- 兼容性
|
|
|
+ - 兼容主流运行环境,必要时使用 polyfill
|
|
|
+- 可访问性
|
|
|
+ - 考虑无障碍与测试性
|
|
|
+- 组合与模块化
|
|
|
+ - 目录结构应清晰,循环依赖最小化
|
|
|
+ - 模块通过接口通信,隐藏实现细节
|
|
|
+- 注释与文档
|
|
|
+ - 关键逻辑提供 JSDoc / TSDoc
|
|
|
+ - 重要行为描述清晰,避免歧义
|
|
|
+- 测试约定
|
|
|
+ - 测试名称具描述性,覆盖边界
|
|
|
+ - fixtures 放 test/fixtures
|
|
|
+ - 使用 setup/teardown 钩子清理环境
|
|
|
+- 运行环境与依赖
|
|
|
+ - 锁定版本,使用 lock 文件
|
|
|
+ - 构建/测试所需的依赖要在 package.json 中明确
|
|
|
+- 代码审查与协作
|
|
|
+ - 提交前本地运行 lint/test,确保通过
|
|
|
+ - 处理冲突时提供可追踪的复核信息
|
|
|
+
|
|
|
+## 项目结构与约定
|
|
|
+- 代码分层
|
|
|
+ - api/ 数据接入接口
|
|
|
+ - store/ 全局状态管理
|
|
|
+ - components/ 可复用 UI 组件
|
|
|
+ - hooks/ 自定义 Hook
|
|
|
+ - views/ 业务页面
|
|
|
+ - plugins/ 插件封装
|
|
|
+ - types/ 公共类型定义
|
|
|
+- 命名约定
|
|
|
+ - 文件/目录使用小写+连字符命名
|
|
|
+ - 变量、函数遵循 camelCase
|
|
|
+ - 类型/类遵循 PascalCase
|
|
|
+- 导出与导入
|
|
|
+ - 默认导出尽量少,命名导出优先
|
|
|
+ - 按功能模块导出,避免跨模块耦合
|
|
|
+- 测试结构
|
|
|
+ - 单元测试靠近实现、集成测试覆盖路由/接口
|
|
|
+ - 端到端测试放在 test/e2e
|
|
|
+
|
|
|
+## Cursor 规则
|
|
|
+- 如存在 Cursor 规则,请放在 .cursor/rules/,并在此处合并引用
|
|
|
+- 当前仓库未发现实际 Cursor 规则文件,将在发现后集成
|
|
|
+
|
|
|
+## Copilot 规则
|
|
|
+- 如存在 Copilot 规则,请放在 .github/copilot-instructions.md,合并引用
|
|
|
+- 当前仓库未发现 Copilot 指令文件,将在发现后集成
|
|
|
+
|
|
|
+## 质量信号与改进计划
|
|
|
+- 发现的常见信号:console/log 调试信息、TODO/FIXME、any 的使用、@ts-ignore、未使用变量
|
|
|
+- 针对这些信号,提出逐步改进计划(以 PR 形式提出)
|
|
|
+- 成功落地后标记该任务为已完成,更新计划
|
|
|
+
|
|
|
+## 维护与更新
|
|
|
+- 定期回顾 AGENTS.md 的适用性
|
|
|
+- 新工具/新框架出现时,更新本文件的版本兼容性条款
|
|
|
+- 提交变更时附带简短的变更说明,方便团队理解
|