Канонические инструкции проекта SKUARO для AI-агентов¶

Этот файл — главный постоянный набор правил для AI в проекте. Явные инструкции пользователя имеют приоритет. При неоднозначном или рискованном конфликте объясни его и запроси решение.

Паспорт проекта¶

Продукт: SKUARO — модульный SaaS и контур контроля клиентской работы для владельца малого бизнеса.
Этап: проектирование MVP и разработка прототипа.
Основной язык интерфейса и документации: русский.
Код и идентификаторы: английский; комментарии и технические материалы: русский.
Английская локализация предусмотрена позже.
Целевая production-архитектура и стек приняты; фактически реализованные части уточняются в docs/STATUS.md и docs/ARCHITECTURE.md.
Открытая самостоятельная регистрация разрешена; организация и membership владельца создаются только после подтверждения email по решению 0009.
STAGE функционально production-like: регистрация всегда открыта, Auth/email и Product-функции используют штатный путь без test-only bypass, mock-режима, заранее созданных тестовых аккаунтов или ограничений по имени среды.

SKUARO не имеет заранее закрытой функциональной границы. Он может включать CRM, коммуникационные, AI, операционные и другие возможности, если они нужны продукту. Ранние исследования и MVP определяют порядок работы, но не запрещают новые функции; новая функциональность по-прежнему классифицируется по модульной архитектуре.

Во всех DEV/STAGE test-контурах и на сайтах документации Basic Auth по умолчанию запрещён: тестовые адреса должны открываться без серверного логина. Basic Auth можно добавить только по новому прямому запросу владельца; собственная SKUARO Auth и backend permissions для защищённых Product-маршрутов сохраняются.

Команды управления¶

Отдельное сообщение START после завершённой настройки показывает краткий статус и не перезаписывает документы.
Отдельная команда ПРИМЕНИТЬ действует только для полной сводки со статусом ОЖИДАЕТ ПРИМЕНЕНИЯ; она не разрешает внешние действия или Git-операции.
Отдельная команда ИЗМЕНИТЬ ПРАВИЛА ПРОЕКТА запускает повторный опрос без удаления прежних решений.
Отдельная команда ПОДГОТОВИТЬ К ПРОДАКШНУ после ручного STAGE-тестирования запускает prompts/09-production-readiness.md: полный аудит, repair loop и независимый GO/NO-GO; она не разрешает фактический PROD deploy.
Отдельная команда закрываем сессию запускает prompts/06-close-session.md и разрешает безопасный commit и обычный push только в текущую согласованную ветку приватного origin.
Упоминание этих фраз внутри обычного текста не является командой.

Перед любой работой¶

Прочитай в таком порядке:

AGENTS.md.
docs/PROJECT_POLICY.md.
docs/PROJECT_CONTEXT.md.
docs/INTEGRATIONS.md, если задача затрагивает инструменты или восстановление.
docs/STATUS.md.
docs/ARCHITECTURE.md и docs/IMPLEMENTATION_PLAN.md, если задача затрагивает код, данные, инфраструктуру или deploy.
docs/DOCUMENTATION_STRATEGY.md, если задача затрагивает документацию или release notes.
Актуальные принятые решения в docs/decisions/.
docs/AGENT_WORKFLOW.md, если задача передаётся между агентами или принимается после выполнения.
docs/AGENT_ROLES.md, если задача использует subagents или меняет их профили/маршрутизацию.
docs/AGENT_MEMORY_AND_SKILLS.md и релевантные записи docs/agent-memory/, если задача повторяет прежнюю процедуру или меняет Skills.
Последний подходящий файл в logs/sessions/, если он нужен для задачи.
Git status, если Git инициализирован.

Если источники истины противоречат друг другу, останови затронутое действие, покажи противоречие и запроси решение.

Быстрая разработка и отдельная проверка¶

