AI intro 8 - Product docs with AI

Human made doc

Нормализованная проза по исходной транскрибации звонка. Для урока использован только релевантный фрагмент про работу с продуктовыми документами, Markdown, Codex, транскрибации и Neuronet.

Есть люди, которые уже пишут в Markdown-формате, более пригодном для AI: чтобы имет супер возможность создавать в своем Codex или Claude Code базы знаний по каждому напаравлению своего продукта, и чтобы AI модели могли красиво читать эту базу знаний, искать по документам и использовать их как контекст.

И есть более продуктовый подход: Confluence, где документы пишутся прежде всего для людей, для того чтобы документы прочитали люди. То есть Confluence давно используется как человеческая база знаний, а Markdown постепенно становится форматом, удобным для AI Native работы.

Здесь важно понимать, что ранее мы уже пробовали практически все форматы продуктовой документации: MS Office, BaseCamp, Notion, Google Docs, Confluence, документы с картинками, документы со стрелочками на скриншотах, видео, Loom и так далее. В какой-то момент Loom стал вершиной эволюции: ты не просто пишешь текст, а рассказываешь и одновременно показываешь на экране, что происходит. В формате Loom максимально удобно делать презентации продуктов, записывать идеи, объяснять задачи и делать инструкции.

Но у Loom и Google Meet есть общая проблема: люди поговорили, кто-то посмотрел запись, кто-то не посмотрел, кто-то что-то понял, кто-то не понял или забыл, и после приятно проведенного времени все разошлись. Для эффективной продуктовой работы такого подхода недостаточно. Разговор сам по себе не превращается в устойчивое знание, которое можно переиспользовать всем членам команды в любой момент.

Параллельно появился AI, и люди научились генерировать документы. Это привело к другой проблеме: AI slop. Генерятся километры текста, которые никто не хочет читать. Даже раньше было сложно заставить людей читать обычные, сделанные людьми, большие документы, то теперь стало еще хуже: человек видит AI slop текст, с первого абзаца понимает, что это нагенерили моделью и не хочет это читать, тратить на это время. Получается, что AI умеет производить текст, но продуктовая работа от этого автоматически лучше не становится.

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

Мой простой опыт такой: продуктовая работа живет в Codex как папка Product. Очень важный принцип: проект в Codex должен быть привязан к реальной папке на локальном диске. То есть я делаю у себя папку Codex, внутри нее папку Product, а потом в Codex создаю проект через existing folder и указываю эту локальную папку. Получается простая связка: проект в Codex равен папке на локальном диске.

Следующий шаг, чтобы синхронизировать ваши локальные папки внутри команды между собой, вы делаете в своем проекте Product Git структуру, и выгружаете после каждой рабочей сессии обновления в Github команды. Другие члены команды обновляют свои локальные папки перед началом работы и делают коммиты в общий Github при создании обновлений или новых документов. Примерно так же работают разработчики с обновлением кода.

Дальше магия начинается с организации вашей папки Product по отдельным чатам, которые так же называют агентами. Вы создаете в вашей папке Product множество чатов по каждой нужной вам в работе продуктовой теме. Здесь нет правил, вы можете темой испльзовать кикофы со стейкхолдерами, или синки с командой, или синки с другими командами. Например, у нас есть документ PRD. Я делаю отдельный чат (агент) для PRD и начинаю складывать туда все исходники, которые относятся к продуктовой работе по PRD. Таким образом вы загружаете всю исходную информацию в это чат, и AI Codex теперь знает о контексте работы над вашим PRD документов все необходимое.

А какие исходники у нас чаще всего есть на старте? В первую очередь Google Meet, то есть разговоры с рабочих встреч. Пришел Shurick, провел kickoff, поставил задачу. Далее мы обсудили задачу с командой, и у нас появляются несколько Google Meet как первичный источник. Очень качественной информации, потому что она идет из первых уст.

Если появляется новая тема, например PlayCanvas, я создаю новый чат (агент) в папке Product и прямо пишу: здесь будем делать всю продуктовую работу по PlayCanvas. После создания обязательно переименовывайте чатик правильно и коротко, чтобы было понятно над чем в нем ведется работа. Важно не просто хранить MD файлы в Codex, а создавать нормальное рабочее пространство, где Codex понимает, с какой темой мы сейчас работаем.

Для транскрибации Google Meet я использую мини-апп Command Center. В Xsolla есть культура мини-аппов и дизайн-прототипов: можно через Neuronet завайбкодить автоматизацию для своего внутреннего процесса. Command Center я использую как раз для того, чтобы превращать Google Meet в транскрибации в нужном мне формате.

