Документация или код: как перестать враждовать и начать жить в условиях договора

[discoverer-official]

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

[itGuevara]

Документация или код для Vibe Coding.

Хотел бы услышать советы как бороться с проблемой. Даешь детальные требования в issue для реализации функции. ИИ пишет, ты тестируешь, даешь замечания и т.п. 1,2,3, 4 и т.д.

Через неделю 55 -я функция также успешно реализуется, но вот 56-я затрагивает вторую и ИИ дорабатывает вторую функцию, но с потерей некоторых требований. Т.е. он переписывает, но берет только часть требований из issue, т.е. например, не помнит изначальные к функции 2 и последующие уточнения функции 2.

Может быть есть какие-то четкие правила, как избежать подобных проблем? Руками собирать требования сложно (сотни issue \ pull request) - видимо в каждый промт указывать ИИ: Веди актуальный список требований к каждой функции?

Однако часть требований, точнее особенностей реализации функции (часто во взаимосвязи нескольких функций), он сам добавляет при разработке, т.е. pull request к issue 2 также может содержать некоторые условия \ требования реализации функции 2, т.е. в промте к ИИ нужно как-то добавлять: Веди актуальный список требований к каждой функции с учетом их реализации, а особенности реализации функции добавляй в pull request и в список требований.

[Svetlana_Purik]

Онтологическая система - один из самых адекватных способов решить проблему забывчивости ИИ. По сути, это создание единой машиночитаемой карты знаний о проекте, где явно прописаны все сущности (функции, модули) и их связи. ИИ может запрашивать у этой карты контекст перед написанием кода.

С чего можно начать на практике:

1. Простой локальный вариант. Используйте бесплатный редактор Protégé, чтобы описать ваши ключевые функции и их зависимости. Затем скриптом на Python (с библиотекой OWLready2) можно спрашивать эту онтологию и вкладывать ответы в промты для ИИ. Это даст возможность быстро проверить концепцию.

2. Более серьезный подход. Разверните бесплатную версию GraphDB, загрузите туда онтологию и используйте её SPARQL-эндпоинт как внешний источник контекста для ИИ. Это уже промышленное решение.

Главные критерии выбора инструмента:

- Наличие удобного API (REST или SPARQL), чтобы его мог опрашивать ваш ИИ-пайплайн.

- Возможность визуализации связей (графов) - это критично для валидации модели людьми.

- Поддержка логического вывода (reasoning), который может автоматически находить противоречия или скрытые зависимости.

Основная сложность - не в установке софта, а в экспертизе построения хорошей онтологии (как правильно выделять сущности и связи) и в интеграции этого шага в ваш процесс разработки, чтобы модель обновлялась автоматически.

Стоит начать с малого - смоделировать один самый проблемный сервис.

[itGuevara]

К твоему пункту 1 - я примерно так и делаю, вставляя в промты ссылку на файл и указанием: Используй при разработке кода. Там ссылки на две онтологии.

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

[DMS_13]

А вы о подходе documentation first знаете?

А о командах, где есть системные аналитики( не бизнес аналитики)?

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

[Svetlana_Purik]

Для госзаказа и разработки критичных систем это базовый, обязательный и допустимый уровень зрелости с самого начала.