documentation-and-adrs

documentation-and-adrs — навык Addy Osmani для фиксации инженерных решений и контекста, который иначе исчезает после завершения задачи. Он отделяет описание результата от объяснения причины: код показывает, что сделано, а запись решения сохраняет ограничения, рассмотренные альтернативы, последствия и условия, при которых выбор может измениться. Это особенно полезно для архитектурных решений, изменения публичного API, выбора фреймворка, базы данных, схемы аутентификации, build-инструмента или платформы размещения — то есть там, где возврат к прежнему варианту будет дорогим. Перед созданием ADR навык требует сначала найти уже принятую в репозитории конвенцию. Нужно проверить существующие ADR, проектные инструкции, файл .adr-dir и конфигурацию инструментов. Если проект использует docs/adr, Documentation/Decisions, MADR, adr-tools или другой формат, необходимо продолжить его расположение, расширение, нумерацию и заголовки. Нельзя незаметно вводить вторую систему решений или начинать нумерацию с начала. Только когда никаких признаков конвенции нет, допустим запасной формат с последовательным номером, статусом, датой, контекстом, решением, альтернативами и последствиями. Хорошая запись отвечает на несколько практических вопросов. Какую проблему нужно решить и какие требования нельзя нарушить? Почему выбранный вариант подходит именно сейчас? Какие альтернативы были рассмотрены, какие у них преимущества и почему они отклонены? Что изменится для команды, эксплуатации и будущих миграций? Статус ADR должен быть жизненным циклом решения: Proposed, Accepted, Superseded или Deprecated. Старые записи не удаляются, потому что они объясняют исторический контекст; при изменении выбора создаётся новая запись, ссылающаяся на прежнюю и заменяющая её. Навык также задаёт границу для обычной документации и комментариев. Очевидный код не требует комментария, а комментарий должен объяснять намерение, риск или неочевидный gotcha, а не повторять следующую строку. Не следует оставлять TODO для работы, которую можно сделать сразу, или хранить закомментированный старый код. Публичные TypeScript API лучше описывать рядом с типами через JSDoc: назначение, параметры, результат, ошибки и короткий пример. Для REST или GraphQL применима OpenAPI-схема. README остаётся входной точкой проекта с кратким назначением, Quick Start и командами, а ADR хранит именно решения и trade-off. Поэтому навык подходит для долговечного контекста, но не нужен для очевидной правки или одноразового прототипа.