Раньше работа выглядела иначе: нужно было записать kickoff, потом самому пересмотреть его, проштудировать, вытащить важное, собрать документ. С важными kickoff от Shurick я до сих пор работаю вручную, потому что приоритет высокий, но для десятков звонков каждую неделю сам процесс обработки изменился. Теперь можно взять транскрибацию часовую встречу в MD формате, загрузить ее в нужный проект и чат Codex, дать локальному агенту контекст и попросить: дай сводку только относительно той темы, которая мне нужна. Если на встрече обсуждали много всего, а мне важен только один участок, агент помогает быстро вытащить именно релевантную часть. Это экономит огромное количество времени. Все работает в три клика: транскрибировали, добавили MD-file в Codex, надиктовали минуту контекста и задачу на обработку, получили готовый результат в MD файле или сразу в Confluence через Skill.

Для этого у меня в Command Center подключен Google Calendar. Я могу брать встречи, транскрибировать их, превращать в Markdown и далее раскидывать по релевантным агентам в папке Codex проекта Product. Эти MD-файлы становятся исходным слоем информации: не красивым документом ради документа, а материалом, который можно загрузить в релевантный чатик агента Codex, получить обработанный MD-файл и запустить его в работу далее - передать в Neuronet, использовать для формирования PRD, архитектурных решений, answers и других продуктовых артефактов.

Важная цель здесь не в том, чтобы просто наделать модных Markdown-файлов. Цель в том, чтобы вся команда работала с одной и той же информацией. И не только команда, но и вся компания, внутри компании есть много людей, которые могут спросить Neuronet что-то про Metasites. Если мы берем лучшие ответы, PRD, архитектурные решения, транскрибации, answers и говорим Neuronet: загрузи и обнови всю информацию по Metasites, то он запоминает этот слой и дальше может отвечать на его основе.

В результате у нас появляется четкая информационная база знаний: документы, архитектурные решения, PRD, опросники, answers, дополнительные PRD и другие материалы. Это важно, потому что стейкхолдеры, топ-менеджмент, партнеры, игровые разработчики и другие участники процесса задают вопросы Neuronet. Если кому-то нужно что-то узнать, он может не идти в личку к одному из продуктовых людей, а спросить у Neuronet из общей AI-базы компании.

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

Markdown-файлы, Codex и Neuronet помогают создать слой исходной информации, который доступен всем. Более того, любой человек может взять набор этих MD-файлов как Source of Truth, загрузить их в свой Codex или Claude Code и оказаться на 100% в том же контексте, что и основная продуктовая команда. Это особенно важно для новых участников проекта: человек может установить Codex, создать проект, загрузить туда материалы и начать спрашивать: что происходит, какие решения уже приняты, где North Star, какие есть PRD, какие обсуждения были на kickoff.

Поэтому я стараюсь хранить всю информацию по Metasites в Markdown. Это нужно не только продактам, но и разработчикам. Разработчики сопротивляются новым AI процессам сильнее, но все равно важно, чтобы даже самый далекий от продукта разработчик понимал North Star проекта и видел, куда мы идем. Не только три продуктовых человека должны знать, какая у нас задача и какие идеи мы придумали, а вся команда должна иметь доступ к общей картине.

Эти же MD-файлы я загружаю и прошу запомнить Neuronet. Так мы решаем свои продуктовые проблемы и одновременно распространяем их решение на всю компанию. У нас появляется не просто набор документов, а общий AI-readable слой: его можно читать людям, его можно загружать в Codex, по нему можно задавать вопросы в Neuronet, из него можно собирать PRD и другие рабочие документы.

AI intro 8 - Product docs - Goals & Answers

Source of Truth

Теперь важный блок: что делать после того, как мы добавили в нужный чат или агент Codex название документа и загрузили туда все исходные материалы. Исходными материалами могут быть Markdown-файлы, Confluence-документы, старые PRD, транскрибации, ответы из обсуждений и любые другие документы, которые относятся к этой теме. Просто загрузить их недостаточно. После этого нужно задать цель.

Best Practice

Цель формулируется очень прямо: найди, пожалуйста, в Confluence best practice по нужному нам документу. Например, если мы хотим сделать PRD, архитектурный документ, постановку задачи в разработку или другой продуктовый артефакт, мы просим Codex найти корпоративные best practice именно по этому типу документа. Codex ищет, какие есть требования, как этот документ принято делать в компании, какие разделы обязательны, какие критерии качества есть, какие примеры уже существуют.

