Comments 37
Мне понравилось
Спасибо! А что-то конкретное понравилось или в целом подход?
В целом то, что заранее «и об этом подумай, и об этом не забудь», и плавно брюки превращаются в «товарищ, у нас тут для вас/LLM задан контекст проекта, причем глобально… это уже не условная ерундятина, just think».
Я про такое раньше думал, но это казалось очевидно-невероятным, потому что ну вроде да, все это нужно сделать ДО, но если этого не просят… А тут понятно, что таки надо, таки контекст для llm.
Из удобностей в плане "док о проекте" я придумал себе только вписывать в readme.md содержимое отдельного файла plan.md, и если план выполнен, то файл с ним можно переименовать/переместить, и для readme.md он «исчезает», и моя «документация по проекту» генерируется в html не запинаясь. Или где-то в тот же readme положить диаграмму если не модулей, то хотя бы этапов выполнения шагов в main.py, чтобы постоянно видеть, к чему надо придти в итоге и где я сейчас.
Я пришел из мира скриптов на bash, они в принципе монолитно-индивидуальные, «сделай все в одном файле», а сейчас привыкаю разносить шаги в тематические модули единого проекта, и окрепло ощущение необходимости поясняющей информации и в отдельных модулях, и более глобально, потому что постоянно переключаюсь между двумя уровнями восприятия проекта. Наверное, стоит и про vision подумать заранее.
На первых порах, думаю, многие обманывались в ожиданиях от ИИ. Дальше либо находили способы работы с ИИ, либо отвергали, либо просто откладывали до лучших времен
Контекст - это самое важное для ллм! Верно акцент расставили! Спасибо!
Справедливости ради, надо сказать, что и для человека контекст важен не меньше )
Да, пробуйте создавать мини тех проекты на подобии vision. Лучше потратить лишние 15 минут на объяснение LLM общей идеи, но зато сэкономить часы на этапах генерации кода далее )) Кстати опять же, как и с человеком )) Только у "человеков" есть возможность, а у многих и привычка, думать над дизайном в процессе работы над кодом - поэтому нам это сходит с рук местами.
Схему с plan не до конца понял, что значит "вписывать содержимое файла plan.md" (это какая-то директива для системы автогенерации документации)?
Да.
В файле readme.md есть строка
<!-- INSERT_PLAN_MD -->
Сборка документации по проекту через pdoc проходит так:
создаю файл /tmp/README.md,
в который вставляю содержимое оригинального readme.md,
а внутри него вместо строки <!-- INSERT_PLAN_MD --> вставляю содержимое файла plan.md.
ввва
Если файл plan.md отсутствует (удален или переименован), то вместо <!-- INSERT_PLAN_MD --> будет пустота, и сборку документации это не остановит.
Дальше выполняю сборку документации через "pdoc", который бегает по всем файлам и собирает описание модулей из докстрингов, и в браузере открывается html, на главной странице Readme и внутри него раздел «План работы» — он же список задач, он же отчет о том, какие из задач уже сделаны (расставляю смайлики в начале строки).
Когда всё доделаю, переименую файл plan.md в 1plan.md и раздел «План работы» в readme уже не будет отображаться.
Ну текст то можно было и ручками набрать
Ну или хотя бы, по примеру из текста, добавить в него нормальных правил, чтобы он выходил не таким рафинированно-штамповным
+1 от меня вам в карму
Для хеллоувордов сойдет, не более
Не соглашусь с Вами.
Действую по принципу описанному в статье.
Работаю на основном проекте и фриланс проекте.
Flow вполне рабочий, НО, для крупно-габаритных проектов, возможно, нужны улучшения.
ИМХО подход НЕ только для "холоу ворлдов"
А я работаю с решениями в несколько десятков(бавало даже сотен) проектов на разных языках(в основном С/C++, C#) и фреймворках, несколько таких решений написал и спроектировал сам, и есть у меня такое ощущение, что я буду дольше такую доку писать, чем сам проект, это без учета проверки и отладки того, что нагенерировалось, еще есть ощущение, что то, что нагенериться для онбординга будет полным мусором. Если вы думаете, что написать код ручками сложно - нет, не сложно, сложно его поддерживать, оптимизировать, расширять и делать понятным. У вас просто таких потребностей нет, так как пишете отдельные, небольшие, одноразовые проекты.
Мериться и спорить крупностью проектов не буду.
Но, говорить, что у меня проекты "маленькие и глупенькие", не стоит.
Я, как написал автор, "слона по кусочкам режу".
Иногда, проще самому написать код, а иногда лучше написать "доку", разбить ее на части, оперируя бизнес логикой, а дальше...ничем не отличается от ревью МРа джуна.
Так что, не знаю.
Все эти "поддерживать, оптимизировать и расширять" я понимаю и также придерживаюсь, НО, при этом, ничего не мешает писать код за счет AI, того же cursor.
Так что, скажу еще раз: "ИМХО, не только для `холоу ворлдов`" и чуть расширю мысль - такой подход закрывает часть задач, "СВОЕГО уровня" и такие задачи могут быть на ЛЮБОГО уровня и габарита проектов.
Резать и пилить у нас в стране все умеют, а что в итоге то? А в итоге вы получите ласкутное одеяло, вместо собранного из частей слона, которое разваливается на ходу. Плавали, знаем.
а иногда лучше написать "доку", разбить ее на части, оперируя бизнес логикой, а дальше...ничем не отличается от ревью МРа джуна.
Сомнительно, но окей. Тут две проблемы для большого проекта: либо описывай кучу функционала в больших задачах, либо кучу задач с маленьких функционалом. И там и там куча функционала, а значит и документации. И опять же, как это все потом будет вместе работать - не понятно. Весь проект у вас в мозги ИИ не влезет, отсюда еще одна проблема, кто вам эту портянку из документации валидировать будет, все ли там согласовано или нет. А с учетом галюнов, то на сколько эта валидация будет корректна. То, что автор указал в качестве архитектуры проекта - типичный хэлоуворд и только для такой архитектуры применим описанный в статье принцип разработки ПО, о чем и был первый мой комментарий.
Весь проект у вас в мозги ИИ не влезет, отсюда еще одна проблема
Это верно, конечно.
Но ведь если следовать low coupling, и всяким буквочкам типа S, I и D - зачем "всему" влезать в мозги?
Это и есть распиливание слона на запчасти - в итоге: куча документации и размывание общей картины в лучшем случае, в худшем - комок грязи (мы переварили слона, мы молодцы). Также стоит заметить, что этого слона нужно грамотно разделать, иначе будет очень неприятно его есть из-за горькой желчи, либо привкуса фикалий, а для этого нужно знать, что такое слон из чего он состоит
Конечно, нужно грамотно разделывать уметь.
Этого никто не отменяет. Пока ИИ за нас такие вещи решать не умеет. Все же ИИ это ассистент.
В одном из докладов разработчиков Антропик - они сказали, что уже дошли до этапа, когда они не проводят ревью кода, сгенеренного ИИ, но это пока только "листовые" куски кода - тот функционал, который не будет меняться в обозримом будущем.
Остальные вещи они у себя в Антропик, кстати решают, очень похожими методами, как описано в статье. Да, мы и сами всеми этими методами пользовались до появления ИИ.
А потом просто многие либо забыли, либо стало лень готовить и разжевывать для ИИ задачу. Не говоря, уже о том, что сильно упал порог входа, и многие без понимания основ и базовых практик SE начали вайбкодить. А по факту, грамотно используй, так как нужно тебе или твоей команде, отталкиваясь от ее уровня.
Такая бюрократия не всегда хорошо, так как много времени отнимает, то есть нужно нанимать промп-инженеров, которые по цене как разработчики, но только промт-инженеры. Опытному разработчику задача понятна по 2-3 предложениям из таска, на крайний случай 1 созвон на 5-10 мин. Будет ли такая задача понятна промт-инженеру для генерации нужного промта, сомневаюсь. В общем, тут много скользких моментов, а профита маловато, если вообще есть.
Мы применяем ИИ как на новых проектах, так и на масштабных легаси проектах с многолетней историей.
Конечно описанный подход, и сам ИИ, не серебряная пуля. В каждом проекте свои особенности, свои нюансы.
Но суть ведь подхода в том, что ИИ это не магия, и относиться к нему нужно, не как к магу, а как к человеку. У ИИ ограничен контекст и у человека ограничен, ИИ не выдаст сразу "конфетку", но и новый в проекте человек тоже не выдаст и т.д. и т.п.
Ну и этапы решения задачи в целом схожи, надо вначале разобрать задачу, подумать, спроектировать решение, построить план решения, учесть существующие соглашения, написать код и т.д. Каждый из этапов ИИ помогает сильно ускорить. Понятно, что для каждого профи точки ускорения будут отличаться.
Я правда не понял, Вы в принципе ИИ не применяете в проектах? Или у Вас какой-то другой способ применения? Можете рассказать?
LLM - это костыль, костыль может быть инструментом, но остается костылем.
У ИИ ограничен контекст и у человека ограничен, ИИ не выдаст сразу "конфетку", но и новый в проекте человек тоже не выдаст и т.д. и т.п.
Тут интересно. Новый человек может загрузить себе в мозг основной контекст и держать его, это сложно, но можно. То же самое можно сделать и с нейросетью. Не с LLM, а отдельной локальной специализированной неросетью, под конкретный проект, тогда ей уже можно давать задачи как обычному разработчику, без развернутой документации. Утверждать ничего не буду, еще не пробовал, все руки не доходят.
Для написания кода LLM не использую, так как не ощущаю никакого профита, для решения отдельных задач некоторые алгоритмы машинного обучения справляются неплохо, те же нейросети, но больше нравятся эволюционные вычисления. Как такового ИИ пока не существует в принципе. Его можно создать на основе экспертных систем, что позволит получать достоверные знания, а не гадать как LLM. Вообще, я за искуственный разум, а не интелект.
Нейросеть - это кухонный комбайн (если проводить аналогии). Он не может сделать хорошее блюдо, если повар не знает, как именно блюдо готовится, какие нужны ингредиенты и что из них на каком этапе закидывать в общий котёл. Но если повар шарит - этот комбайн в разы ускоряет работу.
Я сам, конечно, совсем не разработчик (аналитик данных), но с помощью той же нейросети за 4 вечера успешно сделал покерный калькулятор на C# (при том что ранее ни разу ничего не кодил на C#). Калькулятор с точным расчетом Equity и EV. С тепловой картой стартовых рук (которая меняет диапазоны, в зависимости от позиции игрока, есть ли ставка оппонента и соотношении ставки оппонента к банку). С рекомендациями по игре на разных улицах (учитывая количество оппонентов, размер банка и так далее). Считается это все за секунду при 100 тысячах симуляций по Монте-карло (через адаптированный алгоритм оценки руки от Кевина Саффекула). И немного GTO-логики при оценке действий под капотом (которую ещё нужно докручивать). Смог бы ли я сделать тоже самое без нейросети? Нет. А сколько времени бы занял такой небольшой проект у среднего программиста? Наверное неделю, может две. При этом, как уже отметили ранее, для нейросети КРАЙНЕ важен контекст и количество деталей. Мой первый запрос был подробно расписан на нескольких листах А4. И в дальнейшем никаких проблем с написанием кода не возникало.
Я рад за Ваши успехи, но контекст проектов, с которыми я работал и работаю, это сотни( тысячи) листов А4, которые изменяются и дописываются в отличие от правил покера, т.к. появляются новые хотелки, обновляются инструменты, изменяется законодательство, политическая и экономическая ситуация в мире и т.д. И еще один интересный вопрос : каким кухонным комбайном лучше обработать печень рыбы фугу и кто, если что, понесет ответственность? А также насколько критична скорость обработки?
Весь проект и в ваши мозги не влезет. А если влезет, то едва ли вы видели большие проекты. В любом случае, слишком много «у меня ощущение», зачем вообще спорить если вы даже не побывали по обе стороны и, соответственно, не понимаете, о чем говорите?
За статью спасибо. Очень близко, т.к. действую в той же "парадигме".
В некоторых "узких местах", добавляю псевдокод или оперирую техническими компонентами. Хз как объяснить, зачем именно так, чем это лучше простого написанич кода, кроме как: "я тян - пруфов не будет"
Интересно 👍 Не совсем понятно, как в случае с conventions.md сочетаются требования «не дублировать информацию из него» и «отразить все главные принципы разработки из документа @vision.md». Ведь без дублирования не обойтись: если изменится vision.md, придётся править и conventions.md. Может, тогда в vision.md оставить только принципы? Что там есть ещё, кроме принципов?
Спасибо.
Не совсем понятно, как в случае с
conventions.mdсочетаются требования «не дублировать информацию из него» и «отразить все главные принципы разработки из документа @vision.md»
Без этой инструкции бывало модель начинала переписывать весь vision.md
А нужно, чтобы основные принципы были внесены, а детали реализации остались в vision
если изменится
vision.md, придётся править иconventions.md
Да, верно, если изменится vision, то и conventions имеет смысл обновить.
Также в ходе развития проекта, корректировок модели, указания ей на ошибки и т.п. очень полезно просить модель учесть это и внести в соглашения. Поэтому соглашения живой документ.
Может, тогда в
vision.mdоставить только принципы? Что там есть ещё, кроме принципов?
В vision у нас по сути мини тех проект нашего решения. На мой взгляд, пусть он там и остается, а в соглашениях будут более общие вещи. В общий контекст пойдут оба файла. Но, если вы разделите эту информацию по-другому, и сократите "повторяемость", то это будет только лучше!
Когда хочешь, чтобы приложение не просто работало, а хорошо работало, то вайб-кодинг заканчивается.
А насколько это хорошо работает для задач, которые миллион раз ещё не кодили?
Например:
разработать генератор gcode для 3Д принтера с XY-core архитектурой на прошивке klipper, шестерен гиперболоидной зубчатой передачи, задаваемой передаточным отношением, расстоянием и углом между осями и минимальным модулем? Профиль зуба стандартный, эвольвентный. Допуски и точность печати игнорируем.
В случае невыполнения ограничений по контактной прочности для выбранного пластика выводить ошибку и предлагать варианты изменения геометрии, решающие проблему.
Задачки по геометрии ИИ решает плохо - известный факт.
Но в остальном, если подать в него доки с примерами, должен справляться, нет?
Я много раз проходил ситуацию, когда надо было работать со свежими инструментами, разработанными в 2025 году, и context7 с доками помогал ИИ переставать глючить и выдавать рабочий код с первого раза.
Хорошая и полезная статья. Спасибо за детальную информацию.
В процессе прочтения возникло ощущение, что я быстрее напишу проект руками, чем договорюсь по всем указанным пунктам с нейросетью. Особенно для задачи из примера - которую если исключить настройку докера - я как будто за пару часов решал.
Подход в целом хорош, но как показывает практика, чем больше инструкций, тем менее охотно LLM им следует. Зачастую она их просто игнорирует
Вся эта чипенгузня основывается на полном непонимании любой инжинерии гуманитариями. Гуманитария очень легко поймать за хвост найдя в тексте выражения типа "один раз генерим" и "сделали и забыли". Промпты гуманитария всегда рассчитаны на одноразовое использование. А все дело в том, что гуманитарий не понимает что делает и не желает понимать, более того часто и не может этого понимать - отсюда и мечта об одноразовости. Поэтому все это баловство жёстко ограничено мвп. И со временем ничего не изменится.
Умный вайб-кодинг или семь раз отмерь, один раз сгенерь