system-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Software Architecture Development Skill

软件架构开发Skill

This skill provides guidence for quality focused software development and architecture. It is based on Clean Architecture and Domain Driven Design principles.

本Skill为注重质量的软件开发与架构设计提供指导，基于Clean Architecture和Domain Driven Design原则。

Code Style Rules

代码风格规范

General Principles

通用原则

Early return pattern: Always use early returns when possible, over nested conditions for better readability
Avoid code duplication through creation of reusable functions and modules
Decompose long (more than 80 lines of code) components and functions into multiple smaller components and functions. If they cannot be used anywhere else, keep it in the same file. But if file longer than 200 lines of code, it should be split into multiple files.
Use arrow functions instead of function declarations when possible

提前返回模式：尽可能使用提前返回，替代嵌套条件，以提升可读性
通过创建可复用函数和模块避免代码重复
将较长的组件和函数（超过80行代码）拆分为多个更小的组件和函数。如果它们无法在其他地方复用，可保留在同一文件中。但如果文件超过200行代码，则应拆分为多个文件。
尽可能使用箭头函数替代函数声明

Best Practices

最佳实践

Library-First Approach

库优先原则

ALWAYS search for existing solutions before writing custom code
- Check npm for existing libraries that solve the problem
- Evaluate existing services/SaaS solutions
- Consider third-party APIs for common functionality
Use libraries instead of writing your own utils or helpers. For example, use
```
cockatiel
```
instead of writing your own retry logic.
When custom code IS justified:
- Specific business logic unique to the domain
- Performance-critical paths with special requirements
- When external dependencies would be overkill
- Security-sensitive code requiring full control
- When existing solutions don't meet requirements after thorough evaluation

在编写自定义代码前，务必先寻找现有解决方案
- 查看npm上是否有能解决该问题的现有库
- 评估现有服务/SaaS解决方案
- 考虑使用第三方API实现通用功能
使用库而非自行编写工具函数或辅助函数。例如，使用
```
cockatiel
```
而非自行编写重试逻辑。
以下情况可编写自定义代码：
- 领域特有的特定业务逻辑
- 有特殊要求的性能关键路径
- 使用外部依赖过于冗余时
- 需要完全控制的安全敏感代码
- 经过全面评估后现有解决方案无法满足需求时

Architecture and Design

架构与设计

Clean Architecture & DDD Principles:
- Follow domain-driven design and ubiquitous language
- Separate domain entities from infrastructure concerns
- Keep business logic independent of frameworks
- Define use cases clearly and keep them isolated
Naming Conventions:
- AVOID generic names:
```
utils
```
  ,
```
helpers
```
  ,
```
common
```
  ,
```
shared
```
- USE domain-specific names:
```
OrderCalculator
```
  ,
```
UserAuthenticator
```
  ,
```
InvoiceGenerator
```
- Follow bounded context naming patterns
- Each module should have a single, clear purpose
Separation of Concerns:
- Do NOT mix business logic with UI components
- Keep database queries out of controllers
- Maintain clear boundaries between contexts
- Ensure proper separation of responsibilities

Clean Architecture & DDD原则：
- 遵循领域驱动设计和通用语言
- 将领域实体与基础设施关注点分离
- 保持业务逻辑独立于框架
- 清晰定义用例并使其保持独立
命名规范：
- 避免使用通用名称：
```
utils
```
  、
```
helpers
```
  、
```
common
```
  、
```
shared
```
- 使用领域特定名称：
```
OrderCalculator
```
  、
```
UserAuthenticator
```
  、
```
InvoiceGenerator
```
- 遵循限界上下文命名模式
- 每个模块应具有单一、明确的用途
关注点分离：
- 不要将业务逻辑与UI组件混合
- 不要在控制器中直接编写数据库查询
- 保持上下文之间的清晰边界
- 确保职责的合理分离

Anti-Patterns to Avoid

需避免的反模式

NIH (Not Invented Here) Syndrome:
- Don't build custom auth when Auth0/Supabase exists
- Don't write custom state management instead of using Redux/Zustand
- Don't create custom form validation instead of using established libraries
Poor Architectural Choices:
- Mixing business logic with UI components
- Database queries directly in controllers
- Lack of clear separation of concerns
Generic Naming Anti-Patterns:
- ```
utils.js
```
  with 50 unrelated functions
- ```
helpers/misc.js
```
  as a dumping ground
- ```
common/shared.js
```
  with unclear purpose
Remember: Every line of custom code is a liability that needs maintenance, testing, and documentation

NIH（非我所创）综合征：
- 已有Auth0/Supabase时，不要自行构建认证系统
- 不要自行编写状态管理逻辑，应使用Redux/Zustand
- 不要自行创建表单验证逻辑，应使用成熟的库
不良架构选择：
- 业务逻辑与UI组件混合
- 控制器中直接编写数据库查询
- 缺乏清晰的关注点分离
通用命名反模式：
- 包含50个不相关函数的
```
utils.js
```
- 作为“垃圾场”的
```
helpers/misc.js
```
- 用途不明确的
```
common/shared.js
```
谨记：每一行自定义代码都是需要维护、测试和文档化的负债

Code Quality

代码质量

Proper error handling with typed catch blocks
Break down complex logic into smaller, reusable functions
Avoid deep nesting (max 3 levels)
Keep functions focused and under 50 lines when possible
Keep files focused and under 200 lines of code when possible

undefined

使用类型化catch块进行恰当的错误处理
将复杂逻辑拆分为更小的可复用函数
避免深层嵌套（最多3层）
尽可能保持函数聚焦且代码行数不超过50行
尽可能保持文件聚焦且代码行数不超过200行

undefined