# JavaScript 代码规范（工程执行版）

## 1. 模块与职责

- 按能力分层：`core`、`runtime`、`adapters`、`tools`。
- 禁止在一个文件混合参数解析、业务编排、I/O 实现。

## 2. 代码风格

- 默认使用 ES Modules。
- 函数命名使用动词短语，布尔值使用 `is/has/can/should` 前缀。
- 单函数建议不超过 40 行；超过 60 行必须拆分。

## 3. 注释与 JSDoc

- 注释默认解释“为什么这样做”或“这里的约束是什么”，不复述代码表面行为。
- 导出的函数、共享常量、命令分发表、配置映射、持久化数据结构，若存在边界条件或复用价值，必须补 JSDoc。
- JSDoc 至少说明：用途、关键参数/返回值、数据结构字段含义；对象结构优先用 `@typedef` 明确约束。
- 内部局部变量通常不写注释；仅在兼容处理、路径归一化、迁移逻辑、性能权衡等高理解成本代码附近补简洁说明。
- 禁止无信息注释：如“设置变量”“调用方法”“进入循环”。

## 4. 健壮性

- 外部输入必须显式校验（CLI、ENV、JSON、网络返回）。
- 异常必须携带上下文字段（模块、参数、阶段）。
- 禁止静默吞错；捕获后必须重抛或统一上报。

## 5. 测试与门禁

- 新增能力至少包含 1 条成功路径 + 1 条失败路径测试。
- 建议命令：`npm run lint`、`npm test`。