Comments 22
Грамотное управление требованиями - залог хорошего продукта.
Я тоже делал систему управления требованиями для команды аналитиков, и тоже в Obsidian 😀
https://github.com/dimonier/Obsidian-Requirements-Management
Одновременно измененные MD через Obsidian git нормально мёрджатся, а вот если одновременно изменить canvas, тогда чуда не произойдет, и придется исправлять конфликт вручную. Это единственный недостаток командной работы над требованиями в Obsidian с синхронизацией через git, в остальном работает шикарно.
Не знаю, что такое MD, нагуглить не смог.
Canvas не пользуюсь, т к. не понимаю, как этот плагин может помочь в разработке требований.
Моя статья именно для людей, которые видят проблему коммуникации между аналитиками и программистами. Именно для этого номерные идентификаторы, именно для этого .obsidian не хранится в git.
Мне понравилось. Спасибо за статью и отдельное спасибо за Front Matter Title. Давно искал такой плагин.
После того что надо в номерах тасок делать гэпы читать стало совсем больно. Выглядит как записи в бумажном пронумерованном журнале. 20+ лет автоматизации что-бы перенести бумажный процесс в цифру не уйд от бюрокраитии. Документооборот опять пошел по спирали с наихудшего его варианта.
Дисциплина в проекте это больно, пока не привыкнешь.
Потом наоборот: экономит усилия и позволяет быстро вводить людей в курс, контролировать изменения и, главное, не переделывать лишний раз бизнес-логику в коде.
Если у Вас есть вариант лучше, чем гэпы в номерных идентификаторах (требований, а не тасок), то будет интересно прочитать. Я взял идею из Бейсика 1980-х годов.
К сожалению или к счастью, но универсального общедоступного инструмента для разработки и требований, и кода, трассируемого в требования, не существует. Раз так, то приходится брать контроль за идентификаторами в свои руки. Это, как раз, не больно.
В моей реализации по ссылке в первом комменте идентификаторы требований семантические - от общего к частному через точку.
Это даёт дополнительные возможности поиска и связи требований, ну и в принципе удобно.
P.S. MD - это Markdown, как верно отметили выше. Прошу прощения, что непонятно высказался. Думал, что в контексте Obsidian будет понятно.
Можете рассказать какую проблему решали, вводя описанную методику (технологию)?
Есть статистика по поводу того, насколько увеличились трудозатраты аналитика при документировании требований?
Рассказать о конкретном программном продукте не могу.
Проблема, решаемая предлагаемой методикой, в сложности трассировки кода в требования/требований в код при переходе от одной версии к другой версии продукта. То есть, при появлении новой версии требований проект должен, во-первых, иметь возможность ввести одного-двух новых программистов в курс дела за малый срок и, во-вторых, произвести импакт-анализ новых требований, чтобы оценить сроки и затраты.
И, конечно, потеря бойца не должна быть катастрофой.
Выделенного аналитика в проекте нет, т.к. проект относительно небольшой (порядка 500000 строк) и старый (кодовой базе порядка 10 лет).
А почему вообще должны увеличиться трудозатраты аналитика? В Obsidian так сложно писать требования?
Обсидиан здесь не при чем. Это обычный текстовый редактор.
С моей точки зрения сложность в таком подходе заключается в том , что сама методика "написана на бумаге" и пользователю необходимо самостоятельно производить кодирование требований, контролировать ссылки и т.п.
У меня было несколько аналогичных "подходов к снаряду" (к подобной теме). Рассматривался даже вариант разработки некого DSL, который бы позволил формализовать описание. Описание предполагалось производить с помощью "редактора кода", где можно было бы оперативно отслеживать связи и т.п. Ну те есть по сути "требования как код". Но идею до MVP не довели, не выделили ресурсы (исследования проводились в рамках проекта, у которого был внешний заказчик, ограниченные ограниченное время и т.п.)
Вот по этой причиной я и интересуюсь, насколько увеличились ТРЗ аналитика. Кстати на этот вопрос Вы так и не ответили.
Можно самостоятельно контролировать ссылки из кода в требования, а можно написать скриптик и, например, внедрить его в CI/CD сервера хранилища. Если есть висящие ссылки, то merge request не пройдёт.
Не говоря о том, что в ходе редактирования ссылки из кода в файл требования по относительному пути можно проверять непосредственно в IDE.
Но это если говорить о коде.
Если же говорить об отслеживании ссылок внутри самих требований вне кода, то с этим нет проблем в Obsidian, в нём есть средства и отслеживания висящих ссылок, и демонстрации backlinks, и обновления ссылок при переносе файлов.
Ну, не знаю я, насколько изменятся ТРЗ аналитика, т.к. выделенного аналитика у нас нет.
В чём проблема с кодированием требований, я не понимаю.
И да, не соглашусь, Обсидиан тут "при чём". Если бы Обсидиан был обычным редактором, типа M$ Word, то он был бы не нужен и его бы не было.
Спасибо за статью.
Идею вести документацию в проекте в Obsidian вроде лежит на поверхности, но мне в голову не приходила. Она насколько проста и изящна, что я в восторге.
Особенно в сочетании с тем, что инструкции для ИИ агентов сейчас тоже переходят в .md файлы.
Получается по этой системе можно сделать полное описание системы, которая будет служить и документацией, и инструкцией для ИИ.
В общем - огромное спасибо за идею. Пойду пробовать внедрять
Маленький вопрос в том, будет ли ИИ ссылаться на соответствующие файлы требований в своих выводах. Потому что за ИИ, как известно, нужен глаз да глаз, иначе начнёт бредить.
Будут проблемы -- пишите.
Когда его подключаешь как агента через CLI, ему можно задать файлы инструкций для контекста.
Поэтому если есть Основной файл с описанием системы, на каком языке пишем программу и прочее + файл текущей задачи.
Я имею ввиду подобный подход: https://youtu.be/CqL5kB8pOfo?si=qOHVPkR3itEgEBQs
Есть ли успехи и неудачи?
Был в отпуске 2 недели. Поэтому результатов не очень много.
Пробую на небольших кодовых базах, поэтому у меня нет версионирования задач и LLM хватает контекстного окна для всего проекта. И на таких задачах все показывает себя неплохо.
Из плюсов:
- В такой документации хранятся все ограничения, которые и мне напоминают обо всем и LLM их воспринимает хорошо
- LLM использует функции из фрейморков именно той версии, которая используется в проекте ( без документации, постоянно пытается применить функции из любой версии, которая есть в памяти )
Из минусов:
- Агенты работают на новых Node.js, и если проект старый и требует Node 14, то агенты не запускаются, приходится работать через unix
- Быстро теряешь контроль над кодовой базой. Это как проверять PR, всегда много упускается, что можно улучшить
- Агенты работают на новых Node.js, и если проект старый и требует Node 14, то агенты не запускаются, приходится работать через unix
Агенты ИИ? Ничего не могу сказать, т.к. никогда их не трогал и с Node не работал. Мой язык для таких вещей, т.е. для обработки данных, работы с текстом и прототипирования - Python.
- Быстро теряешь контроль над кодовой базой. Это как проверять PR, всегда много упускается, что можно улучшить
Мне кажется, что это в принципе особенность работы с LLM, а не специфика хранения требований вместе с кодом, использования Git, Obsidian и Markdown.
И да, если для документирования участка кода достаточно требования в комментарии, то ни к чему выносить это комментарий в отдельный маркдаун. Выносить имеет смысл только если это требование нужно где-то ещё, для какого-то другого читателя, кроме читающего код и сгенерированную по коду документацию html, например в документации пользователя или в методике тестирования.
Разработка требований к ПО с помощью Markdown, Git и Obsidian