aigroup-workflow 2.2.1 → 2.2.3

package/skills/java/spring-boot-engineer_zn/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: spring-boot-engineer_zn
+description: 中文版 Java / Spring Boot 工程规约与代码 Review 标准。覆盖 Jakarta Validation 参数校验、空安全工具类、常量与枚举、Lombok/POJO、异常与日志、安全、MySQL/ORM、并发、单元测试、工程分层与 Review 清单。当用中文进行 Java/Spring Boot 代码生成、改造或 Review 时加载。
+license: MIT
+metadata:
+  version: "1.0.0"
+  domain: backend
+  triggers: Java 代码规约, Spring Boot 规约, Jakarta Validation, Lombok, MyBatis, 阿里巴巴 Java 开发手册, 代码 Review, 工程分层
+  role: specialist
+  scope: standards
+  output-format: code
+  related-skills: spring-boot-engineer, java-architect
+  language: zh-CN
+---
+
+# Spring Boot 工程规约（中文）
+
+## 适用范围
+
+本 skill 以《Java 开发手册》为基准，适用于 Java / Spring / Spring Boot 项目的代码生成、修改和 Review，强制遵守命名、格式、异常日志、安全、数据库、分层与设计规约。
+
+加载时机：当用中文进行 Java / Spring Boot 代码生成、改造或 Review，且需要超出纯编码风格（见 `docs/rules/java_zn/coding-style.md`）的工程规约时，加载本 skill。生成代码时优先遵守项目现有约定；项目无明确约定时按本 skill 执行。
+
+## 参考指南
+
+按上下文加载对应参考文件：
+
+| 主题 | 参考文件 | 何时加载 |
+|------|----------|----------|
+| DTO 与参数校验 | `references/validation.md` | Jakarta Validation 注解、`@Valid`/`@Validated`、跨字段与业务校验 |
+| OOP / POJO / Lombok | `references/pojo-lombok.md` | POJO 设计、Lombok 注解组合、Builder、`@Data` 取舍 |
+| 异常与日志 | `references/exception-logging.md` | 异常处理完整规则、SLF4J 日志、脱敏 |
+| 安全 | `references/security.md` | 参数校验、权限、脱敏、SQL 注入、CSRF、幂等防刷 |
+| MySQL 与 ORM | `references/persistence.md` | 表结构规约、MyBatis、分页、事务 |
+| 并发 | `references/concurrency.md` | 线程池、`ThreadLocal`、锁、并发更新 |
+| 单元测试 | `references/testing.md` | 测试编写、覆盖范围、独立可重复 |
+| 工程结构与设计 | `references/architecture.md` | 重复代码抽象、分层依赖、单一职责、设计原则 |
+
+## 核心规约
+
+以下为高频内联规约，完整迁移自原规则。
+
+### 值判断与工具类使用
+
+- 字符串、包装类型、对象、集合、数组等值判断，应优先使用空安全工具类或 JDK 工具方法，避免直接使用 `==` / `!=` 做相等判断。
+- 字符串空白判断优先使用 `org.apache.commons.lang3.StringUtils.isBlank` / `isNotBlank`，或项目已有的 `org.springframework.util.StringUtils.hasText`。
+- 字符串相等优先使用 `org.apache.commons.lang3.StringUtils.equals` / `equalsIgnoreCase`。
+- 对象相等优先使用 `java.util.Objects.equals`。
+- Boolean 包装类型判断优先使用 `org.apache.commons.lang3.BooleanUtils.isTrue` / `isFalse`。
+- 集合或 Map 判空优先使用 `org.springframework.util.CollectionUtils.isEmpty`。
+- 数组、对象整体判空可使用 `org.springframework.util.ObjectUtils.isEmpty`。
+- 枚举相等在明确非空语义下可以使用 `EnumConstant == value`；如果枚举变量可能为 null，优先使用 `Objects.equals(value, EnumConstant)` 或将常量放左侧。
+- 基本类型大小比较仍使用 `>`、`<`、`>=`、`<=`。
+
+禁止写法：
+
+```java
+if (userName == "") {
+    return;
+}
+
+if (status == 1) {
+    return;
+}
+
+if (enabled == true) {
+    return;
+}
+```
+
+推荐写法：
+
+```java
+if (StringUtils.isBlank(userName)) {
+    return;
+}
+
+if (Objects.equals(status, ENABLED_STATUS)) {
+    return;
+}
+
+if (BooleanUtils.isTrue(enabled)) {
+    return;
+}
+
+if (CollectionUtils.isEmpty(userList)) {
+    return;
+}
+```
+
+### 常量与枚举
+
+- 禁止魔法值直接出现在代码中，应定义为常量或枚举。
+- `Long` 字面量使用大写 `L`，例如 `1L`。
+- 固定范围的状态、类型、渠道、来源等优先使用枚举。
+- 常量按功能归类，不要维护一个“大而全”的常量类。
+- 枚举类建议以 `Enum` 结尾，枚举项全大写并使用下划线分隔。
+
+### DTO 与参数校验要点
+
+- DTO 字段校验优先使用 `jakarta.validation` 注解，Controller 入参用 `@Valid` / `@Validated` 触发，嵌套对象与集合元素用 `@Valid` 级联。
+- 禁止使用 `javax.validation` 包；Spring Boot 3+ 统一 Jakarta Validation。
+- 简单字段校验交给 DTO 注解，不在 Service 中重复写 `if`；跨字段、依赖外部数据、权限幂等等复杂校验才用代码校验。
+
+> 完整规则与示例见 `references/validation.md`。
+
+### Lombok 与 POJO 要点
+
+- 创建 DO / DTO / VO / BO / Query / Command 等数据承载对象时，优先使用 Lombok 注解生成 getter、setter、构造器、`toString`、Builder 等样板代码。
+- 字段较多或可选参数较多时优先 `@Builder` + `Xxx.builder().field(value).build()`；框架反射创建对象时保留无参构造器。
+- 谨慎使用 `@Data`：涉及继承、实体、缓存 key、集合元素去重或需精确控制 `equals` / `hashCode` 的类，改用更明确的 `@Getter`、`@Setter`、`@ToString`、`@EqualsAndHashCode`。
+
+> 完整规则与示例见 `references/pojo-lombok.md`。
+
+## Review 检查清单
+
+Review Java 代码时至少检查：
+
+- DTO 字段校验是否优先使用 `jakarta.validation` 注解。
+- 是否误用了 `javax.validation`。
+- 字符串、包装类型、对象、集合判断是否使用空安全工具类。
+- 是否存在 `==` 比较字符串、包装类型或业务值对象。
+- 数据承载对象是否优先使用 Lombok 注解，字段较多的对象创建是否优先使用 Builder。
+- 是否出现魔法值。
+- 同类或跨类重复代码是否出现 3 次及以上。
+- 是否存在过深嵌套、超长方法或复杂条件表达式。
+- 异常是否被吞掉，日志是否重复打印或泄露敏感信息。
+- SQL 是否显式列字段、使用参数绑定并命中必要索引。
+- 新增核心逻辑是否有单元测试覆盖。