После этого Codex должен объяснить нам, как правильно делать этот документ в соответствии с корпоративными требованиями. Это важный шаг, потому что мы не хотим, чтобы AI просто придумал красивую структуру из головы. Нам нужно, чтобы будущий документ опирался на реальный корпоративный формат, на принятые best practice и на то, как такие документы уже пишутся внутри компании.

Template

Следующий шаг: мы устанавливаем для AI цель и говорим, создай, пожалуйста, максимально соответствующий best practice темплейт нужного нам документа. В этот момент Codex уже знает, какой документ нам нужен, видел исходные материалы и изучил корпоративные требования. Поэтому он может создать не случайный шаблон, а наиболее точный и качественный темплейт целевого документа.

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

На этом шаге вы регулируете целевой темплейт под свою задачу. Это не механическая операция. Здесь продуктовый человек должен посмотреть и почувствовать: этот шаблон действительно поможет собрать нужный документ или он уводит не туда. Codex может предложить хорошую базу, но именно вы решаете, какой уровень детализации нужен.

Questionnaire

Когда исходная информация загружена, best practice и корпоративные требования изучены, а темплейт сформирован и скорректирован, нужно сказать Codex самую важную фразу: теперь сравни, пожалуйста, этот темплейт и всю исходную информацию и проверь, какой информации нам не хватает, чтобы полностью и максимально качественно заполнить темплейт.

После этого нужно попросить: для недостающей информации сделай, пожалуйста, questionnaire, то есть опросник с нужным количеством вопросов. Codex должен взять целевой темплейт, взять все исходные материалы, сравнить одно с другим и понять, где есть пустоты. Какие разделы мы пока не можем заполнить? Какие решения не зафиксированы? Какие assumptions непонятны? Где не хватает бизнес-цели, пользовательского сценария, технических ограничений, метрик, рисков, зависимостей, acceptance criteria?

На этом шаге нужно быть аккуратным. Codex может сделать опросник на 200 вопросов, и с таким документом будет крайне сложно работать. На мой взгляд, оптимальное количество вопросов для хорошей проработки продукта или документа - примерно 40-80. Этого достаточно, чтобы хорошо подумать и вытащить недостающую информацию, но не превратить процесс в бесконечную анкету.

В результате Codex создает отдельный MD-файл с вопросами. Это не просто список любопытных вопросов. Это список того, какой информации ему не хватает для достижения цели: чтобы заполнить конкретный темплейт на основании конкретной исходной информации. Такой questionnaire становится мостом между сырыми источниками и качественным финальным документом.

Answers

Следующий шаг: этот MD-файл с questionnaire мы закидываем в Codex и говорим: теперь спрашивай меня по этому опроснику, каждый вопрос по очереди, а результаты записывай в файл answers. И здесь начинается самая ценная часть продуктовой работы.

Во-первых, продуктовая работа становится голосовой. Codex задает вопрос 1, вы отвечаете голосом. Потом вопрос 2, вы отвечаете. Потом вопрос 3, вы отвечаете. Можно отвечать одному, можно проходить опросник вместе с командой. Не нужно сразу садиться и писать идеальный документ. Вы просто отвечаете что думаете по задаваемым опросником вопросам.

Во-вторых, продуктовая работа становится гораздо точнее. Это уже не AI-slop, не сгенерированная портянка текста, а ваша продуктовая информация от первоисточника: от продуктовой команды, от владельца направления, от людей, которые действительно понимают, что происходит. Codex не придумывает за вас продукт. Он помогает правильно спросить, собрать и структурировать то, что знаете вы.

Это максимальнй лайф чендж для продуктвой работы, т.к. вам теперь не нужно писать документы "с белого листа", что всегда было невероятно сложно и трудоемко. И вам не нужно генерить не связанный с контекстом вашего продукта AI слоп. Вы сами, из первых уст создаете контент своим голосом на основании своих знаний, мыслей, идей.

В процессе ответов нужно следить за качеством вопросов. Со временем вы начнете чувствовать, хорошие вопросы идут или нет. Если вопросы повторяются, слишком однообразные, слишком абстрактные или не помогают думать, ничего страшного. Можно сразу сказать Codex: эти вопросы слишком однообразные, сделай вопросы более точными, более продуктовыми, более разнообразным, по сути этой темы или другой. Опросник можно корректировать на ходу, и после этого следующие вопросы будут точнее и точнее.

В результате вы получаете очень сильный answers-файл. По сути, это первоисточник информации о продукте. Это информация с первых рук от продуктовой команды. Такой файл можно использовать как source of truth по проекту: загружать в Neuronet, отдавать новым людям, добавлять в Codex, использовать как основу для будущих документов.

