Appsmith 的 Cursor AI 协作开发规范：.cursor 目录设计、规则体系与工程实践-北京尧图网络

Appsmith 的 Cursor AI 协作开发规范.cursor 目录设计、规则体系与工程实践【免费下载链接】appsmithPlatform to build admin panels, internal tools, and dashboards. Integrates with 25 databases and any API.项目地址: https://gitcode.com/GitHub_Trending/ap/appsmith这篇技术指南以仓库根目录的 .cursor/README.md 为入口系统讲解 Appsmith 如何利用 Cursor AI 的rules、settings.json、hooks与docs构建一套面向全栈 AI 辅助开发的工程纪律从提交信息、语义化 PR、测试生成到性能优化与 bug/feature 验证闭环。读完你可以复刻这套「规则驱动 AI 编码」的组织方式并直接对照 Appsmith 的app/client与app/server真实代码结构使用其中每条命令与配置。这份配置解决什么问题Appsmith 是一个前端React/TypeScript位于app/client与后端Java/Spring Boot/WebFlux位于app/server并存的大型代码库。当 AI 编码助手参与日常开发时最大的风险不是「不会写代码」而是不懂项目规约命名风格、测试框架、提交格式、目录语义、性能红线处处可能跑偏。.cursor目录正是为此而生——它把散落在文档里的工程约定变成 Cursor AI 可以自动读取、校验与执行的规则集合。.cursor/README.md是这一整套机制的总入口声明了目录结构与每个子目录的职责该配置提供的核心能力提交信息规则、代码质量校验、测试要求、性能指南、文档支持仓库级 Workspace 规则的速查派生文件注释风格、Cypress 运行方式。配置的整体架构一份可以「照抄」的目录布局.cursor/README.md给出了这套配置的顶层设计.cursor 目录实际布局与之一致.cursor/ ├── settings.json # 主配置文件代码库地图、测试/质量命令、Git 规约 ├── docs/ # 文档层 │ ├── guides/ # 深度指南性能、测试、验证 │ ├── references/ # 快速参考代码库地图、测试参考、技术细节 │ └── practices/ # 最佳实践React Hooks ├── rules/ # 规则层按类别划分 │ ├── commit/ # 提交相关语义化 PR 校验 │ ├── quality/ # 代码质量性能优化器、React Hook 规范 │ ├── testing/ # 测试测试生成器 │ └── verification/ # 验证bug fix / feature / workflow 验证 ├── hooks/ # Git 钩子与自动化脚本 ├── lessons.md # 经验沉淀踩坑记录 ├── index.mdc # Cursor 规则的统一入口文件 └── incremental_learning.json # 增量学习采集配置关键点在于分层settings.json回答“项目长什么样、命令怎么跑”rules/回答“什么行为符合规范、如何自动校验”docs/提供深度背景hooks/负责把约定固化为脚本。README 也明确建议使用者「在本仓库开发时直接遵循这些规则以保持一致的质量」。settings.json先让 AI 读懂项目再谈遵守规范.cursor/settings.json 是全套配置的「项目知识底座」内容远比 README 更细主要分六大块代码库地图codebase.structure——把路径语义直接写给 AI键值含义codebase.structure.frontendapp/client前端代码根目录codebase.structure.backendapp/server后端代码根目录codebase.structure.infrastructuredeploy部署与基础设施Helm/Ansible/Docker 等codebase.structure.workflows.github/workflowsCI 工作流目录codebase.structure.scriptsscripts脚本目录前后端代码标准前端测试文件匹配*.test.ts、*.test.tsx仓库中可见大量同类同目录测试如src下的组件与工具测试代码风格为 airbnblinter 为 eslint prettier后端测试匹配**/*Test.java、**/*Tests.java代码风格为 googlelinter 为 spotless。质量检查清单development.qualityChecks——把「检查什么」固化为可复现命令前端yarn run test:unit单元测试、yarn run check-types类型检查、yarn run lintlint、npx cypress run端到端测试、CI 中的循环依赖检查后端单元测试、集成测试、spotless 检查、资源泄漏检查通用敏感数据检查、错误处理、性能影响、向后兼容性。Git 工作流分支命名约定为fix/fix-name与feature/feature-name提交信息要求「描述性且带 issue 引用」并启用语义化 PR 校验详见下文。测试框架声明前端单元测试用 jestyarn run test:unit集成测试用 cypressnpx cypress run --spec spec path --browser chrome后端单元/集成测试均为 junit分别匹配**/*Test.java与**/*IntegrationTest.java。这些声明与实际代码库吻合前端在app/client根配置了 jest.config.js端到端用例集中在 app/client/cypress后端则是标准的 JUnit/Spring Boot 测试体系。CI 工作流清单client-build.yml、server-build.yml、ci-test-limited.yml、client-unit-tests.yml、server-integration-tests.yml。增量学习incrementalLearning.enabled true采集**/*.java、**/*.ts、**/*.tsx、**/*.yml、**/*.yaml、**/*.md、**/*.json等模式并存储代码/测试/构建/工作流四类模式配合仓库内的 .cursor/incremental_learning.json 使用。规则层rules/把验证做成可执行的.mdc文件.cursor/rules/README.md 定义了规则的组织方式每个规则是一个 Markdown Cursor.mdc文件内部包含三部分——元数据名称、描述、触发条件、逻辑实现校验的代码片段、文档用法示例。规则按事件自动触发创建/更新 PR、修改文件、执行特定命令也可以手动触发。rules/下的实际规则文件按类别归档commit/semantic-pr-validator.mdc——校验 PR 标题符合 Conventional Commits 规范quality/performance-optimizer.mdc定位性能瓶颈并给出优化建议、react-hook-best-practices.mdcReact Hooks 最佳实践testing/test-generator.mdc——分析代码变更并生成相应测试verification/bug-fix-verifier.mdc、feature-verifier.mdc、workflow-validator.mdc——分别验证 bug 修复、功能实现与开发工作流。目录中还有面向技术栈与行为的规则frontend.mdc、backend.mdc、infra.mdc、playwright.mdc配合 .cursor/skills 下的 Playwright 诊断/修复/编写三个 Skill 使用、agent-behavior.mdc 以及regen-helm-schema.mdcHelm schema 再生成。统一入口 .cursor/index.mdc是这套规则的「元规则」它在前置 YAML 头中声明alwaysApply: true、name: Appsmith Cursor Rules、version: 1.0.0触发事件覆盖pull_request.created、pull_request.updated、file.created、file.modified与command: cursor_help。同时它汇总了全部可用命令命令作用validate_pr_title检查 PR 标题是否符合 Conventional Commits 格式verify_bug_fix --pullRequest123验证某个 bug 修复实现generate_tests --filesrc/utils/helpers.js为指定文件生成测试optimize_performance --filesrc/components/Table.tsx分析并优化指定文件性能validate_feature --pullRequest123验证功能实现cursor_help在命令面板显示可用命令与使用指引行为可通过 .cursor/settings.json 定制且无需额外安装——激活方式是「运行cursor_help」后按指引使用。提交信息与语义化 PR人机一致的 Git 规约.cursor/README.md明确规定提交信息必须简洁且单行必须以动词开头如 adds、removes、updates对重大变更采用「标题空行详细描述」的结构Heading Detailed description.cursor/rules.json 将以上规则形式化允许的动词前缀为adds、removes、updates、fixes、refactors、implements、improves重大变更使用「标题描述空行分隔」。而在 PR 层面.cursor/settings.json 的gitWorkflow.semanticPR采用了更标准的 Conventional Commits 格式type(scope): description配置键值enabledtruetitleFormattype(scope): descriptionvalidTypesfeat、fix、docs、style、refactor、perf、test、build、ci、chore、revertscopeRequiredfalsescope 可选titleValidationtrue校验 PR 标题commitsValidationfalse暂不校验逐条提交两套规范的关系可以理解为仓库内提交走「动词式简洁单行」跨仓库协作的 PR 走「Conventional Commits 语义化标题」由 semantic-pr-validator.mdc 在 PR 事件触发时自动把关。Workspace 规则为 Appsmith 代码库定制的强制约定.cursor/README.md末尾的「Workspace Rules」是本仓库最个性化的部分rules.json又补充了 React Hooks 细则。派生文件的注释风格规定使用/*** */而非//注释这一约定针对的是由工具链自动生成或受版本控制的派生文件避免歧义并保持生成内容一致。Cypress 测试的运行方式——这是与仓库实操最直接相关的一条# 必须在 app/client 目录下执行 yarn cypress run --browser chrome --headless --spec {fileName}执行目录固定为app/client传入的{fileName}相对app/client解析例如实际用例位于 app/client/cypress/e2e如Regression/、Sanity/等目录下的 spec 文件.cursor/settings.json 与仓库脚本如 app/client/cypress/setup-test-ci.sh 采用的 CI 思路均以 Chrome 无头模式为基准保证本地与 CI 行为一致。React Hooks 最佳实践来自 rules.json 的reactHooks.bestPractices必选开启——直指 Appsmith 前端Redux 大量自定义 Hook的高频坑安全嵌套属性访问使用lodash/get或可选链optional chaining读取嵌套属性防止状态不完整时抛错防止循环依赖用useRef记录 previous 值并实现有方向的更新directional updates而不是盲目同步提前返回当值未变化时提前return避免无谓更新深比较对对象/数组使用深等比较而不是靠引用相等触发 effect。这些规则不是空泛口号——.cursor/docs/guides/testing.md 提供了对应的测试模式不完整 Redux state 下 selector 的默认值测试、Error Boundary 兜底测试、safeGet工具测试与rules.json互相印证。文档层指南、参考与最佳实践.cursor/README.md与 .cursor/docs/README.md 明确给出使用导航新开发者从 codebase-map.md代码库地图与 technical-details.md技术细节入手功能开发查阅 testing.md 测试指南与 feature 验证流程修 bug参考 verification.md 验证流程与 bug fix 校验规则性能优化跟随 performance.md 性能指南。其中值得展开的两份指南实际内容都相当扎实**测试指南testing.md**以代码库真实技术栈为依据前端单测用 Jest测试文件.test.ts/.test.tsx与源码同目录放置并提供组件Testing Library 的render/screen/fireEvent与 Redux sliceconfigureStore的完整示例Redux 安全模式测试不完整 state、Error Boundary、安全取值工具——对应上文 React Hooks 规则的「防御性编程」集成/E2E 用 Cypress按用户视角验证如编辑器画布拖入 widget、选中后打开属性面板后端用 JUnit 单测SpringBootTestStepVerifier断言 WebFluxMonoWebTestClient集成测试运行命令前端cd app/client yarn run test:unit后端cd app/server ./mvnw test可加-DtestApplicationServiceTest指定类目标与最佳实践关键路径 80% 覆盖率、测试独立隔离、测行为而非实现、避免act()与异步竞态问题。**性能指南performance.md**给出了与 Appsmith 前后端架构对应的排查清单前端关注不必要重渲染useMemo/React.memo、列表 key、包体与代码分割、effect 清理防泄漏后端关注 N1 查询、MongoDB 索引Indexed、响应式流中的阻塞操作subscribeOn(Schedulers.boundedElastic())、大对象流式处理与背压——并建议按「建立基线 → 定位瓶颈 → 逐项优化 → 对比验证 → 持续监控」五步工作流推进配合 performance-optimizer.mdc 自动化。经验沉淀机制lessons 与增量学习这套体系最独特的设计是让过往踩坑反哺规则。仓库中存在两个显式载体.cursor/lessons.md按「日期上下文症状修复教训」结构记录的实战笔记。从源码结构看其主题与 Appsmith 技术栈高度吻合例如Spring Boot 大版本升级破坏内部 API 覆写软删除SoftDeleteMongoQueryLookupStrategy覆写逻辑静默失效需检查Override与编译告警Plugin领域对象跨越「Cloud Service→ServerWebClient 反序列化→MongoDB→Server→ClientJsonView序列化」三类边界、JsonView只控制出站不控制入站Playwright 语义定位失败FormGroup未生成真正的label for时应沿getByRole → getByLabel → getByPlaceholder → getByTestId优先级链降级而非直接跳回原生 CSS 选择器Appsmith 编辑器 URL 中application、page-是字面量而非占位符widget 的 CSS 类名带widget后缀.t--widget-textwidget版本化组件如inputwidgetv2例外等.cursor/incremental_learning.json 与 settings.json 中的incrementalLearning开关把 Java/TS/TSX/YAML/Markdown/JSON 纳入模式采集持续积累「代码/测试/构建/工作流」四类模式让 AI 对仓库的了解随使用次数增长而非每次从零探测。Hooks把约定固化成可安装的 Git 钩子.cursor/hooks/README.md 展示了如何把.cursor里的自动化脚本接入本地 Git# 1. 进入仓库根目录 # 2. 将 hooks 复制到本地 .git/hooks 并赋予执行权限 cp .cursor/hooks/scripts/* .git/hooks/ chmod x .git/hooks/*hooks 目录内包含 update-docs.sh依据代码变更自动更新文档保持文档与代码同步及其规则说明 auto-update-docs.mdc。也支持手动执行.cursor/hooks/scripts/update-docs.shREADME 特别提醒需要定制钩子时请复制到本地.git/hooks再改不要直接改动.cursor内的脚本——因为仓库拉取更新会覆盖这些文件。这与 settings.json 中preCommit.hooks类型检查、lint、单元测试、敏感数据检查的意图一致把本地提交前的最后一道关也交给自动化。两条典型工作流规则如何驱动 AI 完成真实开发settings.json 的development.workflow把 bug 修复与功能开发都定义成了 AI 可逐条执行的任务清单Bug 修复工作流理解 bug 报告并在本地复现 → 通过代码探索定位根因 → 编写能复现 bug 的失败测试 → 实现修复使测试通过 → 确保全部既有测试通过 → 验证修复确实解决原始问题 → 执行 pre-commit 检查 → 确认 GitHub 工作流可通过。同时 rules.json 要求 bug 修复必须有单测验证具体修复且无回归涉及用户可见行为的改动还须有 E2E 测试。功能开发工作流理解需求与验收标准 → 设计方案 → 按需创建单测/集成/E2E 测试 → 实现功能 → 验证满足验收标准 → 保证性能与效率 → 遵循项目标准 → pre-commit 检查 → 确认 CI 通过。复杂功能须有集成测试用户可见功能须有 E2E 测试。这两条工作流与 bug-fix-verifier.mdc、feature-verifier.mdc 共同构成了「任务 → 校验 → 验证」的完整闭环也是本仓库 AI 协作质量的核心保障。实践建议如何在自己的仓库落地这套模式先建settings.json的地图把 frontend/backend/infra/scripts 的真实路径、测试框架与运行命令写清楚这是 AI 一切判断的基础用.mdc规则承载「会重复踩的坑」优先从 commit 格式、测试必写项、代码风格三条入手格式参照 index.mdc 的前置 YAML名称、描述、触发事件把踩坑记录成 lessons参考 .cursor/lessons.md 的「症状/修复/教训」模板让每次事故都变成 AI 的长期记忆把能脚本化的交给 hooks文档同步、schema 再生成这类机械任务用update-docs.sh模式的脚本固化入口统一像 index.mdc 一样提供一份总纲配合cursor_help让任何开发者一进来就知道有哪些命令、怎么激活。对 Appsmith 仓库而言.cursor的价值在于把「一份大型全栈代码库的隐性规约」显性化为 AI 可读、可执行、可进化的配置资产——README是说明书settings.json是项目认知rules/是行为守则lessons.md是历史经验它们共同组成了现代 AI 辅助开发中「工程纪律」的一种可移植范式。【免费下载链接】appsmithPlatform to build admin panels, internal tools, and dashboards. Integrates with 25 databases and any API.项目地址: https://gitcode.com/GitHub_Trending/ap/appsmith创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Appsmith 的 Cursor AI 协作开发规范：.cursor 目录设计、规则体系与工程实践

相关推荐

Tabby 用量收集（Usage Collection）机制详解：采集内容、上报原理与关闭方法

用C4模型重新理解架构图：四层抽象与实战规范

从数据模型到事件总线：一体化协同办公底层的设计逻辑

更多资讯

海思芯片采购避坑指南：从型号选型到正品验证的实战解析

低功耗开发入门：安卓与嵌入式功耗优化核心技能拆解

Linux磁盘空间占用排查实战：理解df与du，善用lsof与inode

PaddleOCR Text Gestalt 文本图像超分辨率算法：从论文原理到训练、评估与推理部署实战

NDIS 6驱动zip包安装与排错全指南

Supabase 怎么在 Postgres 中用 Vault 存储加密密钥并在 SQL 中引用？

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？