Обучение / Expert AI Layer

Expert AI Layer для разработки программного обеспечения

Короткий ответ

AI уже умеет писать функции, объяснять ошибки, генерировать тесты, проводить code review и предлагать архитектуру. Для многих разработчиков ChatGPT, Claude, Codex и другие coding assistants стали обычным рабочим инструментом.

Но чем сложнее проект, тем заметнее ограничение универсального AI: он знает программирование вообще, но не знает автоматически, как устроен именно ваш проект и почему он устроен именно так.

Он может знать JavaScript, Rust, C, Verilog или SQL. Но он не знает без дополнительного контекста:

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

Expert AI Layer для разработки ПО — это управляемый слой инженерного контекста между опытом разработчиков и AI. Он хранит не только документацию, но и принципы, методы, решения, исключения и границы, которые AI должен учитывать при работе с кодом.

Упрощённо:

Код + документация
        ↓
архитектурные правила
+ инварианты
+ решения и причины
+ исключения
+ инженерные методы
        ↓
Expert AI Layer
        ↓
ChatGPT / Claude / Codex / другой AI
        ↓
код, review, анализ или предложение

Почему одного AI coding assistant недостаточно

Coding assistant хорошо работает там, где задача определяется локальным кодом и общеизвестными практиками.

Например:

• написать функцию преобразования данных;
• объяснить stack trace;
• сгенерировать unit test;
• найти очевидную ошибку;
• предложить рефакторинг небольшого модуля.

Проблема начинается, когда правильность решения зависит от истории проекта.

AI видит функцию и предлагает убрать дополнительную проверку как избыточную. Но команда добавила её после конкретного production incident.

AI предлагает соединить два модуля напрямую. Но архитектура специально запрещает такую зависимость.

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

AI генерирует код, который компилируется. Но код нарушает системный инвариант.

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

Где на самом деле хранится инженерный опыт

В реальном software project знания распределены между множеством мест:

• исходным кодом;
• README;
• архитектурной документацией;
• ADR;
• issue tracker;
• pull requests;
• code review;
• postmortem;
• тестами;
• комментариями;
• чатами команды;
• устными объяснениями опытных разработчиков.

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

Репозиторий показывает что реализовано.

ADR может показать что решили и почему.

Postmortem показывает что сломалось.

Code review часто показывает какое правило команда фактически применяет.

Опытный разработчик знает когда из правила есть исключение.

Expert AI Layer связывает эти элементы в контекст, который можно применять повторно.

Что стоит сохранять в Expert AI Layer для разработки ПО

1. Архитектурные принципы

Это устойчивые ориентиры, действующие во многих задачах.

Например:

Не добавлять новый сервис, если проблема может быть решена внутри существующей границы модуля.

Или:

Восстановимость системы важнее локального выигрыша производительности.

Принцип не обязательно диктует конкретный код. Он задаёт направление инженерного решения.

2. Архитектурные инварианты

Инвариант — условие, которое должно сохраняться независимо от конкретной реализации.

Например:

У ресурса в каждый момент должен существовать только один владелец.

или:

Активный объект нельзя изменять до завершения handoff.

Для AI такие утверждения особенно важны: локально удобный рефакторинг может нарушить глобальный инвариант.

3. Решения и rationale

Недостаточно сохранить:

Используем вариант B.

Лучше сохранить:

Используем вариант B, потому что он сохраняет возможность обратной миграции и не вводит зависимость между модулями X и Y.

Причина позволяет AI понять, когда решение ещё действительно, а когда его можно пересмотреть.

4. Правила модулей и API

Например:

• кто имеет право вызывать интерфейс;
• какие зависимости разрешены;
• какой модуль является владельцем состояния;
• какие данные считаются immutable;
• какой формат является стабильным контрактом;
• какие изменения требуют миграции.

5. Методы разработки

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

Например, собственный метод изменения системного модуля может выглядеть так:

1. Определить затронутые инварианты.
2. Найти существующие решения и ограничения.
3. Проверить изменение интерфейсов.
4. Подготовить минимальную реализацию.
5. Добавить тесты на инварианты и исключения.
6. Провести review последствий.
7. Только затем объединять изменение.

Если AI знает этот метод, он помогает соблюдать процесс, а не только генерирует код.

6. Исключения

