AgentOS

Что такое AgentOS

AgentOS — это не отдельный коммерческий продукт и не “операционная система” в техническом смысле. Это рабочее название слоя правил, документации, маршрутизации и проверки, который помогает использовать AI-агентов в сложном проекте без потери контроля.

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

AgentOS решает эту проблему через понятную последовательность: определить слой задачи, выбрать правильные source documents, ограничить work slice, выполнить изменение, проверить результат и зафиксировать handoff.

Почему это важно

В сложном интерфейсном проекте редко бывает задача “просто поправить экран”. Один и тот же симптом может иметь разные причины.

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

• неверным visual token;
• неправильным Product UI Kit primitive;
• ошибкой в Product Component;
• layout rule;
• runtime adapter;
• taxonomy contract;
• source data;
• устаревшей документацией;
• неправильным использованием компонента в конкретной page composition.

Если сразу править видимую карточку, можно исправить один экран и сломать системную логику. Поэтому первый вопрос в AgentOS — не “что поменять?”, а “какой слой задачи мы трогаем?”.

Documentation as operating layer

Главная часть AgentOS — документация. Не как архив после проекта, а как рабочий слой, который помогает принимать решения.

В системе важны несколько типов документов.

Repo-level docs

Описывают структуру проекта: приложения, пакеты, owner zones, hard stops, правила запуска, validation и границы, которые нельзя менять без отдельного решения.

Product-local docs

Фиксируют продуктовую модель: сущности, роли, сценарии, B2B/B2C boundaries, screen families, taxonomy, booking logic, account-side flows или другие доменные правила.

Design-system docs

Описывают компоненты, уровни дизайн-системы, states, variants, anatomy, usage rules, reference surfaces и component ownership.

Contracts

Нужны там, где нельзя каждый раз решать заново: что является фильтром, что бейджем, где начинается offer, как selected state попадает в BookingWidget, какие данные готовит adapter layer.

Validation docs

Помогают понять, какие проверки нужны для разных типов задач: docs-only, component change, runtime behavior, visual QA, architecture change, public copy.

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

Task routing

Task routing помогает не начинать работу с хаотичного поиска по проекту.

Задача сначала классифицируется по слою:

• product model;
• UX-flow;
• screen family;
• Product UI Kit;
• Product Component;
• Component Block;
• Page Layout;
• runtime adapter;
• source data;
• documentation;
• tooling;
• validation;
• visual QA.

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

Такой подход особенно полезен в проектах с несколькими приложениями, shared packages, design-system слоями, Live Demo, reference surfaces и public-safe материалами.

Source-of-truth context

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

Поэтому AgentOS использует принцип минимального достаточного контекста:

1. определить слой задачи;
2. выбрать нужные owner docs;
3. не читать весь проект без необходимости;
4. не использовать временные заметки как durable truth;
5. после принятия решения переносить его в правильный документ.

Так AI остаётся полезным инструментом анализа и сборки, но не начинает “изобретать продукт” заново.

Component boundaries

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

Например:

• primitive не должен знать бизнес-логику;
• Product Component не должен сам решать routing;
• Component Block не должен превращаться в page-local набор div;
• Page Layout не должен сам придумывать business rules;
• runtime adapter не должен становиться дизайн-системой;
• temporary workaround не должен попадать в component core.

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

Work slices

Изменения лучше делать небольшими проверяемыми slices.

Work slice должен иметь понятные границы:

• какой слой затронут;
• какие файлы меняются;
• какие документы являются source of truth;
• какие проверки нужны;
• что не входит в scope;
• где нужен human review.

Такой подход снижает риск каскадных изменений. Вместо “обновить всё сразу” задача превращается в конкретный участок работы: например, card family, filter behavior, component facade, visual state, docs cleanup или validation note.

Validation matrix

Не все задачи проверяются одинаково.

Docs-only изменение требует проверки связности, терминологии и source-of-truth. Component change требует проверки states, variants, API/props и reference surface. Runtime behavior требует typecheck, build, browser QA, responsive behavior и edge states. Visual change требует human visual QA.

