Меня зовут Александр Мачулин, я основатель Gramax – open source системы для ведения документации в подходе Docs as Code с визуальным редактором.
Сегодня я расскажу вам идею, как вести всю документацию по проекту и весь цикл разработки в одном Git-репозитории и настроить backward-трасси��овку требований в Git.
Прошу обратить внимание, что это не описание проверенного годами подхода. Это идея, по которой нужна обратная связь.
Зачем вам это читать?
Если вы разработчик или аналитик, то вам наверняка знакома ситуация: нужно понять, как работает программа, а актуальной документации нет. Постановка на разработку потерялась, и единственный способ разобраться – смотреть в код.
Если вы продакт-менеджер, то release notes приходится собирать вручную по памяти, и половину фич вы просто забываете упомянуть. Не хватает связи между задачами и изменениями в коде.
Если вы техлид или архитектор, то наверняка часто задаётесь вопросом «Почему программа работает именно так?». История коммитов показывает, что изменилось, но не объясняет, почему. А без этого понимания сложно быстро и безопасно вносить изменения в систему.
У меня разный опыт работы в разработке: разработчик, тимлид, продакт-менеджер. И во всех ролях, в разных командах я сталкивался с этими вопросами, на которые очень сложно получить ответ. Вот хороший пример из недавней статьи по схожей теме:
В конфиге написано
timeout=30s. Раньше былоtimeout=5s. Кто-то увеличил значение в три раза. Почему? Git blame показывает, кто это сделал. А вот причина – утеряна.
Думаю, что эти проблемы знакомы всем. В любой компании информацию о системе приходится собирать по кусочкам: wiki, мессенджер, таск-трекер, Дима, который уволился два месяца назад. Поэтому это общий подход к работе над проектом, а не мелкое изменение процесса разработки.
Но давайте обо всём по порядку.
С чего всё началось
В 2022 году я посмотрел доклад на FlowConf «Документация в коде», где ребята рассказали про подход «постановка = часть документации». Я захотел сразу протестировать идею в работе, потому что она решала важные для меня проблемы: не тратить время на поиски «Почему так работает?», избавиться от множества .docx-файлов и отдельных статей в wiki с кусочным описанием функций и настроить процесс документирования систем с минимальными затратами.
Попробовал организовать работу в таком виде:
Создаём ветку в Git для новой функции и называем её по номеру задачи в таск-трекере.
Создаём Markdown-файл с требованиями.
Дополняем требования по ходу разработки и получаем готовую документацию в черновом виде.
Но подход на практике развалился. В разработке у нас есть PRD – описание от продакта; RFC – мини-проект с детальным анализом требований PRD и описанием реализации от разработчика; user story – шаг реализации RFC.
Вот с какими проблемами мы столкнулись:
Не можем посмотреть полное описание проекта и user story, так как Git не даёт готовых инструментов вытягивания и агрегации информации из разных веток.
Получаем долгоживущие ветки, которые замусоривают репозиторий, так как приоритетная задача может стать неприоритетной и всё время откладываться на потом.
В итоге идея умерла, и три года к ней не возвращались.
Новая надежда
В декабре 2025 года мы задумались о едином источнике правды по разработке и начали брейнштормить идею полного ведения ИТ-проекта в Git.
В итоге пришли к тому, что в Google, Uber и других крупных компаниях процесс разработки достаточно похож на наш. Есть PRD и RFC, они ведутся в Google Docs, но потом документы переносятся из Google Docs в единый репозиторий – Single Source of Truth. Подробнее о том, как это работает в Google, описано в статье.
Но если у нас уже есть удобный редактор для совместной работы – Gramax, почему бы нам не создавать все документы сразу в одном репозитории с кодом и не отслеживать их изменения в контексте задач?
Хранение артефактов разработки в Git становится популярным по мере распространения LLM-агентов, которым значительно проще посмотреть или описать задачу в отдельном файле, чем вызывать API веб-сервиса через MCP.
Переезжаем в Git
Для хранения всех артефактов разработки в одном Git-репозитории предлагается следующая структура папок.
Разработку ведём в ветке develop. Можно делать Feature branch, но, чтобы не собирать со всех веток актуальное состояние, договариваемся, что в develop хранится самое актуальное описание всех артефактов. Для документации и кода необходимо иметь Feature flag, чтобы при мерже develop → master не показать пользователю ещё сырую документацию или недоработанные функции.
User story тоже ведём в репозитории в виде Markdown-файлов, чтобы удобнее было ссылаться на RFC, документы и своевременно вносить правки в требования и критерии приёмки. В Gramax можно добавлять свойства к статьям (статус, релиз, исполнитель) и просматривать их в виде Kanban-доски. В небольшой команде это рабочий подход, но можно вести задачи в таск-трекере, особенно если вам необходимо списание времени (time tracking, timesheets) и другие продвинутые функции таск-трекеров.
Сохраняем мотив изменений
Git хранит текущее состояние (state), а изменения (diff) можно отследить по дереву коммитов. В разработке есть подход Commit linking, когда мы указываем номер задачи или RFC в коммите или названии ветки. Это помогает нам связать мотивацию с кодом. Но теперь, когда у нас все артефакты лежат в одном Git-репозитории, мы можем вывести Commit linking на новый уровень. Мы можем отслеживать, в рамках какой задачи поменялся любой из артефактов, размещая в commit trailers теги задач.
Пример работы подхода
Создали задачу в таск-трекере с кодом
us-137, по результатам которой необходимо подготовить RFC на новое предложение от продактов. В рамкахus-137написали RFC и уточнили PRD.Согласовали RFC, создали задачу с кодом
us-138, чтобы провести более детальный анализ и расписать проект по user story. В рамках детализации поняли, что не учли несколько моментов в RFC, скорректировали его.Начали реализовывать проект в первой user story на разработку с кодом
us-170. Создали отдельную ветку, написали код, уточнили критерии приёмки, написали черновую версию документации. Если произошло изменение критериев, то обновлённые критерии смержили вdevelop, чтобы иметь единый источник правды по текущей разработке.
Важно, чтобы разработчик писал первую версию документации, а не перекладывал это на аналитиков или технических писателей. Именно тогда мы сможем иметь версионируемое описание того, как система работает на самом деле, которое можно потом улучшать с привлечением аналитиков и технических писателей. Если посмотреть на вакансии в Google, то практически в каждой из них есть обязанность: «Contribute to existing documentation or educational content and adapt content based on product/program updates and user feedback.».
Визуализация подхода
│ │
│ WHY │ WHAT (folders changed)
COMMITS│ (motivation)│ prd/ rfc/ tasks/ src/ docs/
───────┼──────────────┼──────────────────────────────────────────────
c1 │ #us-137 │ ■ ■ · · ·
│ │
c2 │ #us-138 │ · ■ ■ · ·
│ │
c3 │ #us-153 │ · ■ · · ·
│ │
c4 │ #us-153 │ ■ ■ ■ · ·
│ │
c5 │ #us-170 │ · · ■ ■ ■
�� │
c6 │ #bug-17 │ · · · ■ ·
│ │
c7 │ #us-170 │ · ■ · ■ ·
│ │
c8 │ #us-170 │ · · · ■ ■
│ │
c9 │ #us-153 │ · · ■ ■ ■
│ │
c10 │ #bug-42 │ · · · ■ ■
│ │
TIME ▼
■ = changed · = unchangedНа схеме выше можем сразу видеть задачу, в рамках которой было изменение, и по клику переходить к описанию задачи и связанному RFC. Также можно фильтровать по тегам и папкам изменения файлов, например:
Найти список всех ревизий по
#us-170.Вычислить состояние до первой такой ревизии (baseline) и состояние после последней (end).
Показать diff между baseline и end по всему репозиторию или по конкретной папке.
Сделать это можно так:
# Найти все коммиты с тегом
git log --all --grep="#us-170" --format="%H"
# Собрать список файлов, изменённых в этих коммитах
git log --all --grep="#us-170" --name-only --format=""
# Показать diff только по этим файлам
git diff <baseline> <end> -- <список_файлов>Или так:
# Для каждого коммита с тегом показать его собственный diff
git show <commit1> <commit2> <commit3>...Таким образом мы начинаем использовать Git не только как хранилище файлов с версионированием, но и как базу данных с запросами к данным.
Пример того, как это выглядит в IDE (но с другими кодами user story):
Внизу по центру – отфильтрованный по тегу задачи граф коммитов.
Внизу справа – список изменённых файлов в рамках выбранной задачи: RFC, код программы и документация.
Мы как разработчики Gramax можем добавить удобные фильтры в режиме просмотра изменений. Тогда полученным результатом в виде diff по репозиторию можно будет делиться в виде ссылки с параметрами фильтрации в URL.
Если добавить иерархию артефактов, то можно будет фильтровать репозиторий по коду RFC и видеть все изменения в репозитории, которые были сделаны в рамках этого RFC.
PRD
├── RFC 1
│ ├── User Story 1
│ ├── User Story 2
│ └── User Story 3
├── RFC 2
│ ├── User Story 4
│ └── User Story 5
└── RFC 3
└── User Story 6Таким образом, мы можем делать backward-трассировку требований через фильтры по тегам или git blame по строке в документации, user story, RFC или PRD.
git blameЛюбой участник проекта видит в конфиге или документации timeout=30s. Делает git blame. Видит коммит с тегом #us-d07b2e34. Кликает – попадает в файл tasks/us-d07b2e34.md. Там написано: «Увеличить таймаут из-за медленных ответов от API платёжной системы, см. RFC-42». Переходит в rfc/rfc-42.md – там анализ про��лемы и решение. 30 секунд вместо двух часов поиска.
Выявленные проблемы
Если разработчики более-менее умеют разделять работу над разными функциями на разные коммиты и добавлять теги к коммитам, то продакты и аналитики – нет. Но это решаемая проблема: Gramax может предлагать выбирать теги из актуальных user story во время публикации изменений, а также разбивать изменения на разные коммиты алгоритмически и через LLM, сразу или в CI/CD.
Если забыли указать тег при коммите или указали не тот, то можно исправить это задним числом через визуальный редактор, как это уже сделано в GIGA IDE (Git → Log → выбрать коммит → F2).
Git не хранит информацию о перемещении файлов, а вычисляет перемещения на лету по похожести файлов. По умолчанию, если файл поменялся не более чем на 50%, то Git определит перемещение. Лучше делать перемещение и изменение файла в двух коммитах, что можно делать автоматически без участия пользователя.
Gramax – это open source. И если мы сами начнём применять такой подход, то нам необходимо будет полностью раскрыть внутреннюю работу, ведь все артефакты будут теперь в нашем репозитории на GitHub.
Беспокоиться о производительности Git не нужно – он отлично работает с большими объёмами данных. Microsoft вложила много сил в оптимизацию Git. В 2017 году в Microsoft перенесли разработку Windows в Git, а это около 300 GB, 3,5 миллиона файлов и 4000 инженеров.
Итог
Мы можем вести полный цикл разработки от идеи до продакшена в Git: документацию, код, задачи, концепции, обсуждения – с трассировкой на уровне коммитов. И когда кто-то из коллег спросит «Почему это так работает?», то мы сможем дать ответ за секунды, а не часы. Это и есть backward-трассировка требований, которой мы можем достичь, используя Git как базу данных.
Основная проблема в том, что нужно доработать Gramax, чтобы и разработчики, и аналитики, и технические писатели, и стейкхолдеры могли работать с единым репозиторием в этой парадигме. Поэтому нужна ваша обратная связь о жизнеспособности такого подхода, а также ваши предложения и сомнения. Пишите комментарии под статьёй.
Если вам понравился подход – ставьте плюс, в следующих статьях опишу forward-трассировку и то, как можно решить проблему со знаниями, которые остаются в чатах мессенджера.
Если вы хотите провести пилот у себя в компании, напишите мне в Telegram: @alexvnder
Подпишитесь на Telegram-канал Gramax
Сайт Gramax: https://gram.ax