Общее правило часто выглядит просто до первого сложного кейса.

Например:

Обычно запрещена зависимость A → B.

Но реальная система может иметь подтверждённое исключение для bootstrapping или compatibility layer.

Исключение — это часто концентрат инженерного опыта, появившийся после реального ограничения или ошибки.

7. Известные ошибки и анти-паттерны

Полезно явно сохранять:

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

Тогда следующий AI-сеанс не начинает обсуждение с того же ошибочного варианта.

8. Границы AI

AI должен знать не только правила кода, но и границу полномочий.

Например:

AI может предложить изменение публичного интерфейса, но не должен считать его допустимым без анализа совместимости.

Или:

Если изменение затрагивает два архитектурных инварианта, требуется review разработчика до генерации финального patch.

Практический workflow: AI, который учится вместе с проектом

Хороший рабочий цикл выглядит так:

Новая задача
   ↓
Код + текущий контекст
   ↓
получение применимых правил, решений и инвариантов
   ↓
AI предлагает реализацию или анализ
   ↓
разработчик проверяет
   ↓
новое полезное решение / исключение / ошибка
   ↓
фиксируется в Expert AI Layer
   ↓
следующая задача начинается с накопленного уровня

Ключевой вопрос после важной задачи:

Что мы сегодня поняли такого, что AI должен знать в следующей похожей задаче?

Ответом может быть одно короткое правило, одно исключение или причина решения.

Именно это создаёт накопительный эффект.

Use case 1. Архитектурное проектирование

Обычный AI может предложить несколько архитектурных вариантов.

Expert AI Layer добавляет контекст:

• существующие границы модулей;
• запрещённые зависимости;
• требования совместимости;
• приоритеты команды;
• предыдущие решения;
• известные исключения.

Тогда вопрос меняется с:

Как лучше спроектировать этот компонент?

на:

Как лучше спроектировать этот компонент в рамках уже принятой архитектуры и её инвариантов?

Use case 2. Code review по правилам проекта

Generic code review обычно ищет:

• ошибки;
• сложность;
• дублирование;
• security-проблемы;
• style issues.

Но команда может иметь собственные дополнительные правила.

Например:

Проверить:
- не появился ли новый владелец состояния;
- не нарушена ли граница модуля;
- не создана ли скрытая зависимость;
- не изменился ли публичный контракт;
- покрыты ли известные исключения.

Так AI review становится частью инженерного процесса команды, а не просто внешним линтером с LLM.

Use case 3. Отладка и повторяющиеся ошибки

История debugging особенно хорошо превращается в Expert AI Layer.

После сложной ошибки можно сохранить:

Симптом
Причина
Как диагностировали
Какое первое предположение оказалось ошибочным
Какой тест подтвердил проблему
Как исправили
Когда решение не применять

Следующий похожий инцидент начинается уже не с общего поиска возможных причин.

AI получает историю реального инженерного опыта.

Use case 4. Разработка системного ПО

Системное ПО особенно чувствительно к скрытым ограничениям.

В tenant Sekura Noda есть реальные материалы по Sekura JS и Reganta OS.

Например, для Sekura JS зафиксирована модель модулей, где один .sjs файл описывает один модуль, а профиль модуля может определять его роль. Отдельные материалы фиксируют runtime layout и dispatch экспортируемых функций.

В Reganta OS зафиксирована архитектура без традиционной модели процессов: системные и пользовательские функции строятся вокруг модулей и собственных механизмов взаимодействия.

Для универсального AI это необычная архитектура.

Если дать ему только отдельный фрагмент кода, он легко может предложить привычное решение из Linux, POSIX или обычного application runtime — и тем самым противоречить самой архитектуре проекта.

Поэтому полезный контекст выглядит не так:

Вот исходный файл. Исправь функцию.

а так:

Вот исходный файл.
Вот архитектурные инварианты.
Вот модель модулей.
Вот действующие интерфейсные решения.
Вот запрещённые предположения.
Вот связанные исключения.
Теперь предложи минимальное изменение.

В этом и проявляется разница между AI, который знает программирование, и AI, который знает, как устроена именно эта система.

Use case 5. Онбординг разработчиков

Новый разработчик обычно читает документацию, код и постепенно задаёт вопросы более опытным коллегам.

