Ведение архитектурных решений (ADR)

★ 8.7 · documentation

documentation-and-adrs — это скилл для Claude Code, который фиксирует архитектурные решения и документирует контекст, необходимый будущим разработчикам и агентам для понимания кодовой базы. Скилл применяется при выборе технологий, смене публичных API, выпуске фич или всякий раз, когда нужно записать обоснование решения — trade-offs и рассмотренные альтернативы. В основе лежит шаблон Architecture Decision Records (ADR): документы хранятся в `docs/decisions/` с последовательной нумерацией, содержат разделы Context, Decision, Alternatives Considered и Consequences, а жизненный цикл описывается переходом PROPOSED → ACCEPTED → SUPERSEDED. Перед созданием ADR скилл проверяет репозиторий на существующие соглашения — формат, расположение, нумерацию — и следует им, а не навязывает собственный шаблон. Дополнительно скилл направляет к встроенным комментариям в коде: документировать нужно *почему*, а не *что*, и избегать очевидных пояснений.