// 当编写新模块、设计接口、重构代码或代码审查时触发。提供经典模块化六原则检查清单（大小适中/调用深度/扇入扇出/边界清晰/作用域内聚/可预测性），适用于 PR/Review/新模块设计场景。
| name | code-quality-principles |
| description | 当编写新模块、设计接口、重构代码或代码审查时触发。提供经典模块化六原则检查清单（大小适中/调用深度/扇入扇出/边界清晰/作用域内聚/可预测性），适用于 PR/Review/新模块设计场景。 |
经典软件工程设计原则在 AI 协作场景下的现代化清单。 用作新模块设计、重构、代码审查时的对照表，不替代具体执行 skill。
/review、/new-feature、/optimize、/design 命令在设计阶段| # | 原则 | 一句话 | 衡量指标 | 详细案例 |
|---|---|---|---|---|
| 1 | 模块大小适中 | 单文件控制在职责边界内 | 行数/职责数 | 引用 size-check |
| 2 | 减少调用深度 | 调用链尽量 ≤ 3 层 | 栈深度 | modularity.md#调用深度 |
| 3 | 多扇入，少扇出 | 被复用 > 主动依赖 | 依赖数/被依赖数 | modularity.md#扇入扇出 |
| 4 | 接口边界清晰 | 入参/出参/异常统一 | 统一响应包装 | modularity.md#边界清晰 |
| 5 | 作用域内聚 | 改 A 不波及 B | 跨模块副作用 | 引用 refactor-safety |
| 6 | 功能可预测 | 同输入→同输出 | 幂等/无副作用/可测 | predictability.md |
主要执行交给
size-checkskill；本 skill 仅作总纲提示。
核心：单文件超限是设计信号，不是格式问题。提示职责过载，应拆分。
默认阈值：Java ≤ 300 / Go ≤ 400 / Vue ≤ 200 / TS ≤ 300 / Python ≤ 300（项目可覆盖）。
❌ 反例：Controller → ServiceA → ServiceB → ServiceC → DAO → Mapper（6 层）。定位 bug 需要逐层进栈，新人难以理解。
✅ 正例：Controller → Service → Repository（3 层），其余通过事件/队列/纯函数解耦。
衡量：调用栈深度 > 5 即视为坏味道。详见 modularity.md#调用深度。
❌ 反例：OrderService.createOrder() 依赖 UserService、CouponService、PaymentService、StockService、NotifyService、AuditService、CacheService、MetricsService（扇出 8）。改一处可能炸 8 处。
✅ 正例：StringUtils.toCamelCase() 被项目 30 处复用（扇入 30）。复用价值高，无下游污染。
衡量：单方法直接依赖数 ≤ 5；被依赖数越多越好。详见 modularity.md#扇入扇出。
现代化改写"单入口单出口"原则。早期 return / guard clause 优于深嵌套。
❌ 反例：成功返回 {data}、失败抛异常、还有一种返 null，调用方需要 3 种处理路径。
✅ 正例：统一 {code, data, message} 包装，异常在边界层（middleware / interceptor）集中处理。一个出入口契约对所有调用方一致。
主要执行交给
refactor-safety与multi-tenant-safetyskill。
核心：
❌ 反例：
✅ 正例：
新增或修改模块前，逐条过一遍：
size-check| 原则 | 主要执行 skill | 本 skill 角色 |
|---|---|---|
| 1 大小适中 | size-check | 触发提示 |
| 2 调用深度 | 无独立 skill | 本 skill 主导 |
| 3 扇入扇出 | 无独立 skill | 本 skill 主导 |
| 4 边界清晰 | api-design-safety | 决策对照 |
| 5 作用域内聚 | refactor-safety / multi-tenant-safety | 触发提示 |
| 6 可预测 | time-zone-safety / redis-safety / query-performance-safety | 本 skill 主导，专项 skill 处理具体陷阱 |
本 skill 是总纲与决策对照表，具体执行细节在上述各 skill 内。
> 📋 本回复遵循：`code-quality-principles` - [原则编号]
一键安装 cc-use-exp 配置体系到 Codex CLI
结构化 Codex 配置与任务状态检查工作流，适用于显式 status、配置诊断、同步结果核对或任务盘点场景；聚焦 Codex 配置与项目内 .codex 任务状态。
当设计或修改 REST API 响应结构、处理 API 返回值，或生成 Excel/CSV/PDF/对账文件等下游产物时触发。防止 API 设计缺陷导致的字段错位、类型歧义，以及生成产物时关键字段缺失但静默成功的问题。
当 API/任务可能执行超过 10 秒（批量数据处理、远程 API 批量调用、全表扫描、跨租户聚合）时触发。防止同步接口被网关 30s 超时切断、用户重复点击触发并发、状态缓存内存泄漏等问题。提供异步任务状态机标准模板。
Bash 脚本与系统命令规范。禁止行尾注释，强制使用 tee/heredoc 写入，提升命令执行的可维护性。
当重构涉及字段映射（dataIndex、枚举映射、类型转换）时触发。防止字段名推测错误，确保字段映射的正确性。