Предисловие
В этой статье хочу поделиться опытом создания документации, которая используется при создании мобильных приложений.
Сразу оговорюсь, что это не enterprise решения.
Это небольшие мобильные приложения, разрабатываемые в режиме вайб-кодинга с использованием ИИ-агента Claude Code Opus 5
Концепция приложения
App Concept
Краткое описание приложения.
Очень краткое, на языке пользователя, без технических подробностей.
Понятно, что разрабатывается как первый документ проекта, до начала разработки.
Часто формулируется как ответ на вопрос – “Чего хочет пользователь?”
Хранится в архиве проекта.
Как правило, не редактируется.
Концепция проекта
Project Concept
Стартовое, исходное описание проекта, на основе концепции приложения.
Включает в себя пользовательские истории.
По сути дела, это еще не технический проект, а пользовательская модель приложения, составленная в результате декомпозиции концепции приложения.
Отсюда, еще одно название, равнозначное – App Model.
Часто формулируется как ответ на вопрос – “Что должен сделать разработчик, чтобы реализовать намерение (желание, запрос, потребности) пользователя?”
Т.е., более подробное описание приложения с учетом базовых инженерных и архитектурных деталей. Например, основная задача, бизнес-процесс приложения, дочерние процессы, их последовательность и взаимосвязи, краткие описания экранов, базовые технические параметры – язык программирования, фреймворк, состав и структура данных, а также определенные общие параметры приложения, например, локализация, количество пользователей, модель распространения, монетизация и др.
Как правило, язык изложения этого документа еще во многом понятен пользователю.
Главная ассоциация – это уменьшенная копия, модель будущего приложения. Как авиамодель самолета – маленькая, внешне похожая, но без многих технических деталей.
Или, как набросок, схема приложения.
Хранится в архиве проекта.
Как правило, не редактируется.
На первый порах используется как ориентир, план, основа для дорожной карты. Потом используется главным образом как исторический артефакт или для анализа особенностей процесса разработки путем сравнения с конечным результатом – что было, как изменилось, почему и что стало.
Карта проекта
Project Map
Строится на базе документа Концепция проекта.
Отличается тем, что не является архивной и является рабочим инструментом проекта.
Служит для отслеживания прогресса проекта – что сделано, какие задачи следующие и т.д.
Не является статичной в отличие от Концепции проекта. Карта проекта можно редактироваться, меняться, обновляться в случаях необходимости. Некоторые задачи могут излагаться более детализированно, могут добавляться новые задачи и под-задачи с учетом текущей обстановки проекта.
В то же время желательно сохранять смысловую связь с исходной Концепцией проекта, чтобы не потерять ориентиры и общее направление проекта.
Документы по итогам чата / сессии
-
Итоги чата
-
Решения
-
Модель процесса
-
Pro-Tools
Итоги чата
Список тем, вопросов, которые обсуждались в ходе чата.
Простое перечисление. При необходимости с кратким пояснением, чтобы было понятно о чем идет речь.
По сути дела это есть оглавление.
Полезно при поиске по чатам, если нужно найти какую-то тему.
Можно просто просмотреть или использовать встроенные поисковики.
Технически это можно вычислить по репликам человека, пользователя. В большинстве случаев именно он начинает обсуждение определенной темы.
Как правило, сессия / чат посвящается решению одного вопроса, задачи, в нашей терминологии – процесса.
Также могут быть процессы, которые реализуются в нескольких чатах, а также могут быть чаты, в которых решаются вопросы по разным процессам. Такая специфика учитывается по ходу.
Оглавление составляется моделью в 2 прохода:
-
Сначала составляется черновой список всех вопросов, которые обсуждались
-
Затем делается их укрупнение, поскольку те или иные темы могут обсуждаться в разных местах чата.
Итоговый, укрупненный список публикуется моделью в конце чата под названием Итоги чата.
Решения
После составления оглавления модель выбирает из списка тем те, в которых принимались решения. При этом необходимо провести отсев мелких и незначимых решений. В основном отбираются решения по разработке продукта, которые существенным образом повлияли на процесс разработки.
Примерная структура описания решения:
-
Проблема (ситуация, сложности, минусы)
-
Предложенное, принятое, реализованное решение
-
Обоснование решения
Решения сохраняются отдельными файлами в хронологическом порядке в отдельной папке /decisions внутри общей контекстной папки проекта /docs.
Также отдельным файлом модель ведет файл DECISIONS_INDEX, где составляет список решений со ссылками на них. Удобно для быстрого поиска.
Решения хранятся как история проекта. Они могут понадобиться спустя некоторое время при необходимости вспомнить, почему было принято то или иное решение.
Сохраняются как принятые решения, так и отвергнутые.
Файлы решений, как правило, не обновляются и не редактируются.
Если принимается новое решение, изменяющее предыдущее, оно оформляется новый файлом. В нем может быть указана ссылка на предыдущее решение по соответствующему вопросу.
Модель процесса
Приложение рассматривается как набор (система) взаимосвязанных процессов, которые также могут называться в зависимости от уровня декомпозиции задачами, операциями, действиями и т.д.
В первоначальном документе Концепция дается исходное базовое описание основных бизнес-процессов приложения.
В документе Модель процесса по итогам чата дается достаточно развернутое описание конечного продукта, модели процесса.
Как правило, оно включает в себя уточненнное название процесса, список и описание его дочерних процессов.
Модель процесса также может включать в себя и раздел с описанием технических параметров реализованного процесса. Но основные технические параметры находятся в коде.
Описание конечной модели процесса является статичным. Т.е., оно делает срез готовой части продукта.
В этом описании нет истории, анализа и т.д. Только статика, модель процесса.
Частично, вопрос истории реализации процесса закрывают описания принятых решений.
Фиксация решений должна предшествовать описанию конечной модели процесса, поскольку модель опирается на принятые решения.
Каждая модель процесса оформляется отдельным файлом и помещается в папку под названием /processes, которая располагается в общей контекстной папке проект /docs.
Также модель ведет файл PROCESSES_INDEX, где составляет список файлов со ссылками на них.
Файл модели процесса в основном архивный и, как правило, не меняется. Исключения составляют случаи, когда реализация следующих процессов влияет и изменяет модель ранеее реализованных. В этом случае новые особенности процесса затирают предыдущие в документе, который должен поддерживать только конечную версию.
Содержание файлов с конечными моделями процессов могут использоваться как в архивном порядке, так и в актуальном по ходу разработки приложения.
Поэтому их значение в проекте выше, чем у других документов, поскольку они могут быть полезными для оценки состояния проекта и видения целостной картины разрабатываемого приложения непосредственно в процессе разработки.
Pro-Tools
В эту категорию относятся так называемые нетематические обсуждения по ходу чата. Т.е., не относящиеся прямо к разработке приложения, а те идеи, которые рождаются в ходе разработки и могут быть использованы в дальнейшем как правила, алгоритмы и инструменты работы.
Но поскольку это не готовые инструменты, а пока лишь черновые записи, наброски, заметки, идеи, то они носят название Пред-Инструменты, или Pro-Tools
В эту группу относятся следующие категории обсуждений по ходу чата
Код
-
как писать: задача блока в комментарии, типовые решения, модульность, оформление комментариев
Git
-
ветки, коммиты, слияния, что делается само, а что по запросу
Общение
-
порядок диалога, форма ответа, чего не говорить, как подавать инструкции
Документация
-
что куда пишем, шаблоны, границы между документами
Инструменты
-
то, что можно запустить: скрипты, навыки, приёмы работы
Методология
-
рассуждения о разработке в целом, переносимые в другие проекты
Все эти виды обсуждений можно действительно рассматривать как определенные инструменты, которые могут использоваться при разработке приложений, как средства совершенствования хода разработки.
Модель назвала эту категорию урожаем и очередью. Т.е., с одной стороны, это есть урожай находок, которые появились в ходе работы. А с другой, это не склад, не архив, это очередь для их внедрения.
Стиль изложения в этом документе свободный, возможно цитирование чата, возможно заметки со ссылками. Главное, чтобы самому разработчику было понятно о чем идет речь.
По сути дела это черновые наброски идей.
Этот документ оформляется отдельным файлом под названием Pro-Tools.
Это не статичный документ, он пополняется и обновляется по ходу работы.
По окончании чата, либо в другое время по выбору разработчика, можно произвести обработку черновых записей, выделить важные правила, алгоритмы, описать их более подробно и структурировано. А потом включить в правила работы с моделью, в методологию разработки и др.
Также, на основе таких заметок могут возникать идеи для создания реальных инструметов – skills, plugins или даже отдельных приложений.
Т.е., это действительно урожай идей и очередь для их внедрения.
Новые идеи, причем из разных чатов, могут записываться в этот файл. Порядок любой, но обычно удобен хронологический.
Реализованные идеи удаляются из списка. Тем самым поддерживается актуальность данного документа.
Контекстная директория проекта
В целом, это может выглядеть следующим образом:
Заключение
Документация проекта не является его обязательным компонентом.
Можно создать приложение и без документации, сохраняя его образ, модель в уме.
Тем не менее, в большинстве случаев документация является существенной опорой проекта и одним из его важных инструментов.
Само собой разумеется, что значение документации растет пропорционально величине проекта. Чем больше проект, тем важнее вести документацию.
Описанные выше документы не рассматриваются автором как обязательные. Но польза от них есть и она заметная. Первые, начальные документы показывают направление работы, а документы по окончании проекта, и по окончании этапов проекта, помогают и контролировать проект, управлять им, повышая качество работы, и совершенствовать методы разработки.
Из описанных выше документов по окончанию чата я бы выделил в первую очередь Итоги чата, т.е., список, оглавление, обсуждавшихся в чате вопросов, тем. Это очень удобная опция, особенно когда у проекта много чатов.
Это легко автоматизируется и сегодня практически любая модель может это сделать. Я даже сделал для себя отдельный skill.
Остальные документы, что называется, на любителя. Например, в последнее время в сети часто обсуждается вопрос необходимости сохранения принятых решений, чтобы было видно, что решено и почему именно так.
Здесь главное избежать второй крайности, когда создание и особенно обновление документации занимает слишком много времени. И здесь также решение состоит в автоматизации с помощью модели.
Еще один момент: полезно время от времени просматривать те документы, которые создает модель. Нередко она фиксируют мелочи, или, наоборот, слишком усложняет. Или повторяет одно и то же в разных документах. Или излагает таким языком, что вроде все правильно, но в памяти не остается, потому что язык такой как на активных продажах. Также иногда модель излишне драматизирует, типа “от этого решения зависит вся последующая архитектура”, хотя на самом деле речь идет об обычной развилке, ветвлении.
Здесь также хорошо работает образец, написанный человеком, который модель потом использует как шаблон.
Оформление документации очень хорошо делается как раз по окончании чата. Как правило, один чат решает одну задачу. Поэтому очень логично подвести промежуточные итоги.
Но бывает, что желание улучшить процесс толкает разработчика фиксировать те или иные находки, правила, промты и т.д., сразу по ходу работы. Что называется, чтобы не забыть. Увы, это может приводить к тому, что очень много времени модель будет тратить на фиксацию таких находок, их описание, сохранение в определенных документах, а потом проверять связи с другими вопросами, сообщать о расхождениях и т.д. Я тоже однажды попал в такую яму и Claude сам признался, что он опутан протоколами, правилами и инструкциями. Пришлось все упрощать и важным решением было именно перенести весь анализ на окончание чата.
И последнее: зная, что в конце чата модель будет делать оглавление и чтобы облегчить ей работу, можно по ходу ставить отметки. Например, “Начинаем такую-то тему”. Или “Закончили обсуждение темы такой-то”, “Еще раз вернемся к вопросу…” и т.д. Или даже сказать совсем прямо – “Запомнить для итогов”. Такая разметка очень неплохо помогает модели собирать итоги чата. Точно также здесь можно делать пометки по каким-то идеям. Не менять, например, документацию сразу, а просто отметить – “Зафиксировать потом в документации” и вернуться к этому именно при анализе итогов чата.
Дисклеймер
В этой статье не рассматриваются стандартные документы памяти в Caude Code, поскольку это отдельный большой вопрос.И в данном случае меня больше интересовала именно проектная документация.
А у самого Claude Code есть два файла почему-то с одинаковым именем CLAUDE, затем встроенная memory, которая пополняется автоматически по ходу чата. А в последнее время все чаще проявляется и память между чатами, особенно между соседними по времени, или связанными близкими темами. Ну и добавьте сюда, что все это надо различать для Claude Code и для Claude Home. И что в Claude Code теперь проектов нет, а есть только группы, где нет встроенного описания проекта как это было раньше.
У меня еще до этого просто не дошли руки. И главное, после нескольких попыток разобраться, стало ясно, что вначале надо определиться, что хочет сам разработчик, какая документация ему нужна, которая реально помогает.
И тогда уже найти способ состыковать свои файлы с файлами, встроенными в Claude
По сути дела данная статья и есть результат составления своего набора проектной документации.
Автор: AppCrafter