package/skills/java/spring-boot-engineer_zn/references/architecture.md

@@ -0,0 +1,23 @@
+# 工程结构与设计
+
+## 重复代码与抽象
+
+- 同一段或高度相似代码出现 3 次及以上，必须评估抽取。
+- 简单业务复用优先抽为 `private` 方法或领域服务方法。
+- 跨类复用优先抽为公共组件、工具类、模板方法或策略类。
+- 跨层、横切关注点优先考虑 AOP、Filter、Interceptor、注解驱动组件，例如：
+  - 登录态、权限、租户、审计、幂等、限流、防重放。
+  - 统一日志、埋点、异常转换、接口耗时统计。
+  - 重复的通用参数校验逻辑。
+- DTO 简单字段校验重复出现时，不要抽 `checkXxx` 方法，应优先回到 DTO 上加 Jakarta Validation 注解。
+
+## 工程结构与设计
+
+- 上层可以依赖下层，下层不要反向依赖上层。
+- Web 层负责协议适配、基础参数校验和转发，不承载复杂业务。
+- Service / Manager 层承载业务编排和领域逻辑。
+- DAO 层只处理持久化，不写业务逻辑。
+- 类应遵守单一职责。
+- 优先组合 / 聚合，谨慎使用继承。
+- 依赖抽象而非具体实现，保持扩展开放、修改封闭。
+- 状态超过 3 个、对象协作复杂、调用链涉及对象超过 3 个时，应考虑补充状态图、时序图或类图辅助设计。

