ECC 编码风格规则Cursor 版不可变性与代码质量检查清单如何在 Agent 驱动开发中落地【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文以.cursor/rules/common-coding-style.md为核心逐条拆解 ECC 为 Cursor 场景定制的通用编码风格规则——不可变性CRITICAL 级别、文件组织、错误处理、输入验证与提交前代码质量检查清单并结合仓库中同源的 rules/common/coding-style.md 和 TypeScript 专属规则.cursor/rules/typescript-coding-style.md说明这套规则如何被alwaysApply机制自动注入会话以及它如何约束 AI Agent 在生成、修改代码时的行为边界。一、规则文件的定位一份始终生效的 Agent 行为约束common-coding-style.md是 ECC 仓库.cursor/rules/目录下的通用编码风格规则服务的是「Agent 在 Cursor 中写代码时必须遵守的风格底线」。它的 YAML frontmatter 只有两个字段但语义非常关键见.cursor/rules/common-coding-style.md--- description: ECC coding style: immutability, file organization, error handling, validation alwaysApply: true ---description用一句话概括了规则覆盖的四个主题域不可变性、文件组织、错误处理、验证alwaysApply: true意味着该规则不依赖文件通配符匹配会在 Cursor 会话中始终作为上下文注入而不是像带globs的规则那样只在编辑特定文件时才生效。这与同目录下的语言专属规则形成分层结构。以.cursor/rules/typescript-coding-style.md为例其 frontmatter 是globs: [**/*.ts, **/*.tsx, **/*.js, **/*.jsx]alwaysApply: false且文件开头明确声明 “This file extends the common coding style rule with TypeScript/JavaScript specific content”——即 common 规则是基座语言规则按文件类型叠加。整个.cursor/rules/目录按此模式组织common-*系列coding-style、patterns、hooks、security、testing、performance、agents、development-workflow、git-workflow加上 golang、kotlin、php、python、swift、typescript 六种语言各自的 coding-style / hooks / patterns / security / testing 五件套。需要说明的适用前提Cursor 平台的规则加载行为可能随 Cursor 版本变化。README 中对该适配器的描述是「Project-local.cursor/adapter」可通过./install.sh --profile minimal --target cursor将 ECC 规则选择性安装到目标项目的.cursor/下见 README.md 的 Platform Support 与安装章节。因此本文的规则解读以当前仓库中.cursor/rules/的静态内容为准。二、规则一不可变性CRITICAL——创建新对象绝不原地修改这是全文档中标注级别最高的一条标题直接带 “(CRITICAL)”原文的表述是.cursor/rules/common-coding-style.md// Pseudocode WRONG: modify(original, field, value) → changes original in-place CORRECT: update(original, field, value) → returns new copy with change规则给出的三条理由不可变数据消除隐藏副作用、让调试更容易、并支撑安全的并发。用伪代码而不是具体语言书写正是为了让这条规则跨越所有语言生效。具体到 TypeScript/JavaScript 场景ECC 在同目录的.cursor/rules/typescript-coding-style.md中把这条抽象规则落成了可执行的写法——用展开运算符spread operator做不可变更新// WRONG: Mutation function updateUser(user, name) { user.name name // MUTATION! return user } // CORRECT: Immutability function updateUser(user, name) { return { ...user, name } }从源码结构看ECC 自身对「不可变」的执行也贯彻到了配置数据层面仓库中状态存储相关模块如 scripts/lib/install-state.js、scripts/lib/state-store/ 系列普遍采用「读出—构造新对象—整体写回」而非原地改字段的模式这与规则本身的要求形成呼应。对 Agent 工作流而言这条规则的价值在于当 LLM 生成的代码反复读写同一可变对象时人很难在 Review 中定位「谁在什么时候改的」而不可变写法下每个引用都是一份可追溯的快照错误处理与并发场景见下文都因此变得更可控。三、规则二文件组织——多小文件优于少大文件原文给出四条硬性约束.cursor/rules/common-coding-style.mdMANY SMALL FILES FEW LARGE FILES总原则是「多而小」胜过「少而大」High cohesion, low coupling高内聚、低耦合200-400 lines typical, 800 max典型文件 200400 行上限 800 行Extract utilities from large modules从大模块中抽离工具函数Organize by feature/domain, not by type按功能/领域组织目录而不是按「所有组件放一起、所有工具放一起」的类型化组织。仓库中平台无关的孪生文件 rules/common/coding-style.md 对 800 行上限补充了更精细的边界说明800 行是「source files 的软性可维护性天花板soft maintainability ceiling」而测试、生成代码、vendored 文件在规模由其角色正当化时可以超出该上限。这一补充很实用——如果 Agent 机械地对所有文件执行 800 行限制可能反而把合理的测试夹具或生成产物拆碎。「按领域组织」这条同样有仓库内可对照的实例ECC 自身的规则体系就按「语言/领域」而非「类型」切分目录如 rules/python/、rules/golang/、rules/react/ 等脚本层则按能力域划分scripts/lib/ 下的 install、session、memory、state-store 等子域。这些目录结构本身即可作为「200-400 行典型 按功能组织」原则的参考样本。四、规则三错误处理——每一层显式处理绝不静默吞掉原文的 Error Handling 章节要求.cursor/rules/common-coding-style.md在每一层显式处理错误Handle errors explicitly at every level面向 UI 的代码提供用户友好的错误消息服务端记录详细的错误上下文Log detailed error context on the server side绝不静默吞掉错误Never silently swallow errors。TypeScript 专属规则把前两条具象为「async/await try-catch 的标准骨架」.cursor/rules/typescript-coding-style.mdtry { const result await riskyOperation() return result } catch (error) { console.error(Operation failed:, error) throw new Error(Detailed user-friendly message) }这个骨架体现了该规则的一个关键分工详细上下文走日志通道console.error记录原始错误对上层抛出的则是用户可读、可行动的消息。此外同文件还要求生产代码中不出现console.log应使用正式日志库并指出「See hooks for automatic detection」——即规则不止是文档约定ECC 还配了 hook 机制做自动检测Cursor 侧的 hook 适配见.cursor/hooks/adapter.js与.cursor/hooks.json。对 Agent 而言「永不静默吞错误」尤其重要LLM 生成代码时常见的catch {}空块正是这类规则要在会话过程中提前拦截的模式。五、规则四输入验证——在系统边界处验证快速失败Input Validation 章节的原文要求.cursor/rules/common-coding-style.md处理前验证所有用户输入可用时优先使用基于 Schema 的验证快速失败Fail fast并给出清晰的错误消息永不信任外部数据——API 响应、用户输入、文件内容一视同仁。「外部数据一律不信任」是面向 Agent 时代的安全底线Agent 生成的代码经常直接消费 API 响应或解析文件若边界验证缺失坏数据会沿调用链扩散且故障点远离污染源、难以归因。仓库中的 TypeScript 规则给出的标准答案是用 Zod 做 schema 验证.cursor/rules/typescript-coding-style.mdimport { z } from zod const schema z.object({ email: z.string().email(), age: z.number().int().min(0).max(150) }) const validated schema.parse(input)这段示例同时覆盖了「快速失败」的语义schema.parse对不合法输入直接抛错而不是返回「默认值掩盖问题」与规则中 “Fail fast with clear error messages” 逐字对应。ECC 仓库自身也在用「schema 化 边界验证」的实践佐证这一风格仓库根目录 schemas/ 下维护了hooks.schema.json、memory.schema.json、install-state.schema.json等一批 JSON Schema用于约束安装与运行时数据的结构这正是“Use schema-based validation where available”在配置层面的体现。六、代码质量检查清单七项可机械校验的完成标准文档最后给出了一份「标记工作完成之前」必须自查的清单.cursor/rules/common-coding-style.md完整保留如下代码可读且命名良好Code is readable and well-named函数足够小50 行文件聚焦800 行无深层嵌套不超过 4 层错误处理到位无硬编码值使用常量或配置无原地修改使用了不可变模式这份清单的设计意图值得注意七项中除了第一、五项偏主观判断外其余五项函数行数、文件行数、嵌套深度、硬编码值、mutation都是可被静态分析机械判定的指标。这使它天然适合作为 Agent 自评环节的检查表——LLM 在宣告 “任务完成” 前逐项核销比开放式自查更不容易漏项。前文提到的 800 行文件上限、50 行函数上限正是在清单中被二次锚定的硬阈值形成「正文规则 清单」双重约束。孪生文件 rules/common/coding-style.md 在同样清单之外还补充了三类与清单直接配套的规则可作为理解清单阈值的背景KISS / DRY / YAGNI三原则DRY 强调「重复是真实存在时才抽抽象不做推测性抽象」与 YAGNI 互为约束避免 Agent 过度设计命名规范变量与函数camelCase布尔值优先is/has/should/can前缀接口/类型/组件PascalCase常量UPPER_SNAKE_CASE自定义 hook 以use前缀代码坏味道深嵌套改用 early return、魔法数字改用命名常量、长函数拆分为职责单一的片段。七、这套规则在 Agent 工作流中如何起作用把以上各节串起来common-coding-style.md在 ECC 体系中的实际角色是会话级常开约束因alwaysApply: true它与语言规则的globs条件加载不同无论 Agent 正在编辑哪类文件这四个主题域的要求都在上下文中生效语言专属规则如 TypeScript 的 spread 更新、try-catch 骨架、Zod 验证、禁用console.log再按文件类型叠加细节。从约定到检测规则不止停留在提示词层面。README 说明 Cursor 侧通过.cursor/hooks/下的 hook 脚本如adapter.js、stop.js等把 Cursor 的 20 个 hook 事件适配为可复用执行规则中「See hooks for automatic detection」即指这条自动检测链路。与模式库互补同目录的.cursor/rules/common-patterns.md规定了 Repository Pattern 与统一 API 响应包络等结构性模式coding-style 管「代码怎么写」patterns 管「结构怎么搭」两者同属alwaysApply层共同构成 ECC 在 Cursor 下的代码生成基线。八、适用前提与限制本文所述规则内容均以当前仓库.cursor/rules/与rules/common/的实际文件为准.cursor/rules/common-coding-style.md与rules/common/coding-style.md存在内容差异后者多出 KISS/DRY/YAGNI、命名规范与坏味道章节且对 800 行上限有测试/生成文件豁免引用时应以对应文件版本为准。规则的运行时行为何时注入、hook 何时触发依赖 Cursor 平台版本与 ECC 安装器--target cursor的安装结果Cursor 的规则/Agent 加载行为可能随版本变化这一点 README 的 Cursor 适配章节已明确提示。规则本身是「行为约束 检查清单」不包含可执行代码文中展示的 TypeScript 示例均来自.cursor/rules/typescript-coding-style.md作为规则的参考实现而非独立库。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考