Validation matrix помогает не запускать всё подряд, но и не закрывать задачу без нужных проверок.

Она также помогает честно фиксировать ограничения: что проверено, что не проверено, где остался риск и что нужно посмотреть вручную.

Handoff protocol

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

Хороший handoff отвечает на вопросы:

• что изменилось;
• зачем это было сделано;
• какой слой затронут;
• какие файлы или surfaces связаны;
• какие проверки выполнены;
• что не проверялось;
• какие ограничения остались;
• где нужен human review.

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

Где AI полезен

AI хорошо помогает в задачах, где есть понятный контекст и границы:

• анализ больших документов;
• поиск противоречий;
• инвентаризация компонентов;
• сравнение старой и новой структуры;
• подготовка вариантов текста;
• public-safe copy;
• рефакторинг в маленьких slices;
• обновление документации;
• поиск legacy-слоёв;
• подготовка QA notes;
• генерация demo data в рамках заданных контрактов.

В таких задачах AI ускоряет работу, но не заменяет продуктовую ответственность.

Где AI не должен принимать решение сам

AI не должен самостоятельно:

• менять продуктовую модель;
• решать, что является source of truth;
• раскрывать закрытые материалы;
• переносить workaround в дизайн-систему;
• менять component boundaries без задачи;
• принимать финальные UX-решения;
• утверждать публичные claims без проверки;
• закрывать visual QA без human review.

Это не недоверие к инструменту. Это нормальная граница ответственности: AI помогает анализировать и собирать, но качество продукта, UX-логика, публичные утверждения и финальное решение остаются за человеком.

Как появился этот подход

AgentOS вырос из практической работы над сложными public-safe проектами, где одновременно существовали продуктовая модель, дизайн-система в коде, Live Demo, reference surfaces, документация, AI-assisted задачи и ограничения публичной демонстрации.

Со временем этот слой стал повторяемой практикой: task routing, source docs, component boundaries, validation и handoff оказались полезны не только для одного проекта, а для разных сложных интерфейсных систем.

Смысл AgentOS не в том, чтобы добавить ещё один бюрократический уровень. Смысл в том, чтобы ускорять работу без потери структуры. Когда проект растёт, решения не должны оставаться только в чате, временном markdown или памяти одного человека.

Что даёт AgentOS

AgentOS помогает:

• быстрее входить в сложный проект;
• отделять source of truth от временных заметок;
• понимать, какой слой задачи нужно трогать;
• безопаснее использовать AI;
• удерживать component boundaries;
• снижать риск хаотичных локальных правок;
• фиксировать решения после acceptance;
• выбирать правильную validation;
• готовить понятный handoff;
• сохранять human review там, где он действительно нужен.

Для сложных B2B, B2C и enterprise-продуктов это особенно важно. Там недостаточно “сгенерировать экран” или быстро поправить CSS. Нужно удерживать продуктовую модель, документацию, дизайн-систему, runtime-поведение и качество реализации как единую рабочую среду.

Практическая основа и масштабируемость процесса

AgentOS — не теоретическая концепция и не отдельный продукт. Этот подход сформировался в реальной ежедневной работе над сложными интерфейсными системами, где одновременно развивались продуктовая логика, дизайн-система, документация, runtime-поверхности и AI-assisted задачи.

Слой документации, интерфейсные контракты, task routing, validation и handoff появились не как формальность, а как способ решать конкретные рабочие проблемы: сохранять контекст между задачами, не смешивать временные решения с source of truth, удерживать component boundaries и снижать риск хаотичных локальных правок.

Главное преимущество подхода — переносимость. Если убрать контекст конкретного продукта, остаётся рабочая модель управления процессом: задача получает слой, source docs задают проверенный контекст, изменения выполняются маленькими slices, результат проходит validation и закрывается human review.

Эту логику можно использовать в разных B2B, B2C и enterprise-продуктах — особенно там, где интерфейс связан с ролями, данными, состояниями, дизайн-системой, документацией и frontend-aware реализацией. AgentOS помогает быстрее двигаться с AI-ассистентами, но сохранять структуру, ответственность и качество решений.