package/skills/java/spring-boot-engineer_zn/references/concurrency.md

@@ -0,0 +1,9 @@
+# 并发规则
+
+- 线程资源必须通过线程池提供，不允许随意 `new Thread`。
+- 线程池不使用 `Executors` 快捷方法，应通过 `ThreadPoolExecutor` 明确核心参数。
+- 线程和线程池必须有可识别的业务名称。
+- `ThreadLocal` 使用后必须在 `finally` 中清理。
+- 多资源加锁必须保持一致顺序，避免死锁。
+- 并发更新同一记录必须考虑锁、版本号、幂等或唯一约束。
+- `SimpleDateFormat` 不得作为共享静态变量；优先使用 `java.time`。

package/skills/java/spring-boot-engineer_zn/references/exception-logging.md

@@ -0,0 +1,31 @@
+# 异常处理与日志
+
+## 异常处理
+
+- 异常不得用于流程控制。
+- 能通过预检查避免的 RuntimeException，不应依赖 catch 兜底。
+- catch 后必须处理、转换或记录，不允许空 catch。
+- 事务代码中 catch 后如果需要回滚，必须显式处理回滚或继续抛出异常。
+- `finally` 中禁止 `return`。
+- 流和资源优先使用 `try-with-resources`。
+- 对外接口使用统一错误码或统一响应结构；应用内部优先通过明确的业务异常表达失败。
+- 方法返回值允许为 null 时，必须通过注释、Optional 或调用约定说明清楚。
+
+## 日志规则
+
+- 使用 SLF4J 等统一日志门面，不直接依赖具体日志实现 API。
+- 日志变量拼接使用占位符，不使用字符串拼接。
+- `trace` / `debug` / 大量 `info` 日志输出前必须判断日志级别。
+- 不要重复打印同一个异常；上层已记录时下层不要重复记录完整堆栈。
+- 异常日志必须包含现场信息和异常堆栈。
+- 生产环境禁止输出敏感数据，用户敏感信息必须脱敏。
+
+示例：
+
+```java
+if (log.isDebugEnabled()) {
+    log.debug("Create user request, orgId={}, userName={}", orgId, userName);
+}
+
+log.error("Create user failed, orgId={}, userName={}", orgId, userName, exception);
+```

package/skills/java/spring-boot-engineer_zn/references/persistence.md

@@ -0,0 +1,13 @@
+# MySQL 与 ORM
+
+- 表名、字段名使用小写字母、数字和下划线，禁止保留字。
+- 表名不使用复数。
+- 表必须包含 `id`、`create_time`、`update_time` 等基础字段，除非项目规范另有说明。
+- 表达是与否的数据库字段使用 `is_xxx`，Java POJO 字段不要使用 `is` 前缀，并在映射中处理。
+- 小数类型使用 `decimal`，禁止用 `float` / `double` 存储精确金额。
+- 具备唯一业务语义的字段必须建立唯一索引。
+- 查询字段必须显式列出，禁止 `select *`。
+- MyBatis 参数使用 `#{}`，禁止 `${}` 拼接用户输入。
+- 分页查询时如果 `count` 为 0，应直接返回，不继续执行分页查询。
+- 更新记录时必须维护更新时间字段。
+- `@Transactional` 不要滥用，事务范围应尽量小且语义明确。