Обычный цикл DEV/STAGE: реализовать изменение, выполнить только технический минимум для запуска, сразу разместить текущий рабочий snapshot в STAGE, передать владельцу URL и исправлять по фактической UI/UX-проверке.
Не создавать task cards, evidence matrices, release hashes и не запускать tester/reviewer, полный check, security audit, backup/restore drill или повторные smoke автоматически для обычной итерации.
Дополнительные тесты сначала предложить владельцу или запустить по его прямой команде. Команда ПРОВЕРИТЬ включает отдельный verification-контур по docs/AGENT_WORKFLOW.md; команда ПОДГОТОВИТЬ К ПРОДАКШНУ включает полный production gate, включая security, данные, migrations, backup/restore и rollback.
STAGE является живой production-like площадкой ручной проверки, но остаётся отдельной средой и не означает готовность к PROD. Один минимальный smoke после deploy проверяет только факт запуска и URL.
Для обычной разрешённой Product-задачи последующий deploy её текущего snapshot в существующий STAGE-контур разрешён без повторного запроса, если владелец не сказал работать только локально. DEV, PROD, DNS, удаление и миграции этим не разрешаются.
Внешний UI/UX-агент создаёт reference artifacts, а не Product-код. Он получает одну текущую задачу из docs/ui-agent/TASK.md. До публикации developer-сайта агент изучает перечисленный в задаче снимок product-репозитория; после публикации использует полный developer-сайт. Result и предложенный MEMORY_DELTA сохраняются в docs/ui-agent/. Task state и принятую memory/ACCEPTED.md меняет только владелец или внутренний координатор.
По решению 0031 завершённый result UI/UX-агента автоматически принимается как точный визуальный reference без отдельного UI-аудита или verification gate. Цвета, размеры, компоновка, таблицы, UI-ассеты, логотипы, иконки и UI-скрипты переносятся в Product как есть. Обычный evidence gate 0022 продолжает действовать только для технической Product-реализации: маршрутов, данных, permissions, Auth/API contracts, сборки и runtime. Reference сам по себе не является deploy artifact.

Роли и делегирование¶

Project-scoped профили orchestrator, architect, frontend, backend, tester, reviewer хранятся в .codex/agents/; точные границы определены в docs/AGENT_ROLES.md и решении 0023.
В обычной DEV/STAGE-итерации основной агент работает напрямую без обязательных subagents. Профильные executor/verifier подключаются только по прямой команде, в отдельном verification-контуре или при подготовке к PROD.
Делегируй одну конкретную ограниченную задачу одному agent thread. Не передавай расплывчатое «сделать всё».
Параллелизуй прежде всего независимую read-heavy работу. Write-heavy задачи по умолчанию выполняются последовательно; параллельная запись допустима только для доказанно непересекающихся путей и критериев.
architect и reviewer работают read-only. tester в режиме verification не исправляет результат. frontend и backend не выходят за границы task card.
Профиль не расширяет sandbox или разрешения родителя. Модель и reasoning effort наследуются; обязательная модель для роли не закреплена.
Одновременно допускается не более трёх subagent-потоков помимо основного координатора.

Источники истины¶

Текущая работа и следующий шаг: docs/STATUS.md.
Стабильная цель и границы: docs/PROJECT_CONTEXT.md.
Действующие правила: этот файл и docs/PROJECT_POLICY.md.
Целевая техническая схема: docs/ARCHITECTURE.md.
Порядок внедрения и контрольные разрешения: docs/IMPLEMENTATION_PLAN.md.
Правила user/developer docs: docs/DOCUMENTATION_STRATEGY.md.
Причины существенных решений: docs/decisions/.
Фактическая история файлов: Git.
Повторяемый подтверждённый опыт: docs/agent-memory/; он не переопределяет канонические решения и текущий статус.
Session logs — история, а не текущее состояние.
Чат — временный контекст и не единственная память проекта.

Классификация новой разработки¶

До создания новой папки, пакета, сервиса или маршрута определи, к чему относится разработка: modules/, platform/, integrations/, packages/, apps/ или infra/.
Если классификация неоднозначна, до реализации обсуди с владельцем назначение, границы, зависимости, данные, permissions и точки интеграции.
Каждый продуктовый модуль живёт в modules/<module-id> и хранит свои frontend, backend, contracts, domain, module-specific database sources, worker, tests и связанную с кодом документацию внутри своей папки, если эти части фактически нужны.
Не создавай пустые каталоги будущих модулей. Новый modules/<module-id> появляется только после принятия его продуктовой границы.
apps/web, apps/api и apps/worker — точки запуска и композиции. Не накапливай в них бизнес-логику одного модуля.
platform/ хранит общие SaaS-возможности, integrations/ — адаптеры внешних систем, packages/ — общие технические пакеты, infra/ — deploy/runtime/backup.
Целевой platform/shell владеет общим каркасом защищённого приложения, а platform/home — роль- и capability-зависимым экраном /home; эти каталоги создаются только вместе с реализацией решения 0018.
modules/today остаётся продуктовым модулем /today, а не главным экраном. Продуктовый модуль не владеет глобальной навигацией, профилем или оболочкой приложения.
Все защищённые внутренние страницы используют общий AppShell и зоны S1–S3, P1–P6, O1–O3; Auth, публичный Site и Docs используют отдельные оболочки.
Внешняя система не становится продуктовым модулем автоматически: например, Telegram transport может быть интеграцией, а отдельный тарифный Telegram-сценарий — продуктовым модулем после отдельного решения.
Модули связываются только через публичные contracts, application services или события; прямые импорты внутренних repository и циклические зависимости запрещены.
Полные правила закреплены решением 0014 и docs/ARCHITECTURE.md.

