Мой опыт онбординга разраба с амнезией

Давай признаем: ты чуть ли не 90% кода пишешь с помощью Claude, Codex или ещё какого-нибудь агента. Ты выпускаешь несколько MR-ов в день, пушишь несколько тысяч строк кода и быстро просматриваешь псевдокод на ревью, чтобы доказать самому себе, что это действительно ты напряг мозг ^[1] и сделал задачу. Ты делаешь ровно то же, что и всегда, думая, что агент просто ускоряет цикл разработки, который ты проходил ежедневно.

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

Давай разберёмся, что мы вообще делаем и зачем.

При получении новой задачи агент каждый раз проходит следующий цикл:

1. Получить задачу.

2. Понять архитектуру.

3. Найти нужные файлы.

4. Найти похожие примеры.

5. Внести изменения.

6. Запустить проверки.

7. Исправить ошибки ^[2].

Отсюда мы видим, что агент при постановке новой задачи каждый раз «насыщается» контекстом о проекте. У агента нет опыта ^[3] работы с вашим проектом: он не помнит архитектуру, не знает, в какую сторону вы двигаетесь. Он буквально каждый раз заново смотрит на ваш проект. Представьте нового разраба в команде с амнезией, который вечно проходит онбординг проекта. Следовательно, мы должны подогнать архитектуру нашего проекта для разработчика с отклонениями (AI-first).

Исторически хорошая архитектура оценивалась довольно стандартными критериями:

• поддерживаемость;

• расширяемость;

• повторное использование;

• модульность;

• тестируемость.

За месяцы корпения над задачами опытный разраб успевает выстроить какую-никакую карту проекта в голове. При постановке новой задачи мне не нужно изучать проект: я почти мгновенно прикидываю, куда, что и как нужно добавить. Агенты пока не умеют «накапливать» опыт из-за своей архитектуры, так как у них нет явной «пассивной» фазы мышления ^[4], но это вообще отдельная тема, поэтому пока забьём.

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

Harness Engineering

В начале 2026 года OpenAI представила концепцию Harness Engineering. Эта концепция изначально относится только к созданию агентов поверх LLM. Главный тезис, который она выражает: окружение, в котором работает LLM, гораздо сильнее влияет на результат, чем сама LLM. Однако этот подход активно начали экстраполировать на архитектуру разрабатываемых приложений.

Я выделил четыре свойства из Harness-методологии, которые добавил к современной архитектуре приложения:

• Navigability (очевидность навигации).

• Constrainability (ограниченность системы).

• Learnability (обучаемость).

• Verifiability (проверяемость).

Navigability (очевидность навигации)

Это свойство отвечает на вопрос: может ли агент быстро найти нужное место в проекте? Каждое неочевидное расположение какого-либо модуля для агента засоряет его контекст ненужной информацией.

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

Вариант: Component-Driven Architecture

components/
hooks/
services/
types/
utils/

Глядя на эту структуру, мы предполагаем, что, наверное, в components есть какое-то представление, условный CancelComponent, который использует хук useCancel, который использует сервис cancel, который использует тип cancel. И это ещё дай бог если однонаправленное распределение ответственности.

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

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

Пока наш агент будет составлять у себя в контекстном окне мапу вашего проекта под конкретно эту задачу, ему придётся прочитать и по пути добавить очень много лишнего. Буквально посмотреть дерево импортов, увидеть где-то нарушение однонаправленности или «мягкое» разделение зон ответственности. Агент, вероятно, предположит, что стоит также прочитать файлы, напрямую не относящиеся к задаче, но способные повлиять на её выполнение. Из-за этого мы буквально засоряем мусором контекстное окно.

Вариант: FSD

features/
    cancel-order/

Как только мы обозначили задачу, агент сразу по папке может предположить, что всё нужное находится внутри… и он будет прав. Даже если у нас FBD, то даже в таком случае агент отлично справится с поиском нужного контекста для выполнения задачи.

Именно поэтому feature-oriented-архитектуры сегодня выглядят значительно привлекательнее, чем несколько лет назад: не потому, что они моднее, а потому, что они уменьшают стоимость поиска контекста.

Важно понимать, что речь необязательно идёт о Feature-Sliced Design. Любая архитектура, которая локализует бизнесовую функциональность, обладает этим свойством. Отдельно напишу статью про сравнение FSD и Clean Architecture: там есть свои особенности при работе с агентом, и каждый из этих видов даёт свои преимущества.

Constrainability (ограниченность системы)

Это свойство нашей новой архитектуры должно помогать агенту отвечать на следующие вопросы:

• Что является публичным API?

• Что считается внутренней реализацией?

Для решения этих вопросов нам отлично поможет жёсткий ESLint. Чем больше ограничений, тем лучше. Нужно ограничить, какие слои могут импортировать какие слои. Жёстко ограничить, что условный /shared не может импортировать ничего извне, так как это наименьшая единица реализации, и так далее по зонам ответственности. Желательно перевести warn в error, чтобы активнее бить по рукам нашего крудошлёпа из Купертино.

Также стала ярко выраженной роль TypeScript и Zod для рантайма. На уровне AGENTS.md нужно вообще запретить декларировать тип any в любом проявлении, а при возможности обозначить union-типы, дабы максимально ограничить работу агента. Лучше иметь несколько похожих, но очень узких реализаций типов, нежели один общий.

Learnability (обучаемость)

Это свойство почти не обсуждается в традиционной архитектуре. Я пришёл к выводу, что при необходимости в каждой feature (напоминаю, что у нас в проекте используется FSD) нужно писать собственный AGENTS.md, где описан эталонный пример реализации в репозитории. Или же можно даже указать сторонние реализации в виде ссылки на репозиторий или просто отдельно взятые куски кода.

Также отлично работают тесты, так как после их прочтения мы явно понимаем ожидаемое поведение ^[6] от реализации того или иного компонента.

Также отлично работает Storybook.

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

Verifiability (проверяемость)

До появления агентов тесты воспринимались как инструмент контроля качества. Теперь они выполняют ещё одну функцию: становятся языком общения между репозиторием и агентом.

После каждого изменения агент задаёт системе один и тот же вопрос: всё ещё работает? Ответ должен быть максимально объективным.

TypeScript
↓
ESLint
↓
Unit Tests
↓
Integration Tests
↓
Playwright
↓
Build

Что с этим делать на практике?

Проверить свой файл AGENTS.md на актуальность описанной там архитектуры и стайлгайда. Далее описать, что ESLint должен жёстко ограничивать импорты. Затем добавить, что в проекте не должно быть никаких any, при возможности использовать union-типы, описать дизайн-систему и запретить создание новых дизайн-компонентов без прямого аппрува.

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

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

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

Литература

1. OpenAI. Harness engineering: Leveraging Codex in an agent-first world. https://openai.com/index/harness-engineering/ ^[7]

2. OpenAI. Unlocking the Codex Harness. https://openai.com/index/unlocking-the-codex-harness/ ^[8]

3. Martin Fowler. Harness Engineering for Coding Agent Users. https://martinfowler.com/articles/harness-engineering.html ^[9]

4. Martin Fowler. Context Engineering for Coding Agents. https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html ^[10]

5. Zhong, Zhu et al. AI Harness Engineering: A Runtime Substrate for Foundation-Model Software Agents. https://arxiv.org/abs/2605.13357 ^[11]

6. GitHub. Spec Kit. https://github.com/github/spec-kit ^[12]