# Code Quality Principles

当编写新模块、设计接口、重构代码或代码审查时触发。提供经典模块化六原则检查清单（大小适中/调用深度/扇入扇出/边界清晰/作用域内聚/可预测性），适用于...

- Repository: https://github.com/doccker/cc-use-exp (1063 stars)
- Category: Git and review
- License: see repository
- Last updated: 2026-08-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add doccker/cc-use-exp --skill code-quality-principles -g -a claude-code -y`
Codex: `npx skills add doccker/cc-use-exp --skill code-quality-principles -g -a codex -y`
Cursor: `npx skills add doccker/cc-use-exp --skill code-quality-principles -g -a cursor -y`
Gemini CLI: `npx skills add doccker/cc-use-exp --skill code-quality-principles -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add doccker/cc-use-exp`

## Description

当编写新模块、设计接口、重构代码或代码审查时触发。提供经典模块化六原则检查清单（大小适中/调用深度/扇入扇出/边界清晰/作用域内聚/可预测性），适用于 PR/Review/新模块设计场景。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 模块化设计六原则

> 经典软件工程设计原则在 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。

The rest: https://github.com/doccker/cc-use-exp/blob/HEAD/.antigravity/skills/code-quality-principles/SKILL.md