FINAL TЗ — Superinstruction Site / Research First / Luna

1. Суть проекта

Создать сайт-инструкцию, который объясняет AI, как запускать новый проект правильно: не начинать сразу кодить, а сначала провести исследование, собрать большой проектный HTML-документ, накопить знания, проверить готовые блоки и только затем переходить к production-выполнению.

Ключевое изменение: предыдущие элементы вроде Coverage audit не должны доминировать на первом экране и не должны визуально запутывать AI. Они остаются в документе как рабочий раздел/раскрывающийся блок, но не как главный смысл интерфейса.

Основной пользовательский сценарий

01Пользователь описывает задачуДаёт AI ссылку на сайт-инструкцию и материалы проекта.

02AI строит первый большой HTMLСоздаёт START_PROJECT_*.html с roadmap, исследованиями и preliminary architecture.

03Пользователь размещает документ на сайтеЭтот HTML становится проектным knowledge-site.

04AI дорабатывает документИсследует блоки, ищет готовые решения, перестраивает план, фиксирует решения.

05Проект проходит research-gateПоявляется статус READY_FOR_VIBECODING.

06Luna начинает production-кодингЧитает уже сформированный проектный сайт и идёт по текущей задаче.

Что именно должен делать этот сайт-инструкция

Объяснять методологию.
Показывать порядок: исследование → проектирование → reuse → gate → код.

Давать AI правила игры.
Описывать формат ТЗ, структуру задач, правила проверки, ограничения и owner gates.

Задавать дизайн-язык.
Современный редакционный интерфейс, в котором видно, что это не блог, а система знаний.

14. Как домен связан с сервером

У проекта есть локальный сервер server2 с адресом 192.168.0.116. Для доступа из интернета используется постоянный внешний IP 79.120.12.88. Домен kastomprog.ru направлен на этот внешний IP, а маршрутизация и проброс HTTP/HTTPS приводят запрос на server2.

01Пользователь открывает доменБраузер запрашивает kastomprog.ru.

02DNS находит внешний IPA-запись домена указывает на 79.120.12.88.

03Запрос приходит на server2Внешний адрес маршрутизирует HTTP/HTTPS на 192.168.0.116.

04Nginx выбирает сайтДля server_name kastomprog.ru используется нужная web-папка.

Важное пояснение: проблема была не в отсутствии сервера или IP. Домен уже был связан с server2, а nginx уже обслуживал его из /mnt/ssd_projects/sites/kastomprog.ru/public. В этой папке просто находилась временная тестовая страница. Для публикации инструкции достаточно заменить index.html, проверить конфигурацию nginx и перезагрузить nginx.

Рабочая схема на будущее

kastomprog.ru ↓ DNS A-запись 79.120.12.88 (постоянный внешний IP) ↓ маршрутизация HTTP/HTTPS server2 — 192.168.0.116 ↓ nginx server_name /mnt/ssd_projects/sites/kastomprog.ru/public/index.html

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

RULE 01

Luna only

Основной агент реализации и проектирования: GPT-5.6 Luna / Medium. Переключения на Sol не требуются.

RULE 02

Task sizing

Если Luna не справляется, значит задача слишком крупная. Её надо дробить до посильного bounded-task формата.

RULE 03

Research First

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

RULE 04

One truth

Живое фактическое состояние проекта хранится в одном state layer, а не в разрозненных текстах, summary и чатах.

RULE 05

Model roles

GPT-5.6 Luna / Medium — основной вайбкодинг. Terra / High — текущий аудит и архитектурная проверка. Sol / High — дополнительный аудит по отдельному решению пользователя.

RULE 06

First response

В начале AI фиксирует user outcome, factual state, unknowns, research map и exact next action. Если задача слишком велика — сначала дробит её.

Обязательная стадия исследований

Что исследуем	Что нужно выяснить	Обязательный выход
Каждый существенный блок	Как его лучше реализовать, какие варианты есть, какие ограничения и риски.	Research card + решение ADOPT / ADAPT / PATTERN / BUILD / REJECT.
Готовые блоки на ПК пользователя	Есть ли уже подходящие куски кода, конфиги, пайплайны, модули, шаблоны, которые можно переиспользовать.	Local reuse catalog.
Готовые решения на Git	Есть ли зрелые готовые проекты, библиотеки, reference implementations и patterns.	Git reuse matrix.

До прохождения research-gate production-кодинг не начинается. Разрешены только discovery, spike, benchmark и documentation work.

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

Источники: каждое важное внешнее утверждение должно иметь ссылку, дату проверки и статус доверия. Если источник не найден, это явно фиксируется как unknown или NO_EXTERNAL_RESEARCH_NEEDED с объяснением.

3. Главный артефакт до кодинга

AI после первого обращения пользователя должна создать один основной HTML-документ:

START_PROJECT__.html

Он обязан содержать

Блоки проекта:
паспорт, user outcome, factual state, sources of truth, preliminary architecture, data flow, infrastructure facts, ограничения, риски, owner gates, phases, subplans, tasks, acceptance, verification, security, domain status.

Блоки исследовательской стадии:
research map, список обязательных исследований, локальный reuse audit plan, git reuse audit plan, unknowns, предварительные решения, plan-to-research, exact next research action.

Дальнейшая судьба этого HTML

Пользователь публикует его на сайте. AI затем многократно обновляет этот проектный сайт: дописывает исследования, меняет roadmap, фиксирует решения и постепенно формирует весь проект в текстовом виде. Только после этого начинается вайбкодинг.

4. Жизненный цикл проекта

AUser requestПользователь описывает задачу и даёт ссылку на этот сайт-инструкцию.

BFirst project specAI создаёт большой HTML со схемой проекта, исследованиями и дорожной картой.

CHosted project siteПользователь размещает HTML на сайте, чтобы AI могла от него отталкиваться.

DResearch iterationsAI исследует каждый блок, ищет reuse, проверяет гипотезы, обновляет план.

EReady for vibecodingПроект проходит gate и получает точную первую coding-task.

FLive projectПосле запуска runtime state переходит в /razraba, которая становится live projection проекта.

Gate READY_FOR_VIBECODING проходит только если

Показать checklist

конечный user outcome зафиксирован;
фактическое стартовое состояние исследовано;
каждый существенный блок имеет RESEARCH_PASS или аргументированный NO_EXTERNAL_RESEARCH_NEEDED;
local reuse audit выполнен;
git reuse audit выполнен;
ключевые dependency / license / maintenance / security вопросы проверены;
архитектура и data flow описаны на нужном уровне;
roadmap перестроен по результатам исследований;
ближайшие implementation-tasks раздроблены под Luna / Medium;
у задач есть acceptance + verification + rollback/risk.

5. Формат исследования по каждому блоку

Каждый значимый блок должен иметь research card. Это не заметка и не набор ссылок, а структурированное исследование.

research_id block_id title problem user_outcome questions[] constraints[] unknowns[] sources[] local_candidates[] git_candidates[] comparison_matrix[] spike benchmark decision = ADOPT / ADAPT / PATTERN / BUILD / REJECT chosen_approach why_chosen rejected_approaches[] risks[] affected_tasks[] status

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

6. Reuse audit обязателен

6.1. Исследование готовых блоков на ПК пользователя

До решения «писать это самим» AI должна проверить разрешённые project roots / рабочие каталоги / архивы и найти уже существующие модули, пайплайны, шаблоны, Docker-конфиги, ComfyUI workflows, API-код, парсеры, UI-компоненты и всё остальное, что можно использовать повторно.

6.2. Исследование готовых блоков на Git

AI должна отдельно проверить GitHub / GitLab / официальные репозитории / настроенные remotes. Не искать только по названию технологии, а искать по реальной функции блока.

Решение	Когда применять	Что означает
ADOPT	Готовый блок подходит почти напрямую	Берём решение с минимальной адаптацией.
ADAPT	Основа хорошая, но требует доработки	Переиспользуем, но меняем под проект.
PATTERN	Код брать не надо, но подход сильный	Используем идею/архитектуру, не копируя реализацию.
BUILD	Готовое решение хуже собственной реализации	Пишем сами, но только после доказанного исследования.
REJECT	Решение не подходит	Сохраняем reason и идём дальше.

7. Финальное визуальное направление

Дизайн должен опираться на сочетание редакционного / документационного интерфейса и геометрической абстракции. Не нужен «тяжёлый корпоративный портал». Нужен умный, собранный, визуально уверенный сайт, который выглядит как инструмент мышления.

Цвета
navy / beige / sand / orange-red / white. Основной текст — глубокий тёмно-синий, акценты — оранжево-красные.

Форма
крупные окружности, дуги, эллипсы, тонкие линии, геометрические пересечения, графические ноды.

Фактура
лёгкая бумажная фактура на фоне, но без шума, который мешает читать.

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

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

первый экран должен сразу говорить: Research First и объяснять суть, а не показывать вторичную таблицу;
Coverage audit убирать ниже и делать его сворачиваемым рабочим разделом;
навигация должна вести по большим смысловым блокам;
терминов должно быть много, но они должны быть организованы и легко обозримы.

8. Программные анимации — обязательно

Сайт должен быть живым. Анимации нужны именно программные: на CSS / JS, без тяжёлых видеовставок. Они не должны превращать сайт в шоу, а должны усиливать ощущение продуманной digital-системы.

Обязательные анимационные паттерны

Элемент	Что происходит	Техническая реализация
Hero geometric art	Очень лёгкое параллакс-движение слоёв при движении курсора.	requestAnimationFrame + transform translate3d / rotate, с маленькой амплитудой.
CTA buttons	Небольшой magnetic hover и мягкая тень.	mousemove + transform, fallback на обычный hover.
Cards / principle blocks	Карточки слегка поднимаются и меняют тень на hover.	CSS transition: transform, box-shadow, border-color.
Reveal on scroll	Секции и блоки плавно появляются снизу.	IntersectionObserver + class toggle.
Accordion sections	Раскрытие не дёргается, высота анимируется мягко.	JS height animation или CSS grid trick.
Top bar	При скролле получает более выраженную тень; может очень аккуратно прятаться/появляться.	scroll listener + throttling / requestAnimationFrame.
Search / nav / anchors	Мягкая подсветка активного состояния.	CSS state transitions.
Status / pulse indicators	Если есть live section, индикатор gently pulse.	CSS keyframes, без частого мигания.

Строгие ограничения анимаций

анимации не должны замедлять чтение и не должны постоянно отвлекать;
никаких тяжёлых canvas-симуляций ради красоты без причины;
обязательно поддерживать prefers-reduced-motion;
все hover-эффекты — сдержанные, точные, premium, а не «кричащие»;
scroll-анимации должны срабатывать один раз или очень мягко, без «дерготни».

Пример кодового направления для анимаций

1. IntersectionObserver → reveal classes. 2. requestAnimationFrame → hero parallax. 3. CSS transitions → cards / buttons / nav states. 4. Magnetic hover → only for primary CTA. 5. Sticky top bar state → scroll position based. 6. Reduced motion media query → disable transforms/keyframes.

9. Информационная архитектура сайта-инструкции

Hero
Что это за методология, зачем она нужна и почему сначала исследование.

Ключевые принципы
Luna only, one source of truth, research per block, reuse audit, /razraba later.

Как это работает
Жизненный цикл от user request до live project.

Артефакты
START_PROJECT HTML, research cards, reuse catalogs, decisions, spec lifecycle.

Правила ТЗ
Как именно AI должна писать полный проектный документ.

Анимации и дизайн
Отдельный раздел с визуальной системой и motion rules.

Что не должно мешать на первом экране

Не надо показывать огромную рабочую таблицу coverage audit, сложные технические JSON-блоки, raw coverage matrix и длинные журналы статусов в hero-зоне. Эти вещи существуют, но живут ниже, в раскрывающихся или вспомогательных секциях.

10. Что AI обязана писать в полном ТЗ проекта

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

- цель блока; - current behavior / required behavior; - inputs / outputs; - data flow; - sources of truth; - constraints; - dependencies; - scope / out-of-scope; - local reuse candidates; - git reuse candidates; - decision after research; - acceptance criteria; - verification; - rollback / risk; - security impact; - data impact; - exact next action.

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

11. Что происходит после начала реальной разработки

Когда исследовательская стадия завершена и Luna начинает production-кодинг, проектный knowledge-site не исчезает. Его логика продолжается в живом проекте через раздел /razraba.

В runtime-state должны попадать: phases, subplans, tasks, attempts, dead ends, blockers, decisions, owner gates, changes, evidence, health, domain status, current task, next action.

GET /api/dev/state?since= UI contract: - update at least every 5 seconds - no full page reload - preserve scroll position - preserve open sections - patch only changed fragments

12. Acceptance criteria для этого сайта

Показать критерии приёмки

сайт визуально объясняет методологию Research First;
в документе явно указано, что каждый блок требует исследования;
в документе явно указано, что нужно исследовать готовые блоки на ПК пользователя;
в документе явно указано, что нужно исследовать готовые решения на Git;
жизненный цикл «идея → проектный сайт → исследования → вайбкодинг» описан end-to-end;
есть требования к внешнему виду, типографике и motion-дизайну;
есть правила, как AI должна писать START_PROJECT HTML;
есть правила, как позже перейти к /razraba;
документ можно показать другой AI без дополнительного чата, и он остаётся понятным.

Out of scope для этой версии

не реализовывать реальный runtime /razraba внутри самого сайта-инструкции;
не строить сейчас систему логина/ролей;
не делать перегруженную CMS вокруг этой документации;
не переносить сюда реальные проектные данные других продуктов.

15. Exact next action

Следующий шаг: использовать этот HTML как финальное ТЗ для сборки сайта-инструкции. После публикации на домене показать его AI как «главный методологический сайт», от которого она будет отталкиваться, когда создаёт новый START_PROJECT_*.html для любого проекта.

То есть итоговая связка теперь такая: сайт-инструкция → проектный сайт → исследовательские итерации → ready for vibecoding → Luna code → /razraba.