Expert AI Layer может дать AI доступ к подтверждённым объяснениям команды:

• почему компонент устроен именно так;
• что нельзя менять без согласования;
• какие решения уже пробовали;
• какие термины имеют специальное значение;
• где лежат реальные границы ответственности.

Это не заменяет senior developer.

Но уменьшает количество вопросов, на которые команда уже отвечала десятки раз.

Use case 6. Работа AI-агентов с репозиторием

Когда AI только предлагает код, ошибку можно поймать на review.

Когда агент получает возможность:

• менять несколько файлов;
• запускать тесты;
• создавать migration;
• обновлять документацию;
• открывать pull request;

роль границ резко возрастает.

Перед действием агенту нужно понимать:

Что разрешено менять?
Какие инварианты проверить?
Какие тесты обязательны?
Какие изменения требуют человека?
Какие файлы или интерфейсы нельзя менять автоматически?

Инструменты дают агенту возможность действовать. Expert AI Layer задаёт профессиональную логику этих действий.

Expert AI Layer vs документация репозитория

Документация необходима, но решает другую задачу.

Они не конкурируют.

Документация является одним из источников слоя.

Expert AI Layer vs ADR

ADR — отличный механизм фиксации архитектурных решений.

Но Expert AI Layer шире.

Он может включать:

• ADR;
• отдельные инварианты;
• coding rules;
• методы review;
• исключения;
• lessons learned;
• решения из debugging;
• границы AI automation.

ADR может быть источником важного знания. Expert AI Layer делает это знание частью текущего контекста AI.

Expert AI Layer vs system prompt

Можно попытаться записать всё в один большой prompt.

На маленьком проекте это работает.

По мере роста появляются проблемы:

• prompt становится длинным;
• правила противоречат друг другу;
• трудно понять, что устарело;
• трудно связать правило с конкретным модулем;
• rejected решение остаётся рядом с accepted;
• одинаковый prompt отправляется даже в задачи, где большая часть правил не нужна.

Управляемый слой позволяет выбрать только применимый контекст.

Expert AI Layer vs RAG по документации

RAG помогает ответить:

Какие документы похожи на текущий запрос?

Для software engineering этого часто недостаточно.

AI ещё должен понимать:

• какое решение принято;
• какой документ superseded;
• какое правило имеет приоритет;
• где действует исключение;
• какой scope относится к текущему модулю.

Поэтому RAG может доставлять материал, а Expert AI Layer — управлять его профессиональным смыслом.

Как сохранять новое знание после code review

Не нужно сохранять весь pull request.

После содержательного review достаточно извлечь короткий вывод.

Например:

Плохо:

PR #314 — большое обсуждение на 47 сообщений.

Лучше:

Rule: модуль A не должен напрямую обращаться к состоянию B. Reason: B должен оставаться единственным владельцем состояния. Exception: диагностический read-only интерфейс. Scope: runtime modules версии 2+.

Такое знание легко применять в будущих изменениях.

Как использовать ошибки AI как источник улучшения

Один из самых дешёвых источников инженерного знания — ваши собственные исправления AI.

Если вы регулярно говорите:

• «нет, в нашем проекте это запрещено»;
• «этот интерфейс immutable»;
• «не создавай процесс — у нас другой runtime»;
• «этот модуль не владеет памятью»;
• «сначала проверь инвариант X»;

то эти исправления являются кандидатами на постоянный контекст.

Полезное правило:

Если вы второй раз исправляете AI одинаковым образом — вероятно, правило уже стоит сохранить отдельно.

Минимальный Expert AI Layer для одного репозитория

Начать можно без сложной инфраструктуры.

Соберите:

10 архитектурных правил

Что нельзя нарушать.

5 решений с причинами

Почему архитектура выбрана именно так.

3 метода

Например: изменение публичного API, расследование ошибки, review нового модуля.

5 известных исключений

Где общие правила работают иначе.

5 анти-паттернов

Что уже пробовали и не хотите повторять.

Границы AI

Что AI может делать самостоятельно, а что требует review.

Этого уже достаточно, чтобы AI начал работать заметно ближе к контексту вашего проекта.

Что не стоит сохранять

Не превращайте слой в копию Git.

Обычно не нужно отдельно сохранять:

