---
title: Prioritize Clarity Over Cleverness
impact: HIGH
impactDescription: Reduces cognitive load and improves maintainability
tags: quality, simplicity, readability
---
## Паспорт документа

- Статус документа: living standard
- Актуально на: 28 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении инженерной практики, CI/CD, архитектурных правил или локального workflow
- Область применения: внутренние rule/reference-card документы для инженерной команды
- Связанные документы:
  - [Индекс Agents](../README.md)
  - [Команды разработки](../commands.md)
  - [Инженерные принципы](../../governance/engineering-principles.md)

## Prioritize Clarity Over Cleverness

**Impact: HIGH**

The goal is code that is easy to read and understand quickly, not elegant complexity. Simple systems reduce the cognitive load for every engineer.

**Questions to ask yourself:**
- Am I actually solving the problem at hand?
- Am I thinking too much about possible future use cases?
- Have I considered at least 1 other alternative? How does it compare?

**Incorrect (clever but hard to understand):**

```typescript
const result = data.reduce((a, b) => ({...a, [b.id]: (a[b.id] || []).concat(b)}), {});
```

**Correct (clear and readable):**

```typescript
const groupedById: Record<string, Item[]> = {};

for (const item of data) {
  if (!groupedById[item.id]) {
    groupedById[item.id] = [];
  }
  groupedById[item.id].push(item);
}
```

**Important note:**
Simple doesn't mean lacking in features. Just because our goal is to create simple systems, this doesn't mean they should feel anemic and lacking obvious functionality.