ECC coding-standards 技能跨项目编码规范、不可变模式与代码坏味道审查的完整实战指南【免费下载链接】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/ECCECCEverything Claude Code将「编码规范」沉淀为可被 Agent 直接调用的技能Skill让命名、不可变性、可读性、代码坏味道审查等跨项目公约数不再依赖团队口头约定而是变成可复用、可审计的标准化流程。本文以 ECC 仓库中的 coding-standards 技能 为主体完整解析其激活条件、作用边界、代码质量四大原则、TypeScript/JavaScript 与 React 实战规范、API 设计标准、文件组织约定、注释文档规范、性能与测试标准以及代码坏味道检测清单并结合仓库中的规则层coding-style.md、code-review.md与安装清单install-components.json补充其落地机制。读完后你可以在任何 TypeScript/JavaScript/React 项目中直接套用这套规范并理解 ECC 如何在 Agent 工作流中强制执行这些约定。一、技能定位共享底线shared floor而非框架手册coding-standards 技能的官方描述是「跨项目的基线编码规范覆盖命名、可读性、不可变性与代码质量审查框架特定模式请使用更细粒度的前端或后端技能」。它被明确定位为共享底线shared floor而不是详细的框架手册。技能文档开头的分工指引是React、状态、表单、渲染与 UI 架构 → 使用frontend-patterns技能仓储/服务分层、端点设计、校验与服务端关注点 → 使用backend-patterns或api-design技能只需要最短可复用规则层、而非完整技能走查时 → 使用 rules/common/coding-style.md。这一定位与仓库的安装体系相互印证在 manifests/install-components.json 中该组件登记为skill:coding-standards描述为「语言无关的编码标准与最佳实践」归属framework-language模块——即选择框架/语言类安装模块时它会与前端/后端模式技能一起被选中但各自职责不重叠。1.1 元数据与隐式调用该技能在.agents/skills/coding-standards/agents/openai.yaml中声明了 Agent 接口元数据interface: display_name: Coding Standards short_description: Cross-project coding conventions and review brand_color: #3B82F6 default_prompt: Use $coding-standards to review code against cross-project standards. policy: allow_implicit_invocation: true其中allow_implicit_invocation: true意味着 Agent 在判断任务属于「代码质量/命名审查且没有更细粒度框架技能适用」时可以隐式激活该技能无需用户显式指定default_prompt则给出了标准触发句式用$coding-standards按跨项目标准审查代码。另外仓库根目录下还有一份带metadata.origin: ECC的同源技能 skills/coding-standards/SKILL.md内容与.agents版本一致体现了技能在两套目录结构中的同步分发。二、激活时机与作用边界2.1 何时激活When to Activate技能文档列出了六类典型激活场景启动新项目或新模块时审查代码质量与可维护性时重构既有代码使其符合约定时强制统一命名、格式化或结构一致性时配置 lint、格式化或类型检查规则时;向新贡献者灌输编码约定onboarding时。2.2 作用边界Scope Boundaries技能对自身边界给出了双向清单这是 ECC「技能分层」设计的核心激活于——描述性命名descriptive naming不可变性默认值immutability defaults可读性、KISS、DRY、YAGNI 的强制执行错误处理预期与代码坏味道code smell审查。不作为主要来源于——React 组合、hooks、渲染模式后端架构、API 设计、数据库分层任何已有更窄 ECC 技能覆盖的领域特定框架指导。从源码结构看这条边界规则在仓库中是被系统性遵守的语言专属技能如skills/cpp-coding-standards/SKILL.md、skills/java-coding-standards/SKILL.md与框架专属技能skills/frontend-patterns/、skills/backend-patterns/与 coding-standards 并列存在于技能目录中而 rules/common/code-review.md 进一步把审查职责按语言拆分给typescript-reviewer、python-reviewer、go-reviewer、rust-reviewer等 Agent——coding-standards 负责「语言无关的公约数」具体语言问题下沉到更专的审查者避免一个技能包揽一切。三、代码质量四原则技能将代码质量原则压缩为四条每条都有可直接执行的子项3.1 可读性优先Readability First代码被阅读的次数远多于被编写的次数使用清晰的变量名与函数名自文档化代码优于注释保持格式化一致性。3.2 KISSKeep It Simple, Stupid选择能工作的最简方案避免过度设计不做过早优化易理解 取巧。3.3 DRYDont Repeat Yourself把常见逻辑抽成函数构建可复用组件跨模块共享工具函数杜绝复制粘贴式编程。3.4 YAGNIYou Arent Gonna Need It不在需要之前构建功能避免投机性泛化只在必要时增加复杂度从简单开始需要时再重构。这四条在规则层 rules/common/coding-style.md 中对应存在更短的「规则版」表述例如 DRY 一节额外补充了「当重复是真实的而非推测的才引入抽象」YAGNI 一节则补充「先简单当压力真实到来时再重构」——技能给出完整走查规则层给出一页可快速引用的底线这正是文档开头「用规则层代替完整技能」建议的落点。四、TypeScript/JavaScript 标准六个维度的可执行约定这是技能文档的主体部分全部采用 PASS/FAIL 对照示例可直接作为代码审查对照表。4.1 变量命名// PASS: GOOD: Descriptive names const marketSearchQuery election const isUserAuthenticated true const totalRevenue 1000 // FAIL: BAD: Unclear names const q election const flag true const x 1000规则层 coding-style.md 对此有更完整的命名约定表变量与函数用描述性camelCase布尔量优先is/has/should/can前缀接口、类型与组件用PascalCase常量用UPPER_SNAKE_CASE自定义 hooks 用use前缀加camelCase。4.2 函数命名动词-名词模式// PASS: GOOD: Verb-noun pattern async function fetchMarketData(marketId: string) { } function calculateSimilarity(a: number[], b: number[]) { } function isValidEmail(email: string): boolean { } // FAIL: BAD: Unclear or noun-only async function market(id: string) { } function similarity(a, b) { } function email(e) { }4.3 不可变模式标记为 CRITICAL// PASS: ALWAYS use spread operator const updatedUser { ...user, name: New Name } const updatedArray [...items, newItem] // FAIL: NEVER mutate directly user.name New Name // BAD items.push(newItem) // BAD这是整个技能中标记最重的条款。规则层给出了其伪代码形式与理由update(original, field, value)应返回带变更的新副本而非原地修改理由是「不可变数据消除隐藏副作用、让调试更容易、并支持安全的并发」。值得注意的是技能允许有充分理由的例外——在注释章节的示例中items.push(newItem)在「刻意为了大数组性能使用 mutation」的注释下被判定为 PASS说明该规范追求的是「例外必须显式声明」而不是教条。4.4 错误处理// PASS: GOOD: Comprehensive error handling async function fetchData(url: string) { try { const response await fetch(url) if (!response.ok) { throw new Error(HTTP ${response.status}: ${response.statusText}) } return await response.json() } catch (error) { console.error(Fetch failed:, error) throw new Error(Failed to fetch data) } } // FAIL: BAD: No error handling async function fetchData(url) { const response await fetch(url) return response.json() }规则层对错误处理的要求与之同构每一层显式处理错误、UI 侧给出用户友好信息、服务端记录详细上下文、绝不静默吞错。4.5 异步/并发最佳实践// PASS: GOOD: Parallel execution when possible const [users, markets, stats] await Promise.all([ fetchUsers(), fetchMarkets(), fetchStats() ]) // FAIL: BAD: Sequential when unnecessary const users await fetchUsers() const markets await fetchMarkets() const stats await fetchStats()无依赖关系的多个请求应并行执行而非串行等待。4.6 类型安全// PASS: GOOD: Proper types interface Market { id: string name: string status: active | resolved | closed created_at: Date } function getMarket(id: string): PromiseMarket { // Implementation } // FAIL: BAD: Using any function getMarket(id: any): Promiseany { // Implementation }偏好联合字面量类型active | resolved | closed收窄取值域杜绝any。五、React 最佳实践技能为 React 场景给出了四组可直接套用的模式注意边界章节已声明 React 深层模式应交给frontend-patterns这里只保留与「命名/结构/不可变」相关的公约数部分。5.1 组件结构// PASS: GOOD: Functional component with types interface ButtonProps { children: React.ReactNode onClick: () void disabled?: boolean variant?: primary | secondary } export function Button({ children, onClick, disabled false, variant primary }: ButtonProps) { return ( button onClick{onClick} disabled{disabled} className{btn btn-${variant}} {children} /button ) } // FAIL: BAD: No types, unclear structure export function Button(props) { return button onClick{props.onClick}{props.children}/button }要点Props 显式建模为接口、可选属性声明?、解构参数带默认值。5.2 自定义 Hooks// PASS: GOOD: Reusable custom hook export function useDebounceT(value: T, delay: number): T { const [debouncedValue, setDebouncedValue] useStateT(value) useEffect(() { const handler setTimeout(() { setDebouncedValue(value) }, delay) return () clearTimeout(handler) }, [value, delay]) return debouncedValue } // Usage const debouncedQuery useDebounce(searchQuery, 500)注意该示例同时体现了两条规范泛型T保持类型安全清理函数clearTimeout避免副作用泄漏。5.3 状态更新// PASS: GOOD: Proper state updates const [count, setCount] useState(0) // Functional update for state based on previous state setCount(prev prev 1) // FAIL: BAD: Direct state reference setCount(count 1) // Can be stale in async scenarios基于前值的函数式更新setCount(prev prev 1)是默认写法直接引用闭包中的旧状态在异步场景下会读到陈旧值——这与不可变原则一脉相承。5.4 条件渲染// PASS: GOOD: Clear conditional rendering {isLoading Spinner /} {error ErrorMessage error{error} /} {data DataDisplay data{data} /} // FAIL: BAD: Ternary hell {isLoading ? Spinner / : error ? ErrorMessage error{error} / : data ? DataDisplay data{data} / : null}短路与逻辑优于嵌套三元的「ternary hell」。六、API 设计标准6.1 REST 约定GET /api/markets # List all markets GET /api/markets/:id # Get specific market POST /api/markets # Create new market PUT /api/markets/:id # Update market (full) PATCH /api/markets/:id # Update market (partial) DELETE /api/markets/:id # Delete market # Query parameters for filtering GET /api/markets?statusactivelimit10offset0资源用名词复数、方法语义明确PUT 全量更新 / PATCH 部分更新、过滤与分页走查询参数。6.2 统一响应格式// PASS: GOOD: Consistent response structure interface ApiResponseT { success: boolean data?: T error?: string meta?: { total: number page: number limit: number } } // Success response return NextResponse.json({ success: true, data: markets, meta: { total: 100, page: 1, limit: 10 } }) // Error response return NextResponse.json({ success: false, error: Invalid request }, { status: 400 })成功与失败共享同一个ApiResponseT泛型外壳客户端可以按单一契约解析。6.3 输入校验Zod schemaimport { z } from zod // PASS: GOOD: Schema validation const CreateMarketSchema z.object({ name: z.string().min(1).max(200), description: z.string().min(1).max(2000), endDate: z.string().datetime(), categories: z.array(z.string()).min(1) }) export async function POST(request: Request) { const body await request.json() try { const validated CreateMarketSchema.parse(body) // Proceed with validated data } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json({ success: false, error: Validation failed, details: error.errors }, { status: 400 }) } } }这正对应规则层的「输入校验」条款在系统边界校验、优先 schema 化、快速失败并给出清晰错误信息、永不信任外部数据。校验失败时返回details: error.errors把 schema 级错误明细透出给调用方。七、文件组织与命名7.1 项目结构src/ ├── app/ # Next.js App Router │ ├── api/ # API routes │ ├── markets/ # Market pages │ └── (auth)/ # Auth pages (route groups) ├── components/ # React components │ ├── ui/ # Generic UI components │ ├── forms/ # Form components │ └── layouts/ # Layout components ├── hooks/ # Custom React hooks ├── lib/ # Utilities and configs │ ├── api/ # API clients │ ├── utils/ # Helper functions │ └── constants/ # Constants ├── types/ # TypeScript types └── styles/ # Global styles7.2 文件命名components/Button.tsx # PascalCase for components hooks/useAuth.ts # camelCase with use prefix lib/formatDate.ts # camelCase for utilities types/market.types.ts # camelCase with .types suffix规则层 coding-style.md 在此之上给出了量化约束多小文件 少大文件单文件 200–400 行为常态、800 行为软性维护上限测试、生成代码、vendored 文件可例外按功能/领域而非按类型组织目录。这套量化阈值与 rules/common/code-review.md 的审查清单完全对齐——「函数 50 行」「源文件处于 800 行软上限内或附例外理由」都直接写入了合并前的检查项。八、注释与文档8.1 何时写注释解释 WHY而非 WHAT// PASS: GOOD: Explain WHY, not WHAT // Use exponential backoff to avoid overwhelming the API during outages const delay Math.min(1000 * Math.pow(2, retryCount), 30000) // Deliberately using mutation here for performance with large arrays items.push(newItem) // FAIL: BAD: Stating the obvious // Increment counter by 1 count // Set name to users name name user.name该示例同时示范了两类合格注释解释算法选择动机指数退避防止故障期压垮 API以及为「规范例外」留痕大数组场景刻意使用 mutation。8.2 公共 API 的 JSDoc/** * Searches markets using semantic similarity. * * param query - Natural language search query * param limit - Maximum number of results (default: 10) * returns Array of markets sorted by similarity score * throws {Error} If OpenAI API fails or Redis unavailable * * example * typescript * const results await searchMarkets(election, 5) * console.log(results[0].name) // Trump vs Biden * */ export async function searchMarkets( query: string, limit: number 10 ): PromiseMarket[] { // Implementation }完整 JSDoc 应覆盖param含默认值、returns、throws与example让公共 API 的行为契约自解释。九、性能最佳实践9.1 记忆化import { useMemo, useCallback } from react // PASS: GOOD: Memoize expensive computations // Copy before sorting - Array.prototype.sort mutates in place const sortedMarkets useMemo(() { return [...markets].sort((a, b) b.volume - a.volume) }, [markets]) // PASS: GOOD: Memoize callbacks const handleSearch useCallback((query: string) { setSearchQuery(query) }, [])注意[...markets].sort(...)的写法Array.prototype.sort原地修改数组先拷贝再排序——性能技巧与不可变原则在这里合流注释行正是 8.1 节「解释 WHY」范式的实例。9.2 懒加载import { lazy, Suspense } from react // PASS: GOOD: Lazy load heavy components const HeavyChart lazy(() import(./HeavyChart)) export function Dashboard() { return ( Suspense fallback{Spinner /} HeavyChart / /Suspense ) }9.3 数据库查询// PASS: GOOD: Select only needed columns const { data } await supabase .from(markets) .select(id, name, status) .limit(10) // FAIL: BAD: Select everything const { data } await supabase .from(markets) .select(*)只取需要的列、显式限制条数。审查规则 code-review.md 的性能清单进一步补充了 N1 查询、缺分页、无界查询、缺缓存四类问题——这些是「查询侧性能」的系统化检查项与本文的列选择约束互为补充。十、测试标准10.1 AAA 结构Arrange / Act / Asserttest(calculates similarity correctly, () { // Arrange const vector1 [1, 0, 0] const vector2 [0, 1, 0] // Act const similarity calculateCosineSimilarity(vector1, vector2) // Assert expect(similarity).toBe(0) })10.2 测试命名// PASS: GOOD: Descriptive test names test(returns empty array when no markets match query, () { }) test(throws error when OpenAI API is missing, () { }) test(falls back to substring search when Redis unavailable, () { }) // FAIL: BAD: Vague test names test(works, () { }) test(test search, () { })测试名即规格说明主语 条件 期望结果如「Redis 不可用时回退到子串搜索」works、test search这类名字被明确判为坏味道。十一、代码坏味道检测清单技能将高频反模式固化为三类可检测清单这也是「审查」场景下该技能最直接的交付物11.1 长函数 50 行// FAIL: BAD: Function 50 lines function processMarketData() { // 100 lines of code } // PASS: GOOD: Split into smaller functions function processMarketData() { const validated validateData() const transformed transformData(validated) return saveData(transformed) }11.2 深层嵌套 4~5 层用早返回压平// FAIL: BAD: 5 levels of nesting if (user) { if (user.isAdmin) { if (market) { if (market.isActive) { if (hasPermission) { // Do something } } } } } // PASS: GOOD: Early returns if (!user) return if (!user.isAdmin) return if (!market) return if (!market.isActive) return if (!hasPermission) return // Do something11.3 魔法数字用命名常量替代// FAIL: BAD: Unexplained numbers if (retryCount 3) { } setTimeout(callback, 500) // PASS: GOOD: Named constants const MAX_RETRIES 3 const DEBOUNCE_DELAY_MS 500 if (retryCount MAX_RETRIES) { } setTimeout(callback, DEBOUNCE_DELAY_MS)常量命名遵循UPPER_SNAKE_CASE如DEBOUNCE_DELAY_MS带单位后缀与 4.1 节命名约定呼应。十二、与 ECC 仓库工程实践的印证技能不是孤立的文档它给出的每条阈值都能在 ECC 仓库自身的工程配置中找到执行机制。审查清单闭环。rules/common/code-review.md 把技能中的软性约定变成硬性合并门槛函数 50 行、文件 800 行或附例外理由、嵌套 ≤ 4 层、错误显式处理、无硬编码密钥、无遗留console.log、新功能有测试且覆盖率 ≥ 80%。它还定义了严重度分级——CRITICAL安全漏洞/数据丢失风险必须BLOCK、HIGH 应WARN、MEDIUM含「超过 800 行软上限且无说明」为INFO、LOW 为NOTE——这意味着「文件过长」这类坏味道会被正式记入审查意见。Lint 兜底。仓库根部的 eslint.config.js 将no-unused-vars、no-undef设为error、eqeqeq设为warn并对_前缀参数提供豁免——「未使用变量」「未定义引用」「非严格相等」这类可由工具机器判定的问题交给 ESLint技能与规则层则聚焦于机器难以判定的命名语义、结构坏味道与设计取舍形成「机器检查 规范审查」的双层防线。规则层与技能层分离。rules/common/coding-style.md 末尾附有一份「代码质量检查清单」函数 50 行、文件 800 行、嵌套 ≤ 4 层、无 mutation、无硬编码值等勾选项与技能全文形成「短规则层 完整技能走查」的两级分发Agent 可按上下文深度选择加载哪一级。十三、落地建议如何在你的项目中使用这套技能结合技能文档与 ECC 的安装体系推荐以下使用路径按模块安装该技能归属framework-language安装模块见 manifests/install-components.json在 ECC 的选择性安装流程中选择框架/语言模块即可获得 coding-standards 及配套的语言/框架技能。审查场景显式调用对 Agent 使用元数据中的默认提示「Use $coding-standards to review code against cross-project standards」或依赖其allow_implicit_invocation: true在代码质量审查任务中自动激活。分层使用日常快速对齐用规则层 rules/common/coding-style.md 的一页清单完整走查、新人 onboarding、新项目初始化时加载完整技能React 细节交给frontend-patterns服务端细节交给backend-patterns/api-design。审查前自检合并前对照 code-review.md 的清单逐项勾选按 CRITICAL/HIGH/MEDIUM/LOW 分级处理审查意见。总结ECC 的 coding-standards 技能把「命名要描述性、默认不可变、KISS/DRY/YAGNI、错误显式处理、坏味道可枚举」这些跨语言公约数组织成一份带 PASS/FAIL 对照示例、量化阈值函数 50 行、文件 800 行、嵌套 4 层和明确作用边界的可执行规范并通过规则层短清单、审查清单与 ESLint 配置三层机制保证其在 Agent 工作流中被持续执行。正如文档末尾所强调的代码质量不可谈判Code quality is not negotiable——清晰、可维护的代码才能支撑快速开发与有信心的重构。【免费下载链接】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），仅供参考