Только после этого мы переходим к финальному документу. Финальная команда звучит так: заполни темплейт на основании наших answers и на основании всей исходной информации. Теперь Codex работает не в пустоте. У него есть корпоративные best practice, целевой темплейт, исходные материалы и ответы продуктовой команды на вопросы, которые закрывают информационные пробелы.

Именно поэтому финальный документ получается уже не AI-slop, а качественный документ по сути. Он собран из реальной информации, проверен через вопросы, структурирован по правильному темплейту и соответствует тому формату, который нужен компании. Это принципиально другой уровень работы по сравнению с просьбой "напиши PRD" в пустом чате.

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

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

Я настоятельно рекомендую использовать этот механизм. Он помогает всем быть на одной странице. Причем не только трем продуктовым людям, которые обсуждали продукт на встрече, а всей команде проекта и всей компании. У нас появляется общий способ превращать разговоры и разрозненные источники в качественные документы, answers, source of truth и общий слой знаний о продукте.

AI intro 8 - Product docs - workflow

Если сформулировать практический workflow, он выглядит так.

Сначала создаем локальную папку проекта и подключаем ее в Codex через existing folder. Важно, чтобы Codex-проект был связан с реальной файловой структурой, а не жил где-то абстрактно.

Потом заводим внутри проекта тематические агенты - чаты: PRD, архитектурные решения, answers, источники, kickoff, отдельные продуктовые направления. Названия должны быть понятными, потому что эта структура будет работать как карта проекта.

После этого собираем первичные источники: kicoffs. транскрибации Google Meet, Loom, заметки, старые документы, Confluence-материалы, ссылки, ответы из обсуждений. Их можно складывать в тематические папки, а можно просто добавлять как вложения в правильный чат или агент Codex. На этом этапе не нужно пытаться сразу сделать идеальный итоговый документ. Важно собрать полный исходный слой информации.

Дальше превращаем звонки и встречи в Markdown. Для этого можно использовать Command Center или другой мини-апп для транскрибации. Главное, чтобы результат был текстовым, лежал в проектной папке и был доступен Codex.

Затем просим Codex найти корпоративные best practice по целевому документу: PRD, архитектурному документу, постановке задачи, стратегии или любому другому формату. Codex должен понять, как такой документ принято делать внутри компании.

После этого просим Codex создать темплейт целевого документа по найденным best practice. Темплейт проверяем вручную и регулируем: делаем короче, если нужен компактный документ, или подробнее, если нужна глубокая постановка задачи.

Потом просим Codex сравнить темплейт со всей исходной информацией и определить, какой информации не хватает. На основе этих пробелов Codex делает questionnaire - отдельный MD-файл с вопросами. Оптимально держать опросник примерно в диапазоне 40-80 вопросов, чтобы он был достаточно глубоким, но еще рабочим.

Дальше просим Codex задавать вопросы по questionnaire по одному и записывать ответы в answers. На этом этапе мы голосом или текстом даем продуктовую информацию от первоисточника, а Codex аккуратно собирает ее в структурированный файл.

После этого просим Codex заполнить темплейт на основании answers и всей исходной информации. Так получается финальный документ, который основан на реальных источниках, корпоративных требованиях и ответах команды, а не на пустой генерации.

В конце проверяем документ: вычитываем, применяем проход по опечаткам и терминам, смотрим, правильно ли перенесены идеи. Если видим, что AI где-то недостаточно точно понял мысль, корректируем промпт или возвращаемся к answers.

И наконец, загружаем отобранный и нормализованный слой в Neuronet или другую общую AI-базу знаний, чтобы не только автор документа, но и вся команда могла спрашивать и получать ответы из одного источника правды.

AI intro 8 - Product docs - Markdowns

Теперь отдельно про структуру хранения продуктовых документов. Мы делаем новую структуру по AI-first принципам. Все исходники документов должны быть в Markdown. Это важно, потому что Markdown одинаково хорошо читается человеком, Codex, Claude Code, Neuronet и другими AI-инструментами. Для удобного ручного чтения Markdown можно использовать self-hosted Obsidian или Sublime Text. Главное, чтобы документы оставались простыми текстовыми файлами, которые можно хранить в репозитории, коммитить, читать, искать и загружать в AI.

Чтобы работать с такими документами, каждый участник может создать проект в своем Codex или Claude Code и засинкаться с этой репой. Коммитить можно, но есть важное правило: не править уже ранее сделанные документы без отдельной причины и договоренности. Если нужен новый продуктовый документ, мы не переписываем старый, а делаем новый файл с пометкой о новой версии. Это сохраняет историю, позволяет понимать, откуда взялась информация, и не ломает уже зафиксированные артефакты.

