api-design-safety
当设计或修改 REST API 响应结构、处理 API 返回值时触发。防止 API 设计缺陷导致的字段错位、类型歧义等问题。
@docckerInstall SkillDevelopment
Skill
/code-quality-principles
当编写新模块、设计接口、重构代码或代码审查时触发。提供经典模块化六原则检查清单（大小适中/调用深度/扇入扇出/边界清晰/作用域内聚/可预测性），适用于 PR/Review/新模块设计场景。
Claude Code
$ npx -y skills add doccker/cc-use-exp --skill code-quality-principles --agent claude-code
Codex
$ npx skills add doccker/cc-use-exp --skill code-quality-principles -a codex -y
Cursor
$ npx skills add doccker/cc-use-exp --skill code-quality-principles -a cursor -y
Gemini CLI
$ npx skills add doccker/cc-use-exp --skill code-quality-principles -a gemini-cli -y
GitHub Copilot
$ npx skills add doccker/cc-use-exp --skill code-quality-principles -a github-copilot -y
OpenCode
$ npx skills add doccker/cc-use-exp --skill code-quality-principles -a opencode -y
Windsurf
$ npx skills add doccker/cc-use-exp --skill code-quality-principles -a windsurf -y
SKILL.md
code-quality-principles.SKILL.mdname: code-quality-principles
description: 当编写新模块、设计接口、重构代码或代码审查时触发。提供经典模块化六原则检查清单（大小适中/调用深度/扇入扇出/边界清晰/作用域内聚/可预测性），适用于 PR/Review/新模块设计场景。
模块化设计六原则
> 经典软件工程设计原则在 AI 协作场景下的现代化清单。 > 用作新模块设计、重构、代码审查时的对照表，不替代具体执行 skill。
触发场景
- 编写新模块、新服务、新接口
- 用户说"设计"、"拆分模块"、"评审"、"重构"
- `/review`、`/new-feature`、`/optimize`、`/design` 命令在设计阶段
- 评估技术债时对照原则定位坏味道
---
六原则速查表
| # | 原则 | 一句话 | 衡量指标 | 详细案例 | |---|------|--------|---------|---------| | 1 | 模块大小适中 | 单文件控制在职责边界内 | 行数/职责数 | 引用 [size-check](../size-check/) | | 2 | 减少调用深度 | 调用链尽量 ≤ 3 层 | 栈深度 | [modularity.md#调用深度](references/modularity.md) | | 3 | 多扇入，少扇出 | 被复用 > 主动依赖 | 依赖数/被依赖数 | [modularity.md#扇入扇出](references/modularity.md) | | 4 | 接口边界清晰 | 入参/出参/异常统一 | 统一响应包装 | [modularity.md#边界清晰](references/modularity.md) | | 5 | 作用域内聚 | 改 A 不波及 B | 跨模块副作用 | 引用 [refactor-safety](../refactor-safety/) | | 6 | 功能可预测 | 同输入→同输出 | 幂等/无副作用/可测 | [predictability.md](references/predictability.md) |
---
1. 模块大小适中
> 主要执行交给 `size-check` skill；本 skill 仅作总纲提示。
**核心**：单文件超限是**设计信号**，不是格式问题。提示职责过载，应拆分。
**默认阈值**：Java ≤ 300 / Go ≤ 400 / Vue ≤ 200 / TS ≤ 300 / Python ≤ 300（项目可覆盖）。
---
2. 减少调用深度
❌ **反例**：`Controller → ServiceA → ServiceB → ServiceC → DAO → Mapper`（6 层）。定位 bug 需要逐层进栈，新人难以理解。
✅ **正例**：`Controller → Service → Repository`（3 层），其余通过事件/队列/纯函数解耦。
**衡量**：调用栈深度 > 5 即视为坏味道。详见 [modularity.md#调用深度](references/modularity.md)。
---
3. 多扇入，少扇出
❌ **反例**：`OrderService.createOrder()` 依赖 UserService、CouponService、PaymentService、StockService、NotifyService、AuditService、CacheService、MetricsService（扇出 8）。改一处可能炸 8 处。
✅ **正例**：`StringUtils.toCamelCase()` 被项目 30 处复用（扇入 30）。复用价值高，无下游污染。
**衡量**：单方法直接依赖数 ≤ 5；被依赖数越多越好。详见 [modularity.md#扇入扇出](references/modularity.md)。
---
4. 接口边界清晰 + 统一错误返回
> 现代化改写"单入口单出口"原则。早期 return / guard clause 优于深嵌套。
❌ **反例**：成功返回 `{data}`、失败抛异常、还有一种返 `null`，调用方需要 3 种处理路径。
✅ **正例**：统一 `{code, data, message}` 包装，异常在边界层（middleware / interceptor）集中处理。一个出入口契约对所有调用方一致。
详见 [modularity.md#边界清晰](references/modularity.md)。
---
5. 作用域内聚
> 主要执行交给 `refactor-safety` 与 `multi-tenant-safety` skill。
**核心**：
- 模块内的修改不应越界影响其他模块
- 私有实现不暴露成公共 API
- 跨模块通信走**明确的 API、事件或消息**，不通过共享可变状态
---
6. 功能可预测
❌ **反例**：
- 同一笔 HTTP 重试扣两次款（无幂等键）
- 定时任务跨夜失败（依赖系统时区）
- 单测时灵时不灵（依赖外部状态）
✅ **正例**：
- 幂等键去重（写操作必有）
- 时间统一 UTC，按需在边界转换
- 纯函数优先，副作用集中在边界（IO/DB/网络）
详见 [predictability.md](references/predictability.md)。
---
检查清单（PR / Review 对照）
新增或修改模块前，逐条过一遍：
- [ ] **大小**：单文件未超行数限制？参考 `size-check`
- [ ] **深度**：调用链 ≤ 3 层？没有 A→B→C→D→E 的长链？
- [ ] **扇出**：直接依赖数 ≤ 5？是否引入了过多 service？
- [ ] **边界**：接口入参/出参/异常有统一约定？
- [ ] **作用域**：修改是否越界影响了其他模块？
- [ ] **幂等**：重试/重复调用是否安全？
- [ ] **隐式依赖**：是否依赖时区、当前时间、随机数等隐式环境？
---
与其他 skill 的边界
| 原则 | 主要执行 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` - [原则编号]
Read more
name: code-quality-principles description: 当编写新模块、设计接口、重构代码或代码审查时触发。提供经典模块化六原则检查清单（大小适中/调用深度/扇入扇出/边界清晰/作用域内聚/可预测性），适用于 PR/Review/新模块设计场景。
模块化设计六原则
> 经典软件工程设计原则在 AI 协作场景下的现代化清单。 > 用作新模块设计、重构、代码审查时的对照表，不替代具体执行 skill。
触发场景
- 编写新模块、新服务、新接口
- 用户说"设计"、"拆分模块"、"评审"、"重构"
- `/review`、`/new-feature`、`/optimize`、`/design` 命令在设计阶段
- 评估技术债时对照原则定位坏味道
---
六原则速查表
| # | 原则 | 一句话 | 衡量指标 | 详细案例 | |---|------|--------|---------|---------| | 1 | 模块大小适中 | 单文件控制在职责边界内 | 行数/职责数 | 引用 [size-check](../size-check/) | | 2 | 减少调用深度 | 调用链尽量 ≤ 3 层 | 栈深度 | [modularity.md#调用深度](references/modularity.md) | | 3 | 多扇入，少扇出 | 被复用 > 主动依赖 | 依赖数/被依赖数 | [modularity.md#扇入扇出](references/modularity.md) | | 4 | 接口边界清晰 | 入参/出参/异常统一 | 统一响应包装 | [modularity.md#边界清晰](references/modularity.md) | | 5 | 作用域内聚 | 改 A 不波及 B | 跨模块副作用 | 引用 [refactor-safety](../refactor-safety/) | | 6 | 功能可预测 | 同输入→同输出 | 幂等/无副作用/可测 | [predictability.md](references/predictability.md) |
---
1. 模块大小适中
> 主要执行交给 `size-check` skill；本 skill 仅作总纲提示。
**核心**：单文件超限是**设计信号**，不是格式问题。提示职责过载，应拆分。
**默认阈值**：Java ≤ 300 / Go ≤ 400 / Vue ≤ 200 / TS ≤ 300 / Python ≤ 300（项目可覆盖）。
---
2. 减少调用深度
❌ **反例**：`Controller → ServiceA → ServiceB → ServiceC → DAO → Mapper`（6 层）。定位 bug 需要逐层进栈，新人难以理解。
✅ **正例**：`Controller → Service → Repository`（3 层），其余通过事件/队列/纯函数解耦。
**衡量**：调用栈深度 > 5 即视为坏味道。详见 [modularity.md#调用深度](references/modularity.md)。
---
3. 多扇入，少扇出
❌ **反例**：`OrderService.createOrder()` 依赖 UserService、CouponService、PaymentService、StockService、NotifyService、AuditService、CacheService、MetricsService（扇出 8）。改一处可能炸 8 处。
✅ **正例**：`StringUtils.toCamelCase()` 被项目 30 处复用（扇入 30）。复用价值高，无下游污染。
**衡量**：单方法直接依赖数 ≤ 5；被依赖数越多越好。详见 [modularity.md#扇入扇出](references/modularity.md)。
---
4. 接口边界清晰 + 统一错误返回
> 现代化改写"单入口单出口"原则。早期 return / guard clause 优于深嵌套。
❌ **反例**：成功返回 `{data}`、失败抛异常、还有一种返 `null`，调用方需要 3 种处理路径。
✅ **正例**：统一 `{code, data, message}` 包装，异常在边界层（middleware / interceptor）集中处理。一个出入口契约对所有调用方一致。
详见 [modularity.md#边界清晰](references/modularity.md)。
---
5. 作用域内聚
> 主要执行交给 `refactor-safety` 与 `multi-tenant-safety` skill。
**核心**：
- 模块内的修改不应越界影响其他模块
- 私有实现不暴露成公共 API
- 跨模块通信走**明确的 API、事件或消息**，不通过共享可变状态
---
6. 功能可预测
❌ **反例**：
- 同一笔 HTTP 重试扣两次款（无幂等键）
- 定时任务跨夜失败（依赖系统时区）
- 单测时灵时不灵（依赖外部状态）
✅ **正例**：
- 幂等键去重（写操作必有）
- 时间统一 UTC，按需在边界转换
- 纯函数优先，副作用集中在边界（IO/DB/网络）
详见 [predictability.md](references/predictability.md)。
---
检查清单（PR / Review 对照）
新增或修改模块前，逐条过一遍：
- [ ] **大小**：单文件未超行数限制？参考 `size-check`
- [ ] **深度**：调用链 ≤ 3 层？没有 A→B→C→D→E 的长链？
- [ ] **扇出**：直接依赖数 ≤ 5？是否引入了过多 service？
- [ ] **边界**：接口入参/出参/异常有统一约定？
- [ ] **作用域**：修改是否越界影响了其他模块？
- [ ] **幂等**：重试/重复调用是否安全？
- [ ] **隐式依赖**：是否依赖时区、当前时间、随机数等隐式环境？
---
与其他 skill 的边界
| 原则 | 主要执行 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` - [原则编号]
Ships withcc-use-exp
保留你熟悉的 CLI/IDE，让 Claude Code、Gemini CLI、Codex、Cursor、GitHub Copilot 开箱即用 按费力度从低到高，用最少操作获得最大帮助 不是提示词集合，而是一套可维护的 AI 协作配置系统。
1.1k24 skills
Stars on GitHub
Momentum
- stars in total
- 1.1k
Other skills on cc-use-exp.
@docckerInstall Skillapi-proxy-safety
网关/代理/WAF/CDN 中间件的安全关键词匹配实现规范，防止纯子串匹配误判正常响应内容中的技术术语（如 Cloudflare、502、error）
@docckerInstall Skillasync-task-pattern
当 API/任务可能执行超过 10 秒（批量数据处理、远程 API 批量调用、全表扫描、跨租户聚合）时触发。防止同步接口被网关 30s 超时切断、用户重复点击触发并发、状态缓存内存泄漏等问题。提供异步任务状态机标准模板。
@docckerInstall Skillbash-style
当用户操作 .sh、Dockerfile、Makefile、.yml、.yaml 文件，或在 Markdown 中编写 bash 代码块时触发。提供 Bash 编写规范。
@docckerInstall Skillexternal-system-debugg…
涉及浏览器、编辑器、CDN/WAF、IM 平台、操作系统剪贴板、第三方 SaaS 等"外部黑盒系统"的代码编写或 bug 调试时触发。强制先抓真实环境数据再推理,避免连续 2 轮"凭代码推理"的修复…
@docckerInstall SkillMore skills from other plugins.
Auto-invoked
brainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or…
@obraInstall Skillask-matt
Ask which skill or flow fits your situation. A router over the skills in this repo.
@mattpocockInstall SkillAuto-invoked
Questions about code-quality-principles.
- Which coding agents can use code-quality-principles?
- code-quality-principles installs in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and Windsurf with the skills CLI, using each agent's flag shown on this page. Flowy's auto-invocation, which fires a skill when your prompt matches, runs in Claude Code only.