Границы автономности¶

Работай только в открытом корне и его дочерних каталогах.
Не создавай дополнительную папку проекта внутри корня.
Чтение, анализ, изменения строго по задаче и безопасные проверки внутри проекта разрешены автономно.
Перед установкой или обновлением программ и зависимостей объясни назначение и последствия и получи подтверждение.
Не удаляй, не выполняй необратимую перезапись, не публикуй, не деплой, не отправляй данные третьим лицам и не меняй удалённые ресурсы без явного разрешения.
Не показывай и не записывай значения секретов, recovery codes, персональные, клиентские или платёжные данные.
Не копируй полный чат или полный вывод терминала в документы проекта.
В обычной итерации запускай только минимум для сборки/старта и один smoke URL; остальные проверки предлагай, но не запускай без отдельной команды.

Отложенные решения¶

Состав продукта функционально не ограничен ранним MVP или сценарием «Сегодня». Новые CRM, коммуникационные, AI и другие возможности добавляются по фактической необходимости с сохранением модульной классификации, данных и permissions.
Better Auth остаётся кандидатом до PoC; email- и AI-провайдеры, первая внешняя интеграция, точные RPO/RTO, бюджет и сроки не выбраны.
Отдельный реестр email неподтверждённых регистраций и письма о продолжении регистрации отложены до решения правил согласия, хранения, удаления, частоты отправки и защиты от злоупотреблений; не реализуй их заранее.
Обычные пользовательские аккаунты STAGE создаются через реальную открытую регистрацию и email verification; test-only аккаунты и bypass запрещены. Реальные клиентские бизнес-данные массово не переносятся в STAGE без отдельного решения.
Каноническая внешняя папка секретов: /Users/alexzandr/MEGA/____SECRETS.
Папка находится вне Git-проекта, но внутри дерева MEGA; владелец принял риск возможной синхронизации.
Не просматривай, не перечисляй и не открывай её содержимое без отдельной явной задачи. Никогда не выводи значения секретов.
Бюджет и сроки уточняются до расходов или обязательства по дате.

Отложенное решение блокирует только связанное действие. В записях различай ПОДТВЕРЖДЕНО ПОЛЬЗОВАТЕЛЕМ, ВЫВЕДЕНО ИЗ ПРОЕКТА, ПРИНЯТО ПО УМОЛЧАНИЮ, ОТЛОЖЕНО и ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ ПЕРЕД ДЕЙСТВИЕМ.

Skills, плагины и MCP¶

Repo-scoped Skill .agents/skills/task-verification используется только по отдельной команде проверки или перед PROD; обычная DEV/STAGE-итерация его не запускает.
Доступное, установленное или рекомендованное расширение не считается выбранной интеграцией проекта.
Реестр и восстановление выбранных расширений хранятся в docs/INTEGRATIONS.md.
Project Skills и безопасная проектная конфигурация сохраняются в Git только после выбора.
Установленное состояние, кэш, пользовательские и глобальные настройки, OAuth и авторизация через Git не переносятся.
Не создавай необязательные каталоги расширений заранее.
До новой или повторяемой задачи ищи подходящий Skill и релевантную запись опыта; не применяй устаревшее знание без сверки с кодом и источниками истины.
После задачи создавай запись опыта только для неочевидного повторяемого знания, подтверждённой ошибки, устойчивой процедуры или проверяемого улучшения. Не протоколируй каждое очевидное действие.
Перед новым Skill сравни цель, входы, выходы, область, permissions и риски с существующими Skills. При совпадающем контракте улучшай существующий Skill, не создавай дубликат.
Изменение памяти или Skill не расширяет разрешения текущей задачи. Migration, удаление, production, секреты и реальные данные по-прежнему требуют отдельного разрешения; независимый review выполняется в production/verification-контуре.
Полный жизненный цикл, статусы и формат записи определены в docs/AGENT_MEMORY_AND_SKILLS.md и решении 0021.

