ECC 的 TypeScript/JavaScript 编码风格规则从不可变性与 Zod 校验到 Hook 自动检测【免费下载链接】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本篇基于 ECC 仓库中的 Cursor 规则文件.cursor/rules/typescript-coding-style.md展开系统讲解其中四条 TypeScript/JavaScript 编码风格约定——不可变更新、async/await 错误处理、Zod 输入校验与console.log禁令——的完整写法并结合仓库源码剖析这些规则如何通过 Hook 机制scripts/hooks/check-console-log.js等在 Agent 会话中自动执行帮助你既能在人写代码时直接复用这套规范也理解其底层自动化实现。规则文件的定位Cursor Rules 的通用 语言两层结构ECC 仓库为 Cursor 提供了一组可版本化的编码规则位于 .cursor/rules/ 目录。该目录下按通用common- 语言专属两层组织.cursor/rules/common-coding-style.mdalwaysApply: true所有语言共享的编码风格基线不可变性、错误处理、输入校验、代码质量清单.cursor/rules/typescript-coding-style.mdTypeScript/JavaScript 专属扩展开头明确写着 This file extends the common coding style rule with TypeScript/JavaScript specific content.。后者的 YAML front matter 定义了它的加载条件--- description: TypeScript coding style extending common rules globs: [**/*.ts, **/*.tsx, **/*.js, **/*.jsx] alwaysApply: false ---三个字段的作用字段取值含义descriptionTypeScript coding style extending common rules规则描述供规则列表检索展示globs**/*.ts、**/*.tsx、**/*.js、**/*.jsx仅当上下文涉及这四类文件时触发注入alwaysApplyfalse非全局常驻按 glob 匹配按需生效这种按文件类型触发的设计正是 Cursor Rules 的核心机制与alwaysApply: true的通用规则互补避免把 TS 专属内容塞进每个文件的上下文中从而节省 token、减少无关干扰。核心约束一不可变更新Immutability规则文件给出的标准范式是禁止原地修改用 spread 返回新对象// WRONG: Mutation function updateUser(user, name) { user.name name // MUTATION! return user } // CORRECT: Immutability function updateUser(user, name) { return { ...user, name } }这条约束并非 TS 特有——它在 .cursor/rules/common-coding-style.md 中被标记为CRITICAL并给出理由不可变数据能消除隐藏副作用、降低调试成本、支持安全并发。同一文件还配套了量化约束函数 50 行、文件 800 行、嵌套不超过 4 层、无硬编码值作为标记工作完成前的检查清单。值得注意的是仓库在同一规范下存在一个扩展版rules/typescript/coding-style.md。它在 Cursor 版的四个章节之上前置了更完整的类型设计约定例如公共 API 显式类型导出函数必须标注参数与返回类型局部变量可交给推断interface vs type可能被扩展/实现的形状用interface联合、交叉、映射、工具类型用type优先字符串字面量联合而非enum避免any外部/不可信输入用unknown再安全收窄泛型用于类型取决于调用方的场景// WRONG: any removes type safety function getErrorMessage(error: any) { return error.message } // CORRECT: unknown forces safe narrowing function getErrorMessage(error: unknown): string { if (error instanceof Error) { return error.message } return Unexpected error }React Props用命名interface定义 props、显式标注回调类型、无特殊理由不用React.FC纯 JS 文件在无法迁移到 TS 时用 JSDoc 表达类型且要求 JSDoc 与运行时行为保持一致。从源码结构看.cursor/rules/Cursor 侧与rules/Claude/通用侧两份规则内容高度同构、互为镜像ECC 通过这种双份维护让不同 Agent 客户端加载各自格式的同一套规范。写作 TS 代码时建议以扩展版为完整清单先过类型设计再过下文的四条实操约束。核心约束二async/await try-catch 错误处理规则文件要求异步操作统一使用 async/await 配 try-catch而不是裸.then/.catchtry { const result await riskyOperation() return result } catch (error) { console.error(Operation failed:, error) throw new Error(Detailed user-friendly message) }关键点在于两层信息分离console.error落详细错误上下文服务端/开发侧可见重新抛出的Error携带面向用户的友好信息UI 侧可见。这与通用规则中UI 面向代码给友好信息、服务端记详细上下文、绝不静默吞错的要求一一对应。扩展版 rules/typescript/coding-style.md 把该模式升级为完整可运行示例catch 参数标注unknown、通过instanceof Error收窄、用可替换的生产级 logger 接口注释建议 pino/winston替代console.errorasync function loadUser(userId: string): PromiseUser { try { const result await riskyOperation(userId) return result } catch (error: unknown) { logger.error(Operation failed, error) throw new Error(getErrorMessage(error)) } }核心约束三Zod 模式化输入校验规则文件指定 Zod 作为边界校验的标准方案import { z } from zod const schema z.object({ email: z.string().email(), age: z.number().int().min(0).max(150) }) const validated schema.parse(input)配套的通用规则要求在系统边界校验所有输入、快速失败、永不信任外部数据API 响应、用户输入、文件内容。扩展版进一步给出了类型联动写法——用z.infer从 schema 推导输入类型使校验逻辑与类型定义单一来源const userSchema z.object({ email: z.string().email(), age: z.number().int().min(0).max(150) }) type UserInput z.infertypeof userSchema const validated: UserInput userSchema.parse(input)这意味着parse成功后返回值的类型即UserInput下游函数签名可以直接消费该类型无需手写一遍字段声明。核心约束四console.log 禁令与自动检测规则文件第四条约定生产代码中不允许console.log语句应使用正规的 logging 库替代See hooks for automatic detection——即该约定不只靠人遵守而是由 Hook 机制自动检测。这一见 Hook的指向在仓库中有完整的实现链路可以印证1. 规则侧的声明.cursor/rules/typescript-hooks.md.cursor/rules/typescript-hooks.md 与编码风格规则使用完全相同的globs和alwaysApply: false声明了 TypeScript 文件相关的 HookPostToolUse配置于~/.claude/settings.jsonPrettier 编辑后自动格式化、编辑.ts/.tsx后运行tsc类型检查、对编辑文件中的console.log发出警告Stop会话响应结束前对所有已修改文件做console.log审计。2. 实现侧的落地check-console-log.jsStop 钩子的实际实现位于 scripts/hooks/check-console-log.js。阅读源码可以看到几个工程细节检测范围通过getGitModifiedFiles([\\.tsx?$, \\.jsx?$])只扫描本轮 git 已修改的 JS/TS 文件而非全仓库控制开销豁免模式EXCLUDED_PATTERNS排除了测试与脚本场景——.test./.spec.文件、*.config.js/ts、scripts/目录、__tests__/、__mocks__/因为在这些地方console.log往往是有意为之只警告不阻断命中后仅log([Hook] WARNING: console.log found in ...)并提示提交前移除退出码保持 0符合 hooks 架构中Stop 钩子可分析但不能阻断的定位ECC 透传约定stdin 原样回写到 stdoutpassThroughAndExit且设置了 1MB 的 stdin 上限——超限的截断 JSON 不再回显以免触发 harness 的 JSON 校验失败源码注释明确指向 issue #2090。该钩子在 hooks/hooks.json 的Stop数组中以stop:check-console-log注册运行于standard,strict配置档位同一数组中还有stop:format-typecheck批量 Prettier/Biome 格式化 tsc类型检查注释说明在 Stop 时一次性运行而非每次 Edit 后。3. 使用与开关按 hooks/README.md 的说明这套 Hook 不建议手工粘贴hooks.json而是通过安装器解析安装bash ./install.sh --target claude --modules hooks-runtime --enable-hookspwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks安装后可用环境变量控制行为而不改配置ECC_HOOKS_ENABLED总开关、ECC_HOOK_PROFILEminimal | standard | strict默认standard、ECC_DISABLED_HOOKS按 ID 逗号分隔禁用特定钩子例如可禁用 console 相关检查。4. 仓库自身的 lint 佐证ECC 仓库对 JS/TS 的静态检查基线见 eslint.config.jsecmaVersion: 2022、默认sourceType: commonjs.mjs单独声明为 module启用no-unused-vars^_前缀豁免、no-undeferror与eqeqeqwarn并 ignore 了.cursor/**、workflows/**/*.workflow.*等目录——这也解释了为何.cursor/rules/下的规则脚本不受本仓库 lint 约束。可以推断规则文档中使用正规 logging 库而非 console.log的要求最终由 ESLintno-console类规则可自定义 Stop 钩子双层兜底。规则全景四条约定的完整继承关系约定通用基线common-coding-style.mdTS/JS 专属typescript-coding-style.md扩展版rules/typescript/coding-style.md不可变CRITICALcreate new, never mutatespread 更新范式增加ReadonlyT参数标注错误处理显式处理、友好信息 详细日志、不静默吞错async/await try-catchunknown收窄 logger 接口输入校验边界校验、快速失败、不信任外部数据Zod schema 示例增加z.infer类型推导console.log未单列生产禁用、用 logging 库、Hook 自动检测同左类型设计未涉及未涉及公共 API 类型、interface/type 取舍、禁 any、Props、JSDoc小结如何把这套规则用在自己的项目里直接复用规则文件.cursor/rules/下common 语言两层规则是纯 Markdown YAML front matter可整体拷贝到目标仓库的 Cursor 规则目录globs与alwaysApply字段的组合方式全局基线常驻、语言规则按文件类型触发值得照搬规范 自动化闭环ECC 的示范价值在于每条约定都有执行器——console.log 有scripts/hooks/check-console-log.js格式化/类型检查有stop:format-typecheck。落地规则时同步配置对应 lint/钩子比纯文档约束有效得多注意适用前提Hook 部分依赖 Claude Code 的 hooks 机制PreToolUse/PostToolUse/Stop事件PreToolUse 可用退出码 2 阻断PostToolUse/Stop 只分析不阻断且需通过install.sh --target claude --modules hooks-runtime --enable-hooks安装以获得按实际 Claude 根目录重写的命令minimal/standard/strict三档 profile 决定检查严格度默认standard。综合来看.cursor/rules/typescript-coding-style.md本身是一份高度精炼的 Agent 规则四条约定覆盖了 TS/JS 生产代码中最常见的四类质量风险而 scripts/hooks/check-console-log.js、hooks/hooks.json 与 rules/typescript/coding-style.md 则分别提供了它的自动化执行与类型层扩展三者共同构成了 ECC 规则即代码风格体系在 TypeScript 场景下的完整落点。【免费下载链接】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），仅供参考