---
name: doc-standards
description: Документация — ловушки структуры, дублирования, устаревания. Активируется при documentation, docs, spec, BRD, PRD, ADR, tech spec, single source of truth, out of scope, metadata, cross-reference, rollback plan, документация
---

# Documentation — ловушки

## Структура

### Копипаста вместо ссылок
Плохо: одна и та же таблица скопирована в 3 документа
Правильно: один источник (single source of truth) + ссылки из остальных документов
Почему: при обновлении меняется только одна копия, остальные устаревают. Данные расходятся

### Монолит на 2000 строк
Плохо: один документ покрывает всё: архитектуру, API, deployment, тестирование
Правильно: split по аудитории или компоненту, max 500 строк на документ
Почему: невозможно найти нужное, никто не читает полностью, merge conflicts при совместной работе

### Глубокая вложенность заголовков
Плохо: H1 -> H2 -> H3 -> H4 -> H5 — 5 уровней вложенности
Правильно: max 3-4 уровня. Если нужен H5 — split на sub-документ
Почему: глубокая вложенность усложняет навигацию и означает что документ пора делить

## Metadata

### "Живой документ" без даты
Плохо: документ без `updated` поля — непонятно, актуально ли содержание
Правильно: metadata обязательна: `type`, `status`, `owner`, `updated`
Почему: через 6 месяцев никто не знает, актуален ли документ или устарел

### Нет Owner
Плохо: документ существует, но никто за него не отвечает
Правильно: owner назначен в metadata, он отвечает за актуальность
Почему: документ без owner устаревает, никто не обновляет при изменении системы

### Status: Draft навсегда
Плохо: документ в статусе Draft, по нему работает команда
Правильно: lifecycle: `draft` -> `review` -> `approved` -> `archived`
Почему: Draft без перехода в Approved = неясно, можно ли опираться на документ

## BRD/PRD

### Нет Out of Scope
Плохо: документ описывает что входит, но не что НЕ входит
Правильно: явный раздел Out of Scope с конкретными пунктами
Почему: scope creep через месяц, ожидания стейкхолдеров не совпадают с реальностью

### NFR пропущены
Плохо: только функциональные требования, без производительности и безопасности
Правильно: Non-Functional Requirements: latency, throughput, compliance, availability
Почему: система работает "правильно", но медленно или небезопасно. NFR определяют качество

### Нет Anti-Metrics
Плохо: метрики успеха без ограничений — "увеличить конверсию"
Правильно: anti-metrics: "latency не должен вырасти выше 200ms", "error rate не выше 0.1%"
Почему: оптимизация одной метрики за счёт другой, без anti-metrics нет ограничений

## ADR

### ADR без Alternatives Considered
Плохо: "Выбрали PostgreSQL" — без объяснения почему не MongoDB или MySQL
Правильно: минимум 2-3 альтернативы с trade-offs для каждой
Почему: без альтернатив решение выглядит необоснованным, ревьюер не видит контекст

### Только плюсы, нет Negative Consequences
Плохо: ADR описывает только преимущества выбранного решения
Правильно: раздел Negative Consequences: что теряем, какие риски принимаем
Почему: неполная картина приводит к неожиданным проблемам после внедрения

### Нет Supersedes ссылки
Плохо: новый ADR заменяет старый, но ссылки нет
Правильно: `Supersedes: ADR-003` + в старом ADR `Status: Superseded by ADR-007`
Почему: без связи непонятно какой ADR актуален, команда следует устаревшему решению

## Tech Spec

### Нет Rollout Plan
Плохо: tech spec описывает что строить, но не как деплоить
Правильно: Rollout Plan + Rollback Strategy + Migration Plan
Почему: деплой без плана отката = риск production down без возможности быстро вернуть

## Чек-лист

- Поискал существующий документ перед созданием нового
- Metadata заполнена (type, status, owner, updated)
- Out of Scope явно указан
- Нет дублирования, ссылки вместо копий
- ADR содержит Alternatives + Negative Consequences
- Документ <500 строк (иначе split)
- Cross-references актуальны