package/skills/java/spring-boot-engineer_zn/references/pojo-lombok.md

@@ -0,0 +1,48 @@
+# OOP 与 POJO
+
+## OOP 与 POJO 通用规则
+
+- 所有覆写方法必须添加 `@Override`。
+- 禁止使用过时类或过时方法。
+- DO / DTO / VO 等 POJO 字段必须使用包装类型，局部变量可使用基本类型。
+- POJO 类必须提供可读的 `toString`，避免遗漏关键字段；优先使用 Lombok `@ToString` 生成。
+- POJO 布尔字段不要以 `is` 开头，避免序列化和反序列化歧义。
+- 构造方法中禁止写业务逻辑；初始化逻辑放到明确的初始化方法或工厂方法。
+- `BigDecimal` 禁止使用 `new BigDecimal(double)`，应使用字符串或 `BigDecimal.valueOf`。
+- 循环体内字符串拼接优先使用 `StringBuilder`。
+- 访问控制从严，能 `private` 不 `protected`，能包内可见不 `public`。
+
+## Lombok 使用规则
+
+- 创建 DO / DTO / VO / BO / Query / Command 等数据承载对象时，优先使用 Lombok 注解生成 getter、setter、构造器、`toString`、Builder 等样板代码。
+- 常用组合：
+  - 可变 DTO / VO：`@Getter`、`@Setter`、`@ToString`、`@NoArgsConstructor`
+  - 需要全参构造：增加 `@AllArgsConstructor`
+  - 字段较多或可选参数较多：增加 `@Builder`，创建对象时优先使用 `Xxx.builder().field(value).build()`
+  - 继承结构下的 Builder：使用 `@SuperBuilder`
+  - 不可变值对象：优先使用 `@Value` 或 `@Getter` + `final` 字段，按项目约定选择
+- Jackson、MyBatis、JPA 等框架需要反射创建对象时，应保留无参构造器，例如 `@NoArgsConstructor`。
+- DTO 字段不要为了 Lombok `@Builder.Default` 设置默认值；确有业务默认值时，应在业务层、工厂方法或明确的初始化流程中处理。
+- 谨慎使用 `@Data`：纯 DTO / VO 可按项目约定使用；涉及继承、实体、缓存 key、集合元素去重或需要精确控制 `equals` / `hashCode` 的类，应改用更明确的 `@Getter`、`@Setter`、`@ToString`、`@EqualsAndHashCode`。
+
+推荐写法：
+
+```java
+@Getter
+@Setter
+@ToString
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class UserDTO {
+
+    private Long id;
+
+    private String userName;
+}
+
+UserDTO user = UserDTO.builder()
+    .id(userId)
+    .userName(userName)
+    .build();
+```

package/skills/java/spring-boot-engineer_zn/references/security.md

@@ -0,0 +1,9 @@
+# 安全规则
+
+- 用户请求传入的任何参数必须做有效性验证。
+- 用户个人页面或功能必须做权限控制，避免越权访问。
+- 敏感数据展示、日志输出、接口返回必须脱敏。
+- SQL 参数必须使用参数绑定，禁止拼接用户输入。
+- HTML 输出用户数据必须正确转义或过滤。
+- 表单和 AJAX 提交按项目规范执行 CSRF 校验。
+- 下单、支付、短信、邮件等资源消耗型接口必须考虑幂等、防重放、防刷和频率限制。

package/skills/java/spring-boot-engineer_zn/references/testing.md

@@ -0,0 +1,7 @@
+# 单元测试
+
+- 单元测试应自动化、独立、可重复执行。
+- 测试代码放在 `src/test/java`。
+- 核心业务、核心模块和缺陷修复必须补充测试。
+- 测试不要依赖外部环境顺序、数据库已有数据或测试执行顺序。
+- 对复杂分支、边界条件、异常路径、参数校验规则应覆盖测试。

package/skills/java/spring-boot-engineer_zn/references/validation.md

