Contextual Commits

Conventional Commits стандартизировали ЧТО изменилось. Contextual Commits добавляют ПОЧЕМУ.

Соглашение для встраивания трассировки решений в тело git-коммита. Каждый коммит несёт не только изменение кода, но и намерение с обоснованием — в виде типизированных строк действий, которые может разобрать любой инструмент и запросить любой агент.

Никаких новых инструментов. Никакой инфраструктуры. Просто лучшие коммиты.

---

Стандартный AI-коммит:

feat(auth): implement Google OAuth provider Added GoogleAuthProvider class with passport.js integration. Created callback route handler at /api/auth/callback/google. Added refresh token logic with offline access scope. Updated auth middleware to support multiple providers.

Это пересказывает то, что и так видно в диффе. Нулевая информационная ценность.

Contextual-коммит:

feat(auth): implement Google OAuth provider intent(auth): social login starting with Google, then GitHub and Apple decision(oauth-library): passport.js over auth0-sdk for multi-provider flexibility rejected(oauth-library): auth0-sdk — locks into their session model, incompatible with redis store constraint(callback-routes): must follow /api/auth/callback/:provider pattern per existing convention constraint(session-store): redis 24h TTL means tokens must refresh within that window learned(passport-google): requires explicit offline_access scope for refresh tokens

Строка темы говорит что. Тело говорит почему.

---

Мотивация

AI-инструменты для написания кода повсюду. Доверие к их результатам — нет. Разрыв — это контекст.

Каждая AI-сессия разработки производит три вида результатов:

1. Изменения кода — коммитятся в git. Сохраняются.
2. Решения — какой подход выбран, что отклонено, какие ограничения найдены. Теряются.
3. Понимание — более глубокое осмысление того, как система работает и почему. Теряется.

Две трети ценности каждой сессии испаряются, когда закрывается окно разговора. История коммитов — единственный источник контекста, к которому любой AI-инструмент имеет доступ из коробки, — однако стандартное тело AI-коммита пересказывает то, что и так видно в диффе. Чего агенты не могут получить из диффа — это почему был выбран тот или иной подход, какие ограничения его сформировали и что было опробовано и отклонено.

Git отслеживает ветки, диффы и историю. Единственное, чего он не отслеживает, — это рассуждения. Тело коммита всегда было доступно для этого.

Контекст, который исчезает

Агент предлагает подход, который вы уже пробовали и отклонили в прошлой сессии, — но обоснование, которое его исключало, погибло вместе с окном разговора. Он пишет чистую реализацию, нарушающую ограничение, о котором у него нет никакой возможности знать, и обнаруживает это через ошибку. Три месяца спустя другая сессия видит паттерн в коде, который выглядит произвольным, — он таковым не был, но причина существовала в разговоре, которого больше нет.

Одна и та же проблема в трёх формах. AI-сессии разработки производят решения и понимание наряду с кодом, но только код выживает в git.

Что агенты могут и не могут восстановить

Несколько категорий контекста влияют на качество AI-разработки. Большинство можно восстановить из кодовой базы: архитектуру, паттерны кода, стратегию тестирования, соглашения об именовании. Агент, читающий ваш код, может это выяснить.

Две категории не поддаются обратному восстановлению: что вы намеревались сделать и что вы уже пробовали. Намерение и исторический контекст — принятые решения, отклонённые альтернативы, обнаруженные ограничения, усвоенные уроки — существуют только в памяти людей и исчезающих разговорах.

Contextual Commits фиксируют именно эти два. Не потому что они самые интересные, а потому что они те, которые иначе были бы безвозвратно утеряны.

Накопление

Первый contextual-коммит спасает одно будущее повторное исследование. Сотый означает, что агент, начинающий новую сессию, наследует каждое решение, отклонение, ограничение и урок из каждой предыдущей сессии — от каждого участника.

Это не документация, которую нужно поддерживать. Это append-only история, которая накапливается как побочный эффект коммита кода. Никаких файлов для актуализации. Никаких wiki-страниц для обновления. Никаких конфликтов слияния. Только git.

---

Соглашение

Формат

Contextual-коммит использует тело коммита для передачи структурированного контекста. Строка темы — стандартный Conventional Commit. Тело расширяет его типизированными строками действий:

<type>(<scope>): <description> <action-type>(<scope>): <content> <action-type>(<scope>): <content>

scope — человекочитаемая метка: область домена, модуль или концепция. Используйте любой словарь, естественный для вашего проекта: auth, payment-flow, api-contracts, session-store.

Типы действий

Тип	Фиксирует	Пример
intent(scope)	Что хотел пользователь и почему	intent(notifications): batch emails instead of per-event
decision(scope)	Что было выбрано, когда существовали альтернативы	decision(queue): SQS over RabbitMQ for managed scaling
rejected(scope)	Что рассматривалось и было отброшено, с причиной	rejected(queue): RabbitMQ — requires self-managed infra
constraint(scope)	Жёсткие ограничения, сформировавшие подход	constraint(api): max 5MB payload, 30s timeout
learned(scope)	Обнаруженные факты, предотвращающие будущие ошибки	learned(stripe): presentment ≠ settlement currency

Пять типов. Каждый фиксирует сигнал, который не покрывает ни один другой тип. Каждый немедленно полезен агенту, начинающему новую сессию.

• intent — чего пытается достичь пользователь. Без него агент восстанавливает цель из кода.
• decision — какой подход был выбран. Без него агент не знает, является ли паттерн намеренным или случайным.
• rejected — что было опробовано и отброшено. Без него агент повторно исследует тупики. Тип с наибольшей ценностью.
• constraint — жёсткие ограничения реализации. Без них агент пишет код, нарушающий ограничения, которые он не может знать.
• learned — факты, обнаруженные в ходе реализации. Без них следующий агент повторяет те же ошибки.