Документирование¶

docs/STATUS.md обновляется при завершении содержательной сессии.
Session log создаётся в формате YYYY-MM-DD-HHMM-краткая-тема.md.
Используй стандартный session log: запрос, результат, файлы, проверки, решения, риски и следующий шаг.
docs/CHANGELOG.md обновляется только при заметном пользователю изменении.
Решение создаётся только для существенного выбора архитектуры, инструмента, структуры, риска или политики.
Обычный отчёт DEV/STAGE короткий: что изменено, ссылка и что проверить вручную. Расширенный evidence/security/Git-отчёт используется только по команде ПРОВЕРИТЬ, при подготовке к PROD или если произошла ошибка/rollback.

Git и GitHub¶

Текущий product-репозиторий: приватный webuzateam/SkuAro-DEV.
Текущий origin: https://github.com/webuzateam/SkuAro-DEV.git.
Для экосистемы также согласованы отдельные приватные webuzateam/SkuAro-Site и webuzateam/SkuAro-Docs; они не создаются автоматически и не являются дочерними каталогами текущего корня.
DEV — разработка и основная рабочая ветка; STAGE — тестирование; PROD — production.
Сохраняй все значимые данные проекта; исключай секреты, системный мусор, подтверждённые кэши, сборки и воспроизводимые зависимости.
Не скрывай содержательные материалы через .gitignore.
Перед commit проверь staged-состав, содержимое на секреты и размеры новых или изменённых файлов.
Файл от 50 MiB требует решения пользователя до commit.
Не включай Git LFS, не сжимай, не переноси, не исключай и не удаляй крупный файл автоматически.
Не используй force push, не переписывай историю, не меняй origin и не создавай пустой commit.
STAGE принимает текущий рабочий snapshot для ручной UI/UX и функциональной проверки, включая незавершённую итерацию; это не является promotion в PROD.
Не трактуй STAGE как обязательный runtime-only артефакт. STAGE повторяет Product behavior, но сохраняет отдельные DB, sessions, credentials и данные; секреты не попадают в Git, а реальные клиентские бизнес-данные не копируются автоматически.
Обычный STAGE deploy может использовать текущий рабочий snapshot без merge, commit/hash gate и отдельного promotion-события. Merge DEV → STAGE остаётся Git-процессом, но не блокирует быстрый test-server deploy.
Команда закрываем сессию никогда не является триггером STAGE. Агент не создаёт PR, не выполняет merge и не активирует pipeline без отдельной явной задачи.

Хранилище секретов¶

Фактические секреты, ключи, логины и пароли хранятся вне проекта в /Users/alexzandr/MEGA/____SECRETS.
Значения не копируются в Git, проектные документы, session logs или чат.
В проекте фиксируются только безопасные имена, назначение, путь восстановления, владелец и статус.
Создание папки, изменение прав и работа с её содержимым требуют отдельного явного разрешения.
Рекомендуемые права при создании: 700 для каталогов и 600 для файлов.

Автоматическое закрытие¶

После отдельной команды закрываем сессию без повторного подтверждения разрешены документирование, применимые проверки, проверка секретов и размеров, commit и обычный push только в текущую согласованную ветку приватного origin, обычно DEV.

Команда не разрешает merge, PR, продвижение DEV → STAGE → PROD, deploy, публикацию, удаление, force push, смену remote, видимости или переписывание истории.

Остановись безопасно при подозрении на секрет, нерешённом крупном файле, публичном remote, конфликте, опасном расхождении истории, необходимости рискованного rebase, потере авторизации или отклонении GitHub.

Финальный отчёт задачи¶

Для обычной live STAGE-итерации сообщи только:

Что изменено.
Ссылку на STAGE.
Что владельцу проверить вручную.
Известное незавершённое поведение, если оно есть.

Полный отчёт с evidence, security, Git, рисками и rollback формируй только в отдельном verification/production-контуре или после фактической ошибки.