@@ -0,0 +1,80 @@
+# DTO 与参数校验
+
+## Jakarta Validation 优先
+
+- DTO 字段非空、长度、范围、格式等校验，必须优先使用 `jakarta.validation` 包下的注解。
+- 禁止使用 `javax.validation` 包；Spring Boot 3+ 项目统一使用 Jakarta Validation。
+- Controller 入参 DTO 使用 `@Valid` 或 `@Validated` 触发校验。
+- 嵌套对象、集合元素需要级联校验时使用 `@Valid`。
+- DTO 字段不要设置默认值，避免框架反序列化和业务语义混淆。
+
+常用注解优先级：
+
+```java
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.AssertTrue;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Positive;
+import jakarta.validation.constraints.Size;
+```
+
+推荐写法：
+
+```java
+public class CreateUserDTO {
+
+    @NotBlank(message = "用户名不能为空")
+    @Size(max = 64, message = "用户名长度不能超过64")
+    private String userName;
+
+    @NotNull(message = "组织ID不能为空")
+    @Positive(message = "组织ID必须为正数")
+    private Long orgId;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+
+    @Valid
+    @NotEmpty(message = "明细不能为空")
+    private List<CreateUserItemDTO> items;
+}
+```
+
+Controller 示例：
+
+```java
+@PostMapping("/users")
+public Result<Void> createUser(@Valid @RequestBody CreateUserDTO request) {
+    userService.createUser(request);
+    return Result.success();
+}
+```
+
+## 代码校验只作为补充
+
+- 简单字段校验不得在 Service 中重复写 `if` 判断，应交给 DTO 注解。
+- 以下场景可以使用代码校验：
+  - 跨字段关系，例如 `startTime` 必须早于 `endTime`。
+  - 依赖数据库、缓存、外部服务的业务校验。
+  - 权限、幂等、防重放、防刷等上下文相关校验。
+  - 注解表达成本过高或会显著降低可读性的复杂条件。
+- 跨字段规则优先考虑 `@AssertTrue`、自定义约束注解或类级别 Validator；仍不适合时才写业务代码校验。
+- 方法参数校验可在类上使用 `@Validated`，并在 public 方法参数上使用 Jakarta Validation 注解。
+
+示例：
+
+```java
+@AssertTrue(message = "开始时间必须早于结束时间")
+public boolean isTimeRangeValid() {
+    if (startTime == null || endTime == null) {
+        return true;
+    }
+    return startTime.isBefore(endTime);
+}
+```

package/skills/javascript/javascript-pro/SKILL.md