Структура папок устроена по роли документов. Верхний уровень делит материалы на source of truth, secondary documents, calls и далее папки конкретных продуктовых документов, которые сейчас актуальны и готовятся. То есть отдельно лежит самая ценная первичная информация, отдельно вторичные материалы, отдельно звонки и отдельно рабочие папки под конкретные PRD, ADR, стратегии, постановки задач и другие документы.

Внутри рабочих папок действует простое языковое правило: английские файлы лежат в корне, русские файлы лежат в папке RU. Это помогает не смешивать версии, быстрее находить нужный файл и не плодить хаос в названиях. Если документ готовится сразу на двух языках, структура должна сразу поддерживать это разделение.

Все документы теперь не пишутся с белого листа. Мы формируем их через уже описанный процесс: даем Codex или Claude Code запрос и исходные документы, спрашиваем best practice template для нужного документа, подгружаем все релевантные MD-файлы, просим определить, какой информации не хватает, и сформировать questionnaire. Если questionnaire получается слишком большим, например на 100+ вопросов, его нужно корректировать. Обычно хватает примерно 50 вопросов, иногда 40-80, если документ широкий.

Дальше questionnaire загружается в Claude Code или Codex в режим "спрашивай - принимай ответы голосом". Мы отвечаем на все вопросы документа. Если сами не знаем, что отвечать, опросник можно отправить владельцу знания или продуктовой команде. В нашем контексте это может быть, например, @d.dolgov: так даже лучше, потому что ответы приходят от первоисточника, а не достраиваются моделью.

После ответов мы даем команду сформировать нужный документ по best practice template, совокупной базе данных и answers. Здесь под совокупными данными имеется в виду вся собранная информация: исходные MD, Confluence, транскрибации, source of truth, secondary documents, answers и дополнительные уточнения.

Если получившийся документ не нравится, это нормально. Например, разработка может посмотреть ADR и сказать, что формат или состав документа не подходит. В этом случае не нужно начинать с нуля. Можно переписать формат или состав документа, используя уже готовые answers.md от Narrative Leader или другого первоисточника. Answers - это ценная база, ее не надо выбрасывать только потому, что первый вариант итогового документа получился неудачным.

Если в процессе переписывания добавляется новая информация, уточнения или решения, по ним должен остаться отдельный артефакт или handoff в Markdown. Этот файл нужно закоммитить в папку данного документа на GitHub. Например, если речь идет про ADR, такой handoff должен лежать в папке ADR. Это правило защищает нас от потери контекста: любые новые вводные должны остаться в источниках, а не только раствориться в финальном тексте.

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

Еще полезно заглядывать в общую папку Source of Truth, где лежит самая ценная информация по продукту. Перед созданием нового документа можно подгрузить в Codex или Claude Code не только текущие материалы, но и предшествующие опросники и answers. Если в Source of Truth уже есть 80, 120 или 200 вопросов и ответов с максимально точной информацией из первых уст, это огромный контекст, который нельзя игнорировать.

Все документы из Source of Truth дополнительно дублируются в Confluence, в пространство Metas/Metasdev, а далее загружаются в Neuronet и Slack. Сейчас это можно делать вручную, позже такую синхронизацию можно автоматизировать. Смысл в том, что Markdown-репозиторий становится AI-readable источником и рабочей базой, а Confluence остается привычным местом чтения и навигации для людей.

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

Главный принцип: Markdown-документы делаются не ради Markdown. Они нужны, чтобы превратить разговоры, встречи и разрозненные решения в общий слой знания, с которым могут работать люди и AI. Codex в этом процессе является рабочим инструментом для локальной продуктовой работы: он читает папку, помогает структурировать источники, собирать документы, вытаскивать релевантную часть обсуждения и поддерживать проектный контекст.

Neuronet в этой схеме становится способом распространять уже подготовленную информацию шире: на компанию, партнеров, разработчиков, менеджеров и всех, кто должен понимать, что происходит. Если сделать этот процесс правильно, мы уменьшаем разрыв между теми, кто придумал продукт, и теми, кто потом должен его делать, продавать, поддерживать или объяснять.

Именно поэтому мы работаем с MD-файлами, Codex и Neuronet не как с модной игрушкой, а как с инфраструктурой продуктовой памяти. Разговор сам по себе исчезает. Loom сам по себе посмотрят не все. Большой AI-документ сам по себе никто не прочитает. А хорошо организованный слой исходной информации в Markdown можно читать, искать, загружать в Codex, обновлять в Neuronet и использовать как живую базу для продуктовой работы.