AGENTS.md 5.7 KB
全局规则概览
- 这是面向 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 的适用性
- 新工具/新框架出现时，更新本文件的版本兼容性条款
- 提交变更时附带简短的变更说明，方便团队理解