A modernized checklist of classic software engineering design principles in AI collaboration scenarios. Used as a reference table for new module design, refactoring, and code review; it does not replace specific execution skills.
Trigger Scenarios
- Writing new modules, new services, new interfaces
- The user says "design", "split modules", "review", "refactor"
/review、/new-feature、/optimize、/designcommand during the design phase- When assessing technical debt, use the principles to locate code smells
Six Principles Quick Reference
| # | Principle | One-liner | Metric | Detailed Case |
|---|---|---|---|---|
| 1 | Moderate module size | Keep a single file within its responsibility boundary | Lines/Responsibilities | Reference cc-size-check |
| 2 | Reduce call depth | Keep call chains ≤ 3 levels when possible | Stack depth | modularity.md#call-depth |
| 3 | High fan-in, low fan-out | Be reused > actively depend | Dependencies/Dependents | modularity.md#fan-in-fan-out |
| 4 | Clear interface boundaries | Unified inputs/outputs/exceptions | Unified response wrapper | modularity.md#clear-boundaries |
| 5 | Scoped cohesion | Changing A does not affect B | Cross-module side effects | Reference cc-refactor-safety |
| 6 | Predictable functionality | Same input → same output | Idempotent/no side effects/testable | predictability.md |
1. Moderate module size
The main execution is delegated to
cc-size-checkskill; this skill serves only as a general outline reminder.
Core: A single file exceeding the limit is adesign signal, not a formatting issue. It indicates responsibility overload and should be split.
Default thresholds: Java ≤ 300 / Go ≤ 400 / Vue ≤ 200 / TS ≤ 300 / Python ≤ 300 (project may override).
2. Reduce call depth
❌ Counterexample：Controller → ServiceA → ServiceB → ServiceC → DAO → Mapper(6 levels). Locating a bug requires stepping into the stack layer by layer, making it hard for newcomers to understand.
✅ Positive example：Controller → Service → Repository(3 levels), with the rest decoupled via events/queues/pure functions.
Metric: A call stack depth > 5 is considered a code smell. See modularity.md#call-depth。
3. High fan-in, low fan-out
❌ Counterexample：OrderService.createOrder() depends on UserService, CouponService, PaymentService, StockService, NotifyService, AuditService, CacheService, MetricsService (fan-out 8). Changing one place may blow up 8 places.
✅ Positive example：StringUtils.toCamelCase() is reused in 30 places in the project (fan-in 30). High reuse value, no downstream pollution.
Metric: Direct dependencies of a single method ≤ 5; the more dependents, the better. See modularity.md#fan-in-fan-out。
4. Clear interface boundaries + unified error return
A modernized rewrite of the "single entry, single exit" principle. Early return / guard clause is better than deep nesting.
❌ Counterexample: returns successfully with {data}, throws an exception on failure, and also returns null, so the caller needs 3 handling paths.
✅ Good example: unified {code, data, message} wrapper, with exceptions handled centrally at the boundary layer (middleware / interceptor). One entry/exit contract is consistent for all callers.
See modularity.md#clear-boundaries。
5. Scope cohesion
The main execution is delegated to
cc-refactor-safetyandcc-multi-tenant-safetyskill。
Core：
- Changes within a module should not cross boundaries and affect other modules
- Private implementation is not exposed as a public API
- Cross-module communication goes throughexplicit APIs, events, or messages, not through shared mutable state
6. Predictable functionality
❌ Counterexample：
- The same HTTP retry deducts the payment twice (no idempotency key)
- A scheduled task fails overnight (depends on the system time zone)
- A unit test passes sometimes and fails sometimes (depends on external state)
✅ Good example：
- Deduplicate with an idempotency key (mandatory for write operations)
- Use UTC uniformly for time, and convert at the boundary as needed
- Prefer pure functions, and concentrate side effects at the boundary (IO/DB/network)
See predictability.md。
Checklist (for PR / Review comparison)
Before adding or modifying a module, go through each item one by one:
- Size: Does a single file stay within the line limit? See
cc-size-check - Depth: Is the call chain ≤ 3 levels? Is there no long chain such as A→B→C→D→E?
- Fan-out: Are there ≤ 5 direct dependencies? Have too many services been introduced?
- Boundary: Is there a unified convention for interface input/output/exceptions?
- Scope: Do the modifications cross boundaries and affect other modules?
- Idempotency: Are retries/repeated calls safe?
- Implicit dependencies: Does it depend on implicit environment factors such as time zone, current time, or random numbers?
Boundary with other skills
| Principle | Main execution skill | Role of this skill |
|---|---|---|
| 1 Moderate size | cc-size-check |
Trigger hint |
| 2 Call depth | No independent skill | This skill leads |
| 3 Fan-in and fan-out | No independent skill | This skill leads |
| 4 Clear boundaries | cc-api-design-safety |
Decision comparison |
| 5 Scope cohesion | cc-refactor-safety / cc-multi-tenant-safety |
Trigger hint |
| 6 Predictable | cc-time-zone-safety / cc-redis-safety / cc-query-performance-safety |
This skill leads, while specialized skills handle specific pitfalls |
This skill is thegeneral outline and decision comparison table, and the specific execution details are in each of the above skills.
Rule traceability
> 📋 本回复遵循：`cc-code-quality-principles` - [原则编号]