Меня зовут Александр Мачулин, я основатель Gramax – open source системы для ведения документации в подходе Docs as Code с визуальным редактором.

Сегодня я расскажу вам идею, как вести всю документацию по проекту и весь цикл разработки в одном Git-репозитории и настроить backward-трассировку требований в Git.

Прошу обратить внимание, что это не описание проверенного годами подхода. Это идея, по которой нужна обратная связь.

Зачем вам это читать?

• Если вы разработчик или аналитик, то вам наверняка знакома ситуация: нужно понять, как работает программа, а актуальной документации нет. Постановка на разработку потерялась, и единственный способ разобраться – смотреть в код.

• Если вы продакт-менеджер, то release notes приходится собирать вручную по памяти, и половину фич вы просто забываете упомянуть. Не хватает связи между задачами и изменениями в коде.

• Если вы техлид или архитектор, то наверняка часто задаётесь вопросом «Почему программа работает именно так?». История коммитов показывает, что изменилось, но не объясняет, почему. А без этого понимания сложно быстро и безопасно вносить изменения в систему.

У меня разный опыт работы в разработке: разработчик, тимлид, продакт-менеджер. И во всех ролях, в разных командах я сталкивался с этими вопросами, на которые очень сложно получить ответ. Вот хороший пример из недавней статьи по схожей теме:

В конфиге написано timeout=30s. Раньше было timeout=5s. Кто-то увеличил значение в три раза. Почему? Git blame показывает, кто это сделал. А вот причина – утеряна.

— How to build a context graph

Думаю, что эти проблемы знакомы всем. В любой компании информацию о системе приходится собирать по кусочкам: 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 теги задач.

Пример работы подхода

1. Создали задачу в таск-трекере с кодом us-137, по результатам которой необходимо подготовить RFC на новое предложение от продактов. В рамках us-137 написали RFC и уточнили PRD.

2. Согласовали RFC, создали задачу с кодом us-138, чтобы провести более детальный анализ и расписать проект по user story. В рамках детализации поняли, что не учли несколько моментов в RFC, скорректировали его.

3. Начали реализовывать проект в первой 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. Также можно фильтровать по тегам и папкам изменения файлов, например:

1. Найти список всех ревизий по #us-170.

2. Вычислить состояние до первой такой ревизии (baseline) и состояние после последней (end).

3. Показать 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.

Любой участник проекта видит в конфиге или документации timeout=30s. Делает git blame. Видит коммит с тегом #us-d07b2e34. Кликает – попадает в файл tasks/us-d07b2e34.md. Там написано: «Увеличить таймаут из-за медленных ответов от API платёжной системы, см. RFC-42». Переходит в rfc/rfc-42.md – там анализ проблемы и решение. 30 секунд вместо двух часов поиска.

Выявленные проблемы

1. Если разработчики более-менее умеют разделять работу над разными функциями на разные коммиты и добавлять теги к коммитам, то продакты и аналитики – нет. Но это решаемая проблема: Gramax может предлагать выбирать теги из актуальных user story во время публикации изменений, а также разбивать изменения на разные коммиты алгоритмически и через LLM, сразу или в CI/CD.

2. Если забыли указать тег при коммите или указали не тот, то можно исправить это задним числом через визуальный редактор, как это уже сделано в GIGA IDE (Git → Log → выбрать коммит → F2).

3. Git не хранит информацию о перемещении файлов, а вычисляет перемещения на лету по похожести файлов. По умолчанию, если файл поменялся не более чем на 50%, то Git определит перемещение. Лучше делать перемещение и изменение файла в двух коммитах, что можно делать автоматически без участия пользователя.

4. Gramax – это open source. И если мы сами начнём применять такой подход, то нам необходимо будет полностью раскрыть внутреннюю работу, ведь все артефакты будут теперь в нашем репозитории на GitHub.

Беспокоиться о производительности Git не нужно – он отлично работает с большими объёмами данных. Microsoft вложила много сил в оптимизацию Git. В 2017 году в Microsoft перенесли разработку Windows в Git, а это около 300 GB, 3,5 миллиона файлов и 4000 инженеров.

Итог

Мы можем вести полный цикл разработки от идеи до продакшена в Git: документацию, код, задачи, концепции, обсуждения – с трассировкой на уровне коммитов. И когда кто-то из коллег спросит «Почему это так работает?», то мы сможем дать ответ за секунды, а не часы. Это и есть backward-трассировка требований, которой мы можем достичь, используя Git как базу данных.

Основная проблема в том, что нужно доработать Gramax, чтобы и разработчики, и аналитики, и технические писатели, и стейкхолдеры могли работать с единым репозиторием в этой парадигме. Поэтому нужна ваша обратная связь о жизнеспособности такого подхода, а также ваши предложения и сомнения. Пишите комментарии под статьёй.

Если вам понравился подход – ставьте плюс, в следующих статьях опишу forward-трассировку и то, как можно решить проблему со знаниями, которые остаются в чатах мессенджера.

• Если вы хотите провести пилот у себя в компании, напишите мне в Telegram: @alexvnder

• Поставьте нам звёздочку на GitHub и GitVerse

• Подпишитесь на Telegram-канал Gramax

• Сайт Gramax: https://gram.ax