• каждый commit;
• каждую строку кода;
• каждую переписку;
• все автоматически сгенерированные предложения AI;
• временные debug-гипотезы после закрытия задачи.

Сохраняйте то, что должно повлиять на будущую работу.

Частые ошибки

Ошибка 1. Считать репозиторий полной базой знаний

Код показывает реализацию, но часто не показывает причины.

Ошибка 2. Считать любой ADR вечным правилом

Архитектура меняется. Нужны статус и актуальность.

Ошибка 3. Сохранять только happy path

Самый ценный опыт часто находится в исключениях и failure modes.

Ошибка 4. Давать AI все документы без scope

Правило одного модуля может быть ошибочно применено к другому.

Ошибка 5. Позволять AI создавать собственные правила без review

AI может предложить draft. Accepted engineering rule должен оставаться управляемым решением.

Ошибка 6. Привязать опыт к одному coding assistant

AI-инструменты будут меняться. Архитектурный слой должен оставаться вашим.

Ошибка 7. Никогда не извлекать вывод после сложной задачи

Тогда AI ускоряет текущую работу, но не создаёт накопительного эффекта.

Как измерять пользу

Для начала не нужна сложная метрика.

Можно отслеживать:

• сколько повторных объяснений исчезло;
• сколько одинаковых ошибок AI перестало повторяться;
• сколько решений повторно используется;
• насколько быстрее проходит onboarding;
• сколько review-комментариев превратилось в устойчивые правила;
• сколько прошлых debugging lessons используется в новых инцидентах.

Главный показатель:

Начинается ли следующая задача с того уровня инженерного понимания, на котором закончилась предыдущая?

Почему это становится важнее по мере улучшения AI

Чем сильнее coding models, тем меньше преимуществ даёт сам доступ к ним.

Если один и тот же сильный AI доступен миллионам разработчиков, преимущество смещается в то, какой инженерный контекст получает модель.

Две команды могут использовать одинаковый AI.

Первая каждый день заново объясняет архитектуру.

Вторая после значимых решений сохраняет:

• один новый инвариант;
• одно исключение;
• одну причину решения;
• одну исправленную ошибку;
• одно улучшение метода.

Через неделю различие небольшое.

Через год вторая команда имеет накопленный инженерный слой, созданный из реальной разработки.

Его нельзя получить установкой нового coding assistant.

Часто задаваемые вопросы

Заменяет ли Expert AI Layer документацию?

Нет. Документация остаётся источником информации. Expert AI Layer добавляет управляемые правила, методы, решения, исключения и границы применения.

Нужен ли RAG?

Не обязательно для маленького проекта. При большом количестве материалов RAG или semantic search могут помочь находить релевантные источники. Но retrieval не заменяет статус, scope и инженерные правила.

Нужен ли fine-tuning coding model?

Обычно нет, если задача состоит в использовании меняющихся архитектурных знаний и решений. Такой контекст проще хранить отдельно от модели.

Можно ли использовать слой с разными AI?

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

Может ли AI автоматически создавать новые правила?

Он может предлагать draft на основе code review, debugging или обсуждения. Значимые архитектурные правила лучше подтверждать человеком.

Это только для больших команд?

Нет. Персональный разработчик тоже накапливает собственные методы, архитектурные решения и ошибки. Для solo developer такой слой может выполнять роль долговременной инженерной памяти.

С чего начать сегодня?

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

Связанные материалы

• Что такое Expert AI Layer
• Архитектура Expert AI Layer
• Как сохранить неявные знания для AI
• Expert AI Layer и AI-агенты
• Expert AI Layer и MCP

Следующий шаг

Не пытайтесь сразу описать всю инженерную организацию.

Начните с одного проекта и одной повторяющейся задачи — например, code review или изменения архитектуры.

Зафиксируйте:

1. применимые инварианты;
2. метод работы;
3. критерии хорошего решения;
4. известные исключения;
5. границы AI;
6. несколько прошлых решений с причинами.

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

Начните создавать свой Expert AI Layer

У всех разработчиков постепенно появятся сильные AI coding assistants.

Различие будет не только в модели.

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

Не просто используйте AI для написания кода. Начните создавать инженерный слой, который становится сильнее вместе с вашим проектом.

Начните создавать свой Expert AI Layer.

Начать создавать свой Expert AI Layer

Вернуться в Expert AI Layer