@@ -1,132 +1,132 @@
----
-name: javascript-pro
-description: Writes, debugs, and refactors JavaScript code using modern ES2023+ features, async/await patterns, ESM module systems, and Node.js APIs. Use when building vanilla JavaScript applications, implementing Promise-based async flows, optimising browser or Node.js performance, working with Web Workers or Fetch API, or reviewing .js/.mjs/.cjs files for correctness and best practices.
-license: MIT
-metadata:
-  author: https://github.com/Jeffallan
-  version: "1.1.0"
-  domain: language
-  triggers: JavaScript, ES2023, async await, Node.js, vanilla JavaScript, Web Workers, Fetch API, browser API, module system
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: fullstack-guardian
----
-
-# JavaScript Pro
-
-## When to Use This Skill
-
-- Building vanilla JavaScript applications
-- Implementing async/await patterns and Promise handling
-- Working with modern module systems (ESM/CJS)
-- Optimizing browser performance and memory usage
-- Developing Node.js backend services
-- Implementing Web Workers, Service Workers, or browser APIs
-
-## Core Workflow
-
-1. **Analyze requirements** — Review `package.json`, module system, Node version, browser targets; confirm `.js`/`.mjs`/`.cjs` conventions
-2. **Design architecture** — Plan modules, async flows, and error handling strategies
-3. **Implement** — Write ES2023+ code with proper patterns and optimisations
-4. **Validate** — Run linter (`eslint --fix`); if linter fails, fix all reported issues and re-run before proceeding. Check for memory leaks with DevTools or `--inspect`, verify bundle size; if leaks are found, resolve them before continuing
-5. **Test** — Write comprehensive tests with Jest achieving 85%+ coverage; if coverage falls short, add missing cases and re-run. Confirm no unhandled Promise rejections
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Modern Syntax | `references/modern-syntax.md` | ES2023+ features, optional chaining, private fields |
-| Async Patterns | `references/async-patterns.md` | Promises, async/await, error handling, event loop |
-| Modules | `references/modules.md` | ESM vs CJS, dynamic imports, package.json exports |
-| Browser APIs | `references/browser-apis.md` | Fetch, Web Workers, Storage, IntersectionObserver |
-| Node Essentials | `references/node-essentials.md` | fs/promises, streams, EventEmitter, worker threads |
-
-## Constraints
-
-### MUST DO
-- Use ES2023+ features exclusively
-- Use `X | null` or `X | undefined` patterns
-- Use optional chaining (`?.`) and nullish coalescing (`??`)
-- Use async/await for all asynchronous operations
-- Use ESM (`import`/`export`) for new projects
-- Implement proper error handling with try/catch
-- Add JSDoc comments for complex functions
-- Follow functional programming principles
-
-### MUST NOT DO
-- Use `var` (always use `const` or `let`)
-- Use callback-based patterns (prefer Promises)
-- Mix CommonJS and ESM in the same module
-- Ignore memory leaks or performance issues
-- Skip error handling in async functions
-- Use synchronous I/O in Node.js
-- Mutate function parameters
-- Create blocking operations in the browser
-
-## Key Patterns with Examples
-
-### Async/Await Error Handling
-```js
-// ✅ Correct — always handle async errors explicitly
-async function fetchUser(id) {
-  try {
-    const response = await fetch(`/api/users/${id}`);
-    if (!response.ok) throw new Error(`HTTP ${response.status}`);
-    return await response.json();
-  } catch (err) {
-    console.error("fetchUser failed:", err);
-    return null;
-  }
-}
-
-// ❌ Incorrect — unhandled rejection, no null guard
-async function fetchUser(id) {
-  const response = await fetch(`/api/users/${id}`);
-  return response.json();
-}
-```
-
-### Optional Chaining & Nullish Coalescing
-```js
-// ✅ Correct
-const city = user?.address?.city ?? "Unknown";
-
-// ❌ Incorrect — throws if address is undefined
-const city = user.address.city || "Unknown";
-```
-
-### ESM Module Structure
-```js
-// ✅ Correct — named exports, no default-only exports for libraries
-// utils/math.mjs
-export const add = (a, b) => a + b;
-export const multiply = (a, b) => a * b;
-
-// consumer.mjs
-import { add } from "./utils/math.mjs";
-
-// ❌ Incorrect — mixing require() with ESM
-const { add } = require("./utils/math.mjs");
-```
-
-### Avoid var / Prefer const
-```js
-// ✅ Correct
-const MAX_RETRIES = 3;
-let attempts = 0;
-
-// ❌ Incorrect
-var MAX_RETRIES = 3;
-var attempts = 0;
-```
-
-## Output Templates
-
-When implementing JavaScript features, provide:
-1. Module file with clean exports
-2. Test file with comprehensive coverage
-3. JSDoc documentation for public APIs
-4. Brief explanation of patterns used
+---
+name: javascript-pro
+description: Writes, debugs, and refactors JavaScript code using modern ES2023+ features, async/await patterns, ESM module systems, and Node.js APIs. Use when building vanilla JavaScript applications, implementing Promise-based async flows, optimising browser or Node.js performance, working with Web Workers or Fetch API, or reviewing .js/.mjs/.cjs files for correctness and best practices.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: language
+  triggers: JavaScript, ES2023, async await, Node.js, vanilla JavaScript, Web Workers, Fetch API, browser API, module system
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian
+---
+
+# JavaScript Pro
+
+## When to Use This Skill
+
+- Building vanilla JavaScript applications
+- Implementing async/await patterns and Promise handling
+- Working with modern module systems (ESM/CJS)
+- Optimizing browser performance and memory usage
+- Developing Node.js backend services
+- Implementing Web Workers, Service Workers, or browser APIs
+
+## Core Workflow
+
+1. **Analyze requirements** — Review `package.json`, module system, Node version, browser targets; confirm `.js`/`.mjs`/`.cjs` conventions
+2. **Design architecture** — Plan modules, async flows, and error handling strategies
+3. **Implement** — Write ES2023+ code with proper patterns and optimisations
+4. **Validate** — Run linter (`eslint --fix`); if linter fails, fix all reported issues and re-run before proceeding. Check for memory leaks with DevTools or `--inspect`, verify bundle size; if leaks are found, resolve them before continuing
+5. **Test** — Write comprehensive tests with Jest achieving 85%+ coverage; if coverage falls short, add missing cases and re-run. Confirm no unhandled Promise rejections
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Modern Syntax | `references/modern-syntax.md` | ES2023+ features, optional chaining, private fields |
+| Async Patterns | `references/async-patterns.md` | Promises, async/await, error handling, event loop |
+| Modules | `references/modules.md` | ESM vs CJS, dynamic imports, package.json exports |
+| Browser APIs | `references/browser-apis.md` | Fetch, Web Workers, Storage, IntersectionObserver |
+| Node Essentials | `references/node-essentials.md` | fs/promises, streams, EventEmitter, worker threads |
+
+## Constraints
+
+### MUST DO
+- Use ES2023+ features exclusively
+- Use `X | null` or `X | undefined` patterns
+- Use optional chaining (`?.`) and nullish coalescing (`??`)
+- Use async/await for all asynchronous operations
+- Use ESM (`import`/`export`) for new projects
+- Implement proper error handling with try/catch
+- Add JSDoc comments for complex functions
+- Follow functional programming principles
+
+### MUST NOT DO
+- Use `var` (always use `const` or `let`)
+- Use callback-based patterns (prefer Promises)
+- Mix CommonJS and ESM in the same module
+- Ignore memory leaks or performance issues
+- Skip error handling in async functions
+- Use synchronous I/O in Node.js
+- Mutate function parameters
+- Create blocking operations in the browser
+
+## Key Patterns with Examples
+
+### Async/Await Error Handling
+```js
+// ✅ Correct — always handle async errors explicitly
+async function fetchUser(id) {
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return await response.json();
+  } catch (err) {
+    console.error("fetchUser failed:", err);
+    return null;
+  }
+}
+
+// ❌ Incorrect — unhandled rejection, no null guard
+async function fetchUser(id) {
+  const response = await fetch(`/api/users/${id}`);
+  return response.json();
+}
+```
+
+### Optional Chaining & Nullish Coalescing
+```js
+// ✅ Correct
+const city = user?.address?.city ?? "Unknown";
+
+// ❌ Incorrect — throws if address is undefined
+const city = user.address.city || "Unknown";
+```
+
+### ESM Module Structure
+```js
+// ✅ Correct — named exports, no default-only exports for libraries
+// utils/math.mjs
+export const add = (a, b) => a + b;
+export const multiply = (a, b) => a * b;
+
+// consumer.mjs
+import { add } from "./utils/math.mjs";
+
+// ❌ Incorrect — mixing require() with ESM
+const { add } = require("./utils/math.mjs");
+```
+
+### Avoid var / Prefer const
+```js
+// ✅ Correct
+const MAX_RETRIES = 3;
+let attempts = 0;
+
+// ❌ Incorrect
+var MAX_RETRIES = 3;
+var attempts = 0;
+```
+
+## Output Templates
+
+When implementing JavaScript features, provide:
+1. Module file with clean exports
+2. Test file with comprehensive coverage
+3. JSDoc documentation for public APIs
+4. Brief explanation of patterns used