61 lines
8.6 KiB
Markdown
61 lines
8.6 KiB
Markdown
# AGENTS.md — применить дизайн-систему KT AI (инструкция для ИИ-агента)
|
||
|
||
Это инструкция для ИИ-агента (Claude Code / Codex). **Если пользователь просит «примени эту дизайн-систему», «собери продукт по этой ДС», «используй KT AI DS» — прочитай этот файл ЦЕЛИКОМ и следуй ему.** Папка этой ДС далее — `DS/` (папка, где лежит этот файл).
|
||
|
||
## Железное правило (Definition of Done)
|
||
Экран продукта НЕ готов, пока он:
|
||
1. построен на **ките/токенах KT AI** (не вёрстка с нуля);
|
||
2. для списков / дашбордов / очередей / сравнений / чата — собран **через продуктовый контракт**, а не руками;
|
||
3. прошёл **гейт**: `validate_product.py --strict` = `0/0` И проход по `DS/CHECKLIST.md` глазами.
|
||
|
||
«Зелёный валидатор» ≠ «готово». **Не объявляй экран готовым без прохода CHECKLIST.**
|
||
|
||
## ⚠️ Если в проекте УЖЕ есть экран/прототип (частая ошибка!)
|
||
**Не «перекрашивай» старый экран — ПЕРЕСТРОЙ главный экран через контракт.** Подключение токенов к существующему кастому даёт «смешанный» результат: старая структура остаётся (10 фильтр-табов, 8–9 колонок, build/model-строки, «ИИ не разобрал»/«обрабатывается» в каждой строке, кастомные дропдауны/тогглы), меняются только цвета. **Это НЕ применённая ДС — это перекраска.**
|
||
|
||
Правильно для главного экрана данных:
|
||
1. собери `config.json` по контракту (`DS/docs/PRODUCT_CONTRACT.md`) из реальных данных проекта;
|
||
2. отрендери `<KTAIShell><KTScreen contract={config}/></KTAIShell>`;
|
||
3. **удали старый компонент экрана** — не патчь его. Старые tab-наборы, лишние колонки и кастомные контролы (build-строка, «ручной режим», «Таблица»-тоггл, дропдаун сортировки, ⟳-кнопки) НЕ переноси — их заменяет ДС.
|
||
|
||
Не оставляй два «дизайна» рядом. Если экран не построен через контракт — он не прошёл п.2 Железного правила.
|
||
|
||
## Шаг 1 — прочитай канон (в этом порядке)
|
||
`DS/README.md` → `DS/docs/GOAL.md` → `DS/docs/PRINCIPLES.md` + `DS/docs/ELEVENLABS_DESIGN.md` (почему так) → `DS/docs/DESIGN.md` + `DS/COMPONENTS.md` (чем строить) → `DS/docs/PRODUCT_CONTRACT.md` + `DS/docs/ARCHETYPES.md` (контракт) → `DS/CHECKLIST.md` (гейт, по которому принимаешь).
|
||
|
||
## Шаг 2 — выбери РАНТАЙМ под стек проекта (ДС двухрантаймовая!)
|
||
Один контракт — два рантайма. **Сначала определи стек проекта, потом бери рантайм:**
|
||
|
||
- **React / Next.js / npm → React-кит** (`DS/templates/kt-ai-shadcn/`). Установка (см. `DS/templates/kt-ai-shadcn/PROTOTYPING_WORKFLOW.md`): из папки кита `python3 -m http.server 4188`, в проекте `npx shadcn@latest add http://127.0.0.1:4188/r/kt-ai-starter.json`. Даёт токены/тему, типы, `KTScreen`+`KTAIShell`, иконки. Рендер: `<KTAIShell><KTScreen contract={config}/></KTAIShell>`.
|
||
|
||
- **Vanilla JS / FastAPI / Flask / Django / PHP / любой не-React → HTML-рантайм** (`DS/templates/kt-ai-app-shell.html`). Это самодостаточный HTML/CSS/JS-app-shell, **гидрируется JSON-конфигом**: контракт кладётся в `<script id="kt-app-config" type="application/json">…</script>`, скрипт сам читает `CFG = JSON.parse(...)` и рендерит весь экран (очередь, KPI, drawer, темы). React/npm НЕ нужны.
|
||
- Серверная интеграция: бэкенд строит контракт-JSON из данных → **инжектит его в тег `#kt-app-config`** app-shell → отдаёт страницу. Логику инжекта можно взять из `DS/scripts/build_prototype.py` (он делает ровно это).
|
||
- CSS/спрайт/feedback.js инлайнятся в app-shell один раз (как делает `build_prototype.py`), дальше per-request меняется только конфиг.
|
||
|
||
В обоих случаях источник правды — один и тот же `config.json` по `DS/docs/PRODUCT_CONTRACT.md`.
|
||
|
||
## Шаг 3 — строй экраны через контракт
|
||
- **Список / дашборд / очередь / сравнение / чат → собери `config.json`** по `DS/docs/PRODUCT_CONTRACT.md` (+ `DS/product.schema.json`), выбери архетип по `DS/docs/ARCHETYPES.md`. Отрендери выбранным рантаймом (React `<KTScreen>` или HTML-инжект конфига). Структура, поведение и стиль приходят разом — не верстаешь руками.
|
||
- **Нестандартный экран → на компонентах/токенах** по `DS/docs/DESIGN.md` + `DS/COMPONENTS.md`.
|
||
|
||
## Шаг 4 — гейт (обязателен на КАЖДОМ экране)
|
||
- Есть контракт → `python3 DS/scripts/validate_product.py <config>.json --strict` → должно быть `0/0`.
|
||
- Всегда → пройди `DS/CHECKLIST.md` (G0–G8) глазами в обеих темах и на узком экране.
|
||
|
||
## Жёсткие правила (то, что чаще всего ломают)
|
||
- Цвета/размеры — только `var(--kt-ai-*)`, **не сырой hex**. Значения правятся в `DS/tokens.json`.
|
||
- **Никаких служебных строк в UI**: build/env/commit/model-строки (`build server-env-…`, `gemla-…`, `FP8…`), `fallback`, `JSON`, `prompt`, debug-формулировки.
|
||
- **Первичных фильтр-табов ≤ 4 + «Все»** (закон Хика). 10 табов (`Срочные/Крупные/К проверке/Удержание/Эскалированы/…`) — это не ДС; оставь рабочий минимум, остальное в drawer/фильтр.
|
||
- **Колонок мало и по делу** (обычно 5–6, не 8–9). **Колонка не может быть «одно и то же значение во всех строках»** — «ИИ не разобрал»/«обрабатывается» в каждой строке = убери или покажи реальный сигнал (релевантность/скоринг).
|
||
- **Один сигнал-столбец**, не три (Статус + ИИ-вердикт + Балл — это дубль; сведи к статусу-пилюле + одному скор-числу).
|
||
- **Даты** — `ДД.ММ.ГГГГ`, время `чч:мм`; не сырой ISO, без мусорных `00:00:00`/`09:00:00`.
|
||
- **Дубли строк** — дедуп. **Один primary** на экран. **Статус — пилюлей**, не цветом текста. **Create-кнопки** с ведущим «+».
|
||
- Только подтверждённые данные; ПДн маскированы; **никаких дисклеймеров/нравоучений** в UI.
|
||
- Один фильтрующий поиск на экран; AI-кнопка Төре — в топбаре у поиска.
|
||
|
||
## Чтобы применялось в КАЖДОЙ сессии автоматически
|
||
Добавь в `CLAUDE.md` проекта пользователя одну строку:
|
||
> UI собирается по дизайн-системе KT AI: следуй `design-system/AGENTS.md`. Экран не готов без `validate_product.py --strict` (0/0) и прохода `CHECKLIST.md`.
|
||
|
||
Тогда правила в контексте каждой сессии Claude Code, без напоминаний.
|