diff --git a/README.md b/README.md index dc3cb8f..052e536 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Agent Engineering Kit -Agent Engineering Kit gives AI coding agents a compact, versioned set of engineering rules for working in real repositories. It helps agents preserve task scope, use evidence, respect project boundaries, and choose checks that observe the intended result. +Agent Engineering Kit reduces repeated setup and explanations when starting and developing software projects. It combines a project bootstrap, optional tested configurations, and compact, versioned engineering rules to keep code, design and project context consistent. Connect the kit once, then keep working in your project as usual. The agent reads only the rules relevant to the current task. @@ -50,15 +50,15 @@ If internal files are already tracked, preview the transition and install local These commands preserve the index, history and local files. They provide a separate instruction for untracking runtime files after saving unique rules and obtaining the owner's permission. Previously published files remain in old commits. See [private context and restoration](sync/README.md#публичный-проект-и-private-project-context) for setup and migration details. -For a new product, start with a small architecture before implementing its first scenario: +For a new project, start directly with its idea, first scenario and constraints: ```powershell .\ai-rules.ps1 prompt bootstrap -ProjectRoot C:\path\to\project ``` -Paste the prompt with your goal and first scenario. The agent chooses where code belongs, creates only the needed parts, and checks the important dependency boundaries. Connecting an existing project does not restructure its code. +The agent chooses an appropriate scale and technology, explains important choices, and shows a plan for your approval. It then builds the first complete scenario, applies only useful checks and settings, and leaves short instructions for continuing. Connecting the kit can be part of this plan; a separate connection interview is unnecessary. A lasting utility can remain three files. An application, service, mobile product, game or library can use its native conventions even without a kit example. Connecting an existing project does not restructure its code. -For substantial new UI or a visual redesign, ask the agent to choose a visual direction before implementation: product context, references, distinct options, then a short design contract. Small fixes and features within an established design system do not restart discovery; connecting the kit does not redesign existing projects. +For substantial new UI or a visual redesign, choose a composition for the audience and main scenario, then keep a short visual contract. References and alternatives help when the choice is uncertain; there are no quotas or universal visual styles. Small fixes and features within an established design system do not restart discovery; connecting the kit does not redesign existing projects. For a deep project audit later, generate a dedicated prompt: @@ -72,7 +72,7 @@ To learn how a project works through code walkthroughs and practical checks: .\ai-rules.ps1 prompt study -ProjectRoot C:\path\to\project ``` -Study sessions track explored areas and demonstrated understanding separately. Significant decisions are maintained as a regular project practice, with a short, readable map of current choices and their reasons. Temporary audits, research and delivery evidence live separately and are reviewed when the work ends. +Study sessions track explored areas and demonstrated understanding separately. Keep significant decisions and their reasons in one existing place; separate maps and ADRs are optional. Temporary audits, research and delivery evidence live separately and are reviewed when the work ends. For a large task with independent parts, generate a prompt for Codex: @@ -96,7 +96,7 @@ If they look correct, apply them: .\ai-rules.ps1 update -ProjectRoot C:\path\to\project -Apply ``` -Initial `connect` and `init` create the local setup, including public-profile exclusions. Rule updates require `-Apply`; the kit preserves manually changed rules and does not run `commit`, `push`, or publishing commands. +Initial `connect` and `init` create the local setup, including public-profile exclusions. Optional [technical materials](templates/README.md#технические-материалы) provide starting configurations for Vue/Vite and a Node service; they are not full application templates, and rule updates never apply them to project code. Rule updates require `-Apply`; the kit preserves manually changed rules and does not run `commit`, `push`, or publishing commands. ## Kit development diff --git a/ai-rules.ps1 b/ai-rules.ps1 index 7786d87..89aa7f5 100644 --- a/ai-rules.ps1 +++ b/ai-rules.ps1 @@ -71,7 +71,7 @@ Agent Engineering Kit prompt parallel -ProjectRoot ПУТЬ Подготовить запрос для параллельной задачи. prompt bootstrap -ProjectRoot ПУТЬ - Выбрать первоначальную архитектуру нового проекта. + Подготовить основу и первый работающий сценарий проекта. connect -ProjectRoot ПУТЬ Подготовить проект и показать изменения. connect -ProjectRoot ПУТЬ -Apply diff --git a/hub/ARCHITECTURE.md b/hub/ARCHITECTURE.md index 840f7d6..46a940c 100644 --- a/hub/ARCHITECTURE.md +++ b/hub/ARCHITECTURE.md @@ -2,7 +2,7 @@ ## Целевой результат -Целевой проект должен получить короткую локальную точку входа и читать только тот набор правил, который относится к его типу и текущей задаче. +Целевой проект получает подходящую работающую основу, проверенные настройки по необходимости и короткий контекст для продолжения. Kit сохраняет инженерный опыт между проектами, не выбирая одну архитектуру или технологию для всех. Подключённый агент читает только правила текущей задачи. ```text запрос владельца и указанный контекст задачи @@ -54,15 +54,15 @@ ### `templates/` -Стартовые формы локальных документов. Незаполненное место не является значением по умолчанию, а комментарий шаблона — нормативным правилом. +Стартовые формы локальных документов и узкие [технические материалы](../templates/README.md#технические-материалы). Незаполненное место не является значением по умолчанию, а пример — нормативным правилом. Материал имеет условия применения, версии и проверку; агент применяет подходящую часть или отказывается от неё. После применения настройки принадлежат проекту, обычная синхронизация их не копирует и не обновляет. Совместимые материалы доступны из checkout хаба; shared-выпуск включает канонические templates, но также не применяет их к проекту. ### `workflows/` Инструкции для ограниченного процесса: подключения, первичного аудита или учебного изучения проекта. Workflow применяется только по явной команде или выбранному совместимому идентификатору и не становится нормой для всех задач проекта. -Первоначальный выбор обязан состояться по `ARCHITECTURE_AND_DATA.md` до существенной реализации новой развиваемой области. Всегда читаемый `standard-product`, тема реализации и `INDEX` ведут к этому условию; локальный контракт затем определяет место нового кода. [`PROJECT_BOOTSTRAP.md`](../workflows/PROJECT_BOOTSTRAP.md) содержит только стартовый процесс, три архетипа и запрос `prompt bootstrap` в одном файле. `project-bootstrap` выбирается явно и не входит в композицию профилей. Подключение нового проекта предлагает следующий шаг, существующего — фиксирует разрыв без реализации или рефакторинга. Если процесс не установлен, краткий контракт архитектурного правила остаётся достаточным для первоначального выбора. +Первоначальный выбор масштаба задаёт [ARCHITECTURE_AND_DATA](../rules/ARCHITECTURE_AND_DATA.md#первоначальная-архитектура). `standard-product`, тема реализации и `INDEX` ведут к нему до существенного нового кода. [PROJECT_BOOTSTRAP](../workflows/PROJECT_BOOTSTRAP.md) ведёт от первого сценария и одобренной основы к работающему результату. Он допускает любые технологии, компактные долговечные инструменты и отказ от примеров Kit. Отдельный запуск подключения не требуется, если оно уже входит в одобренный план bootstrap. Само подключение существующего проекта не меняет его архитектуру. -Визуальный выбор до существенного нового UI или редизайна задаёт [PRODUCT](../rules/PRODUCT.md#визуальное-направление-до-реализации); `standard-product`, `IMPLEMENTATION` и metadata `INDEX` ведут к нему до кода. [VISUAL_DESIGN_DISCOVERY](../workflows/VISUAL_DESIGN_DISCOVERY.md) содержит подробный процесс и читается только по подходящей задаче, из хаба либо явно выбранной копии `visual-design-discovery`. Профили его не устанавливают; без workflow действует компактный минимум продуктового правила. [QUALITY](../rules/QUALITY.md#проверка-интерфейса) владеет приёмкой направления и антишаблонной проверкой. Это предотвращает выбор привычной композиции без основания, сохраняя существующие системы и границы малых задач. Цена — исследование и сравнение до кода; эффект на дизайн остаётся гипотезой до поведенческих evals. Объём процесса пересматривается при задержках без пользы или смене модели; равноценный более простой путь — основание заменить процесс после сравнения. +Визуальный выбор задаёт [PRODUCT](../rules/PRODUCT.md#визуальное-направление-до-реализации). Минимум — обоснованная композиция и короткий контракт; [VISUAL_DESIGN_DISCOVERY](../workflows/VISUAL_DESIGN_DISCOVERY.md) помогает только при необходимом исследовании или сравнении. Квот референсов и вариантов нет, продукты без графического интерфейса пропускают процесс. [QUALITY](../rules/QUALITY.md#проверка-интерфейса) владеет приёмкой. При продолжении используются действующие компоненты и токены. ### `sync/` и управляемая копия diff --git a/hub/PROJECT_RULES.md b/hub/PROJECT_RULES.md index a77549a..bb4b777 100644 --- a/hub/PROJECT_RULES.md +++ b/hub/PROJECT_RULES.md @@ -2,7 +2,9 @@ ## Назначение -Хаб хранит проверенный, переносимый каркас правил для новых и существующих проектов. Его результат — не максимальное число инструкций, а небольшой непротиворечивый набор, который можно осознанно подключить, проверить и локально уточнить. +Agent Engineering Kit сокращает повторяющуюся работу при создании и развитии программных проектов: помогает выбрать подходящую основу, применить проверенные настройки и сохранить особенности проекта между сессиями. Последовательность архитектуры, кода, дизайна и документации остаётся практической целью; обучение модели общему программированию не является назначением Kit. + +Общие принципы независимы от стека. Готовые материалы применяются избирательно: небольшая долговечная утилита может остаться несколькими файлами, а сервис с независимыми интеграциями и риском повторных эффектов получает необходимые границы. Отсутствие примера для мобильной платформы, игры, обработки данных или другой технологии нормально. Агент использует принятые средства этой технологии и объясняет отказ от неподходящего материала Kit. Этот репозиторий публичный. Для любых изменений, публикации и внешнего взаимодействия обязателен профиль [`../profiles/public-repository.md`](../profiles/public-repository.md) вместе с подключаемыми им тематическими правилами. @@ -22,6 +24,8 @@ Если правило подтверждено одним доменом и несёт его терминологию, оно остаётся профилем либо проектным примером. Базовый набор не растёт из единичного предпочтения. +Перед добавлением инструкции проверь, не экономнее ли готовая конфигурация, команда, проверка или уже существующий инструмент. Для технического материала нужны область применения, совместимые версии, проверяемый пример, ограничения и цена обновления. Не копируй каркас выпущенного приложения целиком. Пример не устанавливается автоматически, а после применения его конфигурация принадлежит проекту. + ## Нормативная граница Нормативны только: diff --git a/profiles/standard-product.md b/profiles/standard-product.md index 7030868..e472393 100644 --- a/profiles/standard-product.md +++ b/profiles/standard-product.md @@ -2,7 +2,7 @@ ## Назначение -Для приложения или сервиса, который регулярно доставляет пользовательский либо операционный результат. Состав тем — в `sync/catalog.json` и manifest проекта. +Для программного продукта, который регулярно доставляет пользовательский либо операционный результат: приложения, сервиса, игры, инструмента или пакета. Профиль не выбирает стек, каталоги, UI, CI или развёртывание. Состав тем — в `sync/catalog.json` и manifest проекта. ## Уникальные обязательства diff --git a/rules/AI_COLLABORATION.md b/rules/AI_COLLABORATION.md index 0585365..c5891e1 100644 --- a/rules/AI_COLLABORATION.md +++ b/rules/AI_COLLABORATION.md @@ -4,7 +4,7 @@ В начале значимой задачи сделай явными ожидаемый результат, границы полномочий и степень самостоятельности. Если критерий готовности не задан, предложи наблюдаемый результат и способ проверки до изменений. Когда запрос уже однозначен, кратко подтверди понимание и продолжай без повторного согласования. -До значимого выбора найди карту решений затронутой области и примени раздел «Карта значимых решений» в `DOCUMENTATION.md`. Это постоянная практика проекта, а не только часть учебного режима; отсутствие карты не разрешает приписывать владельцу решения или причины. +Контекст решений и минимальная передача незавершённой работы — по [DOCUMENTATION](DOCUMENTATION.md). Отсутствие карты не разрешает приписывать владельцу решения или причины. Помощь адаптируется к риску, опыту владельца и цели: @@ -50,17 +50,6 @@ Если владелец выбрал журнал проблем, локальные правила указывают один канонический файл и маршрут к нему. До связанной работы читай только релевантные записи; существенную новую проблему и результат её проверки сохраняй до итоговой передачи. Повтор того же механизма обновляет прежний ID. Неизвестные причины, доступный агенту контекст и применённая версия не восстанавливаются догадкой. Исправление продукта и проверка пользы меры Kit имеют разные статусы. Шаблон `templates/DEVELOPMENT_ERRORS.md` находится в checkout хаба, отдельно от управляемого снимка проекта; он помогает начать документ, но не вводит журнал во все проекты автоматически. -## Сводка для продолжения - -Если работа прерывается или передаётся, сохрани только полезное продолжению: - -- цель и текущие границы задачи; -- подтверждённые решения и основания; -- изменённые области и состояние проверок; -- неизвестное, риск и следующий шаг. - -Сводка не заменяет каноническую документацию и не содержит лишний внутренний контекст. - ## Исключения Тривиальная одношаговая задача не требует формального согласования режима или сводки. Ограничения полномочий и честность результата действуют всегда. diff --git a/rules/ARCHITECTURE_AND_DATA.md b/rules/ARCHITECTURE_AND_DATA.md index 4da465c..b14d8df 100644 --- a/rules/ARCHITECTURE_AND_DATA.md +++ b/rules/ARCHITECTURE_AND_DATA.md @@ -11,14 +11,14 @@ - Для существенных модулей назови допустимое направление зависимостей, разрешённые точки входа и запрещённые связи. Например: `UI → прикладной сервис → репозиторий`; конкретная схема зависит от проекта. - Архитектурное правило должно ограничивать наблюдаемый риск, а не предписывать каждую деталь реализации. Внутри проверяемых границ сохраняй свободу выбора решения. -- В развиваемом проекте после выбора устойчивых границ агент обязан закрепить наиболее важные разрешённые и запрещённые связи линтером, анализатором зависимостей или структурным тестом до завершения первого сквозного сценария. Используй существующий инструмент либо небольшой локальный скрипт; тяжёлая зависимость без необходимости не нужна. Сообщение проверки объясняет нарушенную границу и способ исправления. +- Если нарушение устойчивой границы создаёт значимый риск для данных, независимого тестирования или изменений нескольких модулей, либо уже повторяется архитектурный дрейф, закрепи важнейшие связи линтером, анализатором зависимостей или структурным тестом. Используй существующий инструмент; тяжёлая зависимость без необходимости не нужна. Сообщение проверки объясняет нарушенную границу. Сам факт длительной разработки не требует guard: нескольким связным файлам без такой границы достаточно прямой проверки поведения. - Проверка должна наблюдать реальные пути зависимостей проекта, включая используемые алиасы, реэкспорты и статические динамические импорты. Докажи, что разрешённый случай проходит, а представительное нарушение отклоняется; проверка пустого каталога не защищает границу. Назови команду и место запуска в обычном наборе проверок; CI подключай в пределах задачи. Если автоматизация недоступна, запиши конкретное ограничение и следующую проверку, но не объявляй границу механически защищённой. - Не автоматизируй непроверенное предпочтение. Если один и тот же архитектурный дрейф повторяется, устраняй не только частный случай: уточни правило, проверку или обратную связь, которые предотвращают повторение. ## Организация кода и импортов - Модуль, компонент и каталог группируются по связной ответственности и причинам совместного изменения. Код одной возможности остаётся рядом с ней, включая её UI, независимую логику и узкие тесты; общие интеграционные проверки могут оставаться отдельно. -- Корень исходников содержит точки входа и архитектурные области, а не россыпь независимой прикладной логики. Общая папка компонентов не заменяет владельцев самостоятельных сценариев. В общую область выноси фактически переиспользуемый или по природе общесистемный код; она не знает конкретные возможности. +- В проекте с несколькими самостоятельными областями корень исходников содержит точки входа и эти области. Общая папка компонентов не заменяет владельцев самостоятельных сценариев. В общую область выноси фактически переиспользуемый или по природе общесистемный код; она не знает конкретные возможности. Связная утилита или библиотека может хранить несколько файлов рядом с точкой входа. - Точка композиции собирает зависимости, маршруты и экраны. Она не должна заодно владеть несколькими самостоятельными экранами, сетевым доступом и независимыми расчётами. Локальные обработчики и состояние одного связного компонента не требуют отдельного слоя. - При заметном росте файла или перед добавлением существенной функции в файл с несколькими независимыми причинами изменения агент обязан проверить ответственности: назвать владельцев поведения и решить, сохранить связный файл либо выделить самостоятельную границу в затронутой области. Несвязанный долг фиксируй отдельно. Большой связный файл допустим; число строк или файлов не заменяет эту проверку. - Формат фреймворка не отменяет разделение ответственностей. Например, Vue SFC может совместно хранить `template`, локальный `script` и локальные `style`, пока они обслуживают один связный компонент; самостоятельные сценарии, доменная логика, сетевое взаимодействие и доступ к постоянному хранилищу получают подходящую границу вне компонента экрана. @@ -27,15 +27,15 @@ ## Первоначальная архитектура -До существенной реализации нового развиваемого проекта, крупного package/application или подсистемы без установленных границ агент обязан выбрать минимальную архитектуру для первых реальных сценариев. Несколько сценариев, UI с данными и внешним доступом либо независимые причины изменения требуют выбора сразу, а не после накопления долга. Количество файлов не является критерием. +До существенной реализации нового проекта или подсистемы без установленных границ агент обязан выбрать подходящий масштаб для первых реальных сценариев. Учитывай данные, внешние эффекты, независимые причины изменения, ограничения платформы и ближайшее развитие. Сложность определяется этими условиями, а не ярлыком MVP, числом файлов или сроком жизни проекта. -Зафиксируй в локальном архитектурном контракте тип проекта, первые сценарии, выбранный архетип, области и их владельцев, направление зависимостей, точки композиции, маршрут размещения нового кода, сознательно отсутствующие слои и условия пересмотра. Несколько абзацев в `PROJECT_RULES` или существующей карте достаточно; отдельный документ не обязателен. После выбора этот контракт ограничивает дальнейшие изменения. +Зафиксируй в локальном архитектурном контракте только существенное для продолжения: где размещать новый код, владельцев данных и поведения, важные зависимости и причину выбора. Для маленького проекта достаточно нескольких предложений в существующем README или `PROJECT_RULES`; отдельная карта, перечень отсутствующих слоёв и ADR не обязательны. Для нескольких независимых областей уточни точки композиции и запрещённые связи. Укажи условие пересмотра, если оно влияет на ближайшее развитие. -Выбери один стартовый архетип: пользовательский frontend с локальными возможностями; сервис с независимыми сценариями и адаптерами; библиотека/CLI с минимальным техническим ядром. Имена каталогов зависят от проекта. Создавай каталог только вместе с реальным кодом его ответственности, без пустых слоёв на будущее. Пошаговый запуск и примеры архетипов доступны через `project-bootstrap` или команду хаба `prompt bootstrap`; они читаются только при первоначальном выборе. Если процесс не установлен или хаб недоступен, выполни этот краткий контракт и проверку границ из раздела выше, не откладывая выбор. +Не выбирай архитектуру из закрытого списка Kit. Используй соглашения выбранной технологии и существующий код; готовый материал подходит только при совпадении задачи, масштаба и версии инструментов. При существенном или дорогом в изменении выборе сравни подходящие альтернативы и рекомендуй одну; для очевидной локальной задачи сравнение не нужно. Создавай каталог вместе с реальным кодом ответственности. Пошаговый старт доступен через `project-bootstrap` или `prompt bootstrap`; отсутствие этого процесса или подходящего примера не препятствует выбору. -Одноразовый скрипт, экспериментальный файл, минимальный воспроизводитель, очень маленький прототип или небольшой CLI с одной связной обязанностью могут остаться компактными без модульного каркаса и отдельного архитектурного guard. Назови причину и триггер возврата: превращение в развиваемый продукт, второй самостоятельный сценарий или новая независимая граница. Прототип уже запланированного продукта не является автоматическим исключением. +Небольшая утилита, библиотека, скрипт или прототип с одной связной обязанностью могут оставаться компактными и при длительном использовании. Модули появляются при независимом поведении, реальном повторном использовании или существенной внешней границе; проверки — по риску. Малый размер не отменяет безопасность, сохранность данных и совместимость. -У существующей области сначала используй действующие границы. Подключение правил не создаёт архитектуру, guard и не разрешает рефакторинг: отсутствие контракта фиксируется как разрыв. При обычной feature-задаче читай локальный маршрут размещения кода и затронутые решения, а не все стартовые архетипы. +У существующей области сначала используй действующие границы. Подключение правил не создаёт архитектуру, guard и не разрешает рефакторинг: отсутствие нужного контекста фиксируется как разрыв. При обычной feature-задаче читай локальный маршрут размещения кода и затронутые решения, без повторного выбора основы. ## Целевое состояние и переход diff --git a/rules/DOCUMENTATION.md b/rules/DOCUMENTATION.md index 19631b6..d697d77 100644 --- a/rules/DOCUMENTATION.md +++ b/rules/DOCUMENTATION.md @@ -4,6 +4,8 @@ Документ помогает человеку понять проект или выполнить работу. Перед созданием файла проверь, почему информация не может жить в уже существующем месте. Если самостоятельной задачи нет, новый файл не нужен. +Минимальный контекст для продолжения — что делает проект, как запустить и проверить его, где находится затронутый код, какие ограничения и существенные решения нужно сохранить. Обычно достаточно README и коротких локальных правил. Приведённые ниже роли не требуют отдельных файлов: карта системы и решения могут быть разделами существующего документа. Runbook нужен при реальных операционных действиях; handoff — для незавершённой передаваемой работы. + - `AGENTS.md` — короткая точка входа в корне: начало работы, применимые правила, расположение проектного контекста, карты и решений. - `PROJECT_MAP` — как устроен проект и где найти реализацию основных сценариев. Покажи вход, важные переходы, владельцев данных и внешний эффект; дай ссылки на код и контракты. Не копируй решения, подробные инструкции и журналы проверок. - `DECISIONS` — какие важные решения определяют устройство проекта сейчас и что нужно знать перед изменением. @@ -23,19 +25,17 @@ ### Решение и событие -Решения: SQLite — основное хранилище; данные сначала сохраняются локально; конфликт синхронизации разрешает пользователь; frontend остаётся на Vercel; выбран self-hosted Supabase; Telegram Topics служат операторской поверхностью. - -События: куплен VPS, зарегистрирован домен, прошло 198 E2E, создан PR, выполнен deploy, исправлены F1–F7, CI упал, обновлены screenshots, проверен SHA, staging прошёл smoke, завершён аудит. Их место — текущая работа, issue, PR, CI или нужное evidence, а не карта решений. +«Данные сначала сохраняются локально» — решение. «Прошли тесты, выполнен deploy» — событие; его место в текущей работе, PR, CI или нужном свидетельстве проверки. Карта решений не становится журналом поставок. Отделяй выбор от исполнения. Решение о self-hosted Supabase сохраняет смысл после смены сервера; текущие VPS, DNS, HTTPS, SMTP, S3, миграционные этапы и deployment SHA относятся к эксплуатации или рабочему материалу. Принятое решение ещё не доказывает готовность реализации. Если это влияет на безопасное изменение, укажи короткое ограничение и ссылку на текущее состояние. ### Формат и размер -По умолчанию достаточно одного `DECISIONS.md` с короткими разделами, без огромной таблицы и обязательных метаданных. Запись содержит **Решение**, **Зачем** (если причина известна) и **Где смотреть**; при необходимости добавь **Важно помнить** и **Пересмотреть, если**. Например: +По умолчанию достаточно раздела решений в существующем документе или одного `DECISIONS.md`, если раздел вырос. Без огромной таблицы и обязательных метаданных. Запись содержит **Решение**, **Зачем** (если причина известна) и **Где смотреть**; при необходимости добавь **Важно помнить** и **Пересмотреть, если**. Например: > SQLite — основное хранилище состояния. События и ответы сначала сохраняются, затем обрабатываются. Это позволяет переживать перезапуск и не повторять действия без необходимости. Реализация: `src/infrastructure/persistence/`. -Обычно запись занимает 5–12 строк содержательного текста; заголовки и пустые строки не считаются. Это ориентир читаемости, а не повод удалять значимую границу. Карта из 5–10 решений должна читаться за несколько минут. Большому проекту может понадобиться больше решений, но карта не растёт вместе с историей задач. +Краткость определяется удобством чтения и ценой решения. Не заполняй фиксированное число полей, строк или решений; не удаляй значимую границу ради размера. Сохраняй устойчивые ID и полезные ссылки. Не придумывай историческую причину или рассмотренные альтернативы: неизвестное можно сказать одной фразой. Предложения не выдавай за принятый выбор; при необходимости сохраняй их в текущей работе или явно отделённой части существующего ADR. @@ -43,28 +43,13 @@ ### Где хранить -Значимые долгоживущие решения хранятся в версионируемом и восстанавливаемом источнике, доступном после clone с нужными правами. Версионируемый не означает публичный. В приватном проекте используй его существующий контекст; при отсутствии структуры допустима `.ai/` с `PROJECT_MAP.md`, `DECISIONS.md` и `work/`. Не создавай рядом ещё `.project`, `docs/internal` и вторую систему контекста. +Значимые долгоживущие решения хранятся в версионируемом и восстанавливаемом источнике, доступном после clone с нужными правами. Версионируемый не означает публичный. Используй существующий контекст; новое место нужно только при иной аудитории или границе хранения. Не создавай `.ai/`, `.project`, `docs/internal` и вторую систему контекста ради шаблона. Корень — место для точек входа, стандартных файлов проекта и документов, нужных инструментам или внешним участникам: `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, `SECURITY.md`, `LICENSE`, package/config/build files. Внутренние `DECISIONS.local.md`, `PROJECT_MAP.local.md`, `AI_FEEDBACK.local.md`, publication preparation, research, audit и handoff по умолчанию находятся в проектном контексте. Намеренно публичная карта или требуемый инструментом корневой файл допустимы при понятной пользе. ### Приватный источник публичного проекта -**Private Project Context** — отдельный приватный версионируемый источник внутреннего контекста публичного проекта. Сохраняй уже выбранный источник вместо переноса в `.ai` ради имени. Постоянные карты находятся отдельно от временной работы, например: - -```text -private-context/project/ - PROJECT_MAP.md - DECISIONS.md - agent/ - work/ # только нужные материалы - audits/ - research/ - delivery/ - migrations/ - investigations/ -``` - -Это пример, а не обязательный набор папок. Создавай только используемые. `.local` и игнорируемая копия не заменяют восстанавливаемый источник значимых решений. Публичные решения допустимы при внешней пользе и проверке содержимого. `visibility: private` не защищает файл в публичном Git. +**Private Project Context** — приватный версионируемый источник внутреннего контекста публичного проекта. Сохраняй уже выбранное место; постоянные сведения отделяй от временной работы без обязательного дерева папок. `.local` и игнорируемая копия не заменяют восстановление значимых решений. Публичные решения допустимы при внешней пользе и проверке содержимого. `visibility: private` не защищает файл в публичном Git. Связь проекта с источником, доступ и восстановление должны быть понятны следующему агенту с нужными правами. Приватные пути не попадают в публичные документы. Уникальные `AGENTS.md`, `PROJECT_RULES.md`, `RULESET.md` и выбранная конфигурация также получают способ восстановления. Производный `upstream/` восстанавливается из версии Kit, manifest и lock. Необязательный локальный descriptor и пределы диагностики описаны в [sync/README.md](../sync/README.md#публичный-проект-и-private-project-context). @@ -84,7 +69,9 @@ Kit не выбирает сервис хранения и не синхрони ## Жизненный цикл рабочих материалов -Используй одно место `work/` внутри существующего проектного контекста. Публичные руководства, обязательная история и внешние контракты остаются на своих местах. Учебный материал следует [PROJECT_STUDY](../workflows/PROJECT_STUDY.md), но не создаёт вторую карту решений. +Если задаче нужны рабочие материалы, используй одно существующее место, например `work/` в проектном контексте. Публичные руководства, обязательная история и внешние контракты остаются на своих местах. Учебный материал следует [PROJECT_STUDY](../workflows/PROJECT_STUDY.md), но не создаёт вторую карту решений. + +Обновляй документ вместе с изменением описанного контракта, команды, границы или принятого решения. Не документируй очевидное из кода, каждую команду, локальную обратимую деталь или результат проверки, уже доступный в CI, без причины хранить его отдельно. Возвращаясь после перерыва, начни с точки входа, текущих команд, решений области, `git status` и незавершённой задачи; всю историю читать не нужно. После завершения задачи материал должен стать частью постоянного документа, остаться компактным историческим evidence с понятной причиной хранения либо быть удалён. Не сохраняй каждый audit/research/handoff «на всякий случай». Для оставленной временной работы должно быть понятно, что ещё нужно сделать и когда материал перестанет быть нужен; отдельный реестр для этого не требуется. @@ -96,7 +83,7 @@ Kit не выбирает сервис хранения и не синхрони Правила и вспомогательные процессы (scaffolding) не вечны. В существующем описании значимого решения кратко объясни, какой сбой предотвращает мера, её цену и условие пересмотра или удаления. Подробные сравнения моделей, запуски и доказательства относятся к исследованию, а не обязательным полям каждой карты. -После значимого обновления модели или процесса пересмотри полезность меры. Исчезновение исходного сбоя или равноценный более простой путь делают её кандидатом на удаление. Сравнение следует [правилам исследования](RESEARCH_AND_EVIDENCE.md#сравнение-процессов); ограничения доступа и обязательства проекта сохраняются. +При наблюдаемой потере пользы пересмотри меру: повторяющаяся настройка может стать конфигурацией или проверкой, лишняя инструкция — исчезнуть. Реальной работы и прямой проверки часто достаточно; обновление модели не требует нового исследования или платного сравнения. Если сравнение действительно нужно, действуют [правила исследования](RESEARCH_AND_EVIDENCE.md#сравнение-процессов); ограничения доступа и обязательства проекта сохраняются. ## Аудит документации и hygiene diff --git a/rules/GIT_AND_DELIVERY.md b/rules/GIT_AND_DELIVERY.md index 0ca20a9..4344c0e 100644 --- a/rules/GIT_AND_DELIVERY.md +++ b/rules/GIT_AND_DELIVERY.md @@ -2,11 +2,9 @@ ## Локальная история -- До изменения проверь branch, `git status` и релевантный diff. Сохраняй несвязанные изменения владельца. - Коммит имеет один проверяемый результат и включает относящиеся к нему тесты. До добавления в индекс раздели diff по намерению и проверь, можно ли независимо понять, проверить или откатить каждую часть. - Если части дают самостоятельные результаты или относятся к разным причинам изменения, раздели их на логические коммиты. Функциональная правка не смешивается с массовым форматированием, несвязанным рефакторингом, обновлением зависимостей или изменением общей инфраструктуры. - Большой коммит допустим при создании проекта, добавлении одного связного модуля или другом неделимом результате, когда разбиение создаст непроверяемое промежуточное состояние. Само количество файлов не доказывает ни необходимость разбиения, ни целостность коммита. -- Не переписывай историю, не удаляй данные и не меняй чужую ветку без отдельного разрешения. - Добавление в индекс Git, `commit`, `push`, запрос на слияние, объединение веток, выпуск и публикация выполняются только в явно разрешённых границах. ## Ветки и изоляция изменения @@ -18,10 +16,7 @@ ## Параллельные пишущие задачи в Git -- Для каждой пишущей задачи зафиксируй базовую ветку и точный базовый commit до создания ветки задачи. Назначь ей одну ветку и один рабочий каталог; отдельный `git worktree` — рекомендуемый способ изоляции параллельных исполнителей. Другой пишущий исполнитель не использует этот каталог. -- Исполнитель не переключает ветку внутри назначенного worktree произвольно. Изменение базы или ветки координируется с владельцем интеграции и не переносит чужие незавершённые изменения. -- Владелец интеграции отвечает за `merge`, `rebase` или `cherry-pick` результатов в интеграционную ветку и за проверку итогового состояния. Исполнитель не интегрирует свою работу без выданных полномочий. Добавление в индекс, коммит, отправка, запрос на слияние и внешняя поставка сохраняют границы разрешения из раздела «Локальная история». -- Удаляй рабочий каталог или worktree только с разрешения владельца после проверки, что нужный результат сохранён, доступен владельцу интеграции и больше не требуется для проверок. Нельзя терять незакоммиченные или ещё не интегрированные изменения при очистке. +Координация и один владелец интеграции — по [AI_COLLABORATION](AI_COLLABORATION.md#параллельная-работа). Для пишущей задачи назначь одну ветку, известный базовый commit и изолированный каталог. Исполнитель не переключает базу и не выполняет интеграцию без полномочий. Worktree удаляется только после разрешения и проверки сохранности незакоммиченного или ещё не интегрированного результата. Подробный [PARALLEL_DELIVERY](../workflows/PARALLEL_DELIVERY.md) нужен при явной параллельной задаче. ## Сообщения коммитов и автоматическая проверка diff --git a/rules/IMPLEMENTATION.md b/rules/IMPLEMENTATION.md index 09bf47a..dbb1343 100644 --- a/rules/IMPLEMENTATION.md +++ b/rules/IMPLEMENTATION.md @@ -2,7 +2,6 @@ ## Изменение кода -- Сначала проследи затронутый сценарий и его контракты, затем меняй минимальную связанную область. - Перед реализацией существенного нового UI или редизайна выполни раздел «Визуальное направление до реализации» в [PRODUCT](PRODUCT.md#визуальное-направление-до-реализации); обычные изменения используют действующий визуальный контракт. - До добавления нового кода найди его владельца и место по локальному архитектурному контракту. Для нового развиваемого проекта или крупной подсистемы без границ сначала выполни раздел «Первоначальная архитектура» в `ARCHITECTURE_AND_DATA.md`; обычная feature-задача использует уже выбранную структуру. - Если дефект или требование может повторяться в похожих экранах, компонентах, операциях или состояниях, до исправления найди семантически аналогичные места во всём затронутом сценарии. Не ограничивай поиск совпадением имени файла, селектора или текста. @@ -10,7 +9,6 @@ - Перенос, замена или удаление поведения завершены, когда прослежены прежние точки входа и потребители, для каждого выбран результат: удалить, перенаправить, мигрировать либо осознанно сохранить. Проверь доступность нового пути и отсутствие незапланированного старого. - Следуй локальному стилю и существующим устойчивым абстракциям. Не смешивай функциональную правку с массовым форматированием или несвязанным рефакторингом. - Ошибка должна сохранять причину и контекст, достаточный для диагностики, но не раскрывать секреты или чувствительные данные. -- Совместимость публичного поведения — по CORE, раздел «7. Обратимость и совместимость». ## Читаемость управляющего потока diff --git a/rules/PRODUCT.md b/rules/PRODUCT.md index 4c022bb..d6299b5 100644 --- a/rules/PRODUCT.md +++ b/rules/PRODUCT.md @@ -21,11 +21,11 @@ ## Визуальное направление до реализации -До реализации нового продукта с существенным UI, самостоятельной визуальной области или значительного редизайна агент обязан выбрать визуальное направление через Design Discovery. Это относится и к задаче устранить признанную шаблонность интерфейса. Формулировки «современный dashboard», modern, clean или elegant не задают достаточного направления. +До реализации нового продукта с существенным UI, самостоятельной визуальной области или значительного редизайна агент обязан выбрать подходящее визуальное направление. Определи аудиторию, основной сценарий, приоритет информации, плотность и ограничения платформы. Формулировки «современный dashboard», modern, clean или elegant не задают достаточного направления. Для продукта без графического интерфейса процесс не применяется. -Минимальный результат до кода: характер продукта → исследование и примерно 4–6 обоснованных разноплановых референсов → таблица «Reference / Почему выбран / Что берём / Что не берём» → минимум два существенно разных направления → выбранное направление и короткий визуальный контракт. Различие только в цвете или скруглениях не считается отдельным направлением. Используй подтверждённые материалы, не выдавай непроверенные интерфейсы за просмотренные. После реализации проверь соответствие контракту и шаблонность по [QUALITY](QUALITY.md#проверка-интерфейса). +Минимальный результат до кода — одна обоснованная композиция для первого сценария и короткий визуальный контракт. Референсы нужны, когда помогают выбрать или объяснить направление; фиксированного количества и обязательной матрицы нет. Несколько направлений сравнивай при значимой неопределённости, дорогом выборе или запросе владельца; различие только в цвете не считается альтернативной композицией. Используй подтверждённые материалы, не выдавай непроверенные интерфейсы за просмотренные. После реализации проверь соответствие контракту и шаблонность по [QUALITY](QUALITY.md#проверка-интерфейса). -Подробный процесс — [VISUAL_DESIGN_DISCOVERY](../workflows/VISUAL_DESIGN_DISCOVERY.md). Читай его только для подходящей задачи: из выбранной копии по `INDEX.md` или доступного хаба. Если процесс недоступен, выполни описанный выше минимум и явно назови ограничения исследования; это не повод сразу реализовать привычный dashboard. Установка workflow не является условием выбора направления. +Подробный процесс — [VISUAL_DESIGN_DISCOVERY](../workflows/VISUAL_DESIGN_DISCOVERY.md). Читай его при необходимости исследования или сравнения: из выбранной копии по `INDEX.md` или доступного хаба. Описанного выше минимума достаточно для ясного выбора. Действующие компоненты, токены и соглашения платформы имеют приоритет перед случайным новым набором; один визуальный стиль Kit не задаёт. Исправление компонента, добавление поля или небольшого состояния, обычная feature-задача в установленной визуальной системе, accessibility fix и layout bug не запускают Discovery. Используй действующий осознанный visual contract/design system; новое исследование нужно только при изменении направления или подтверждённой непригодности для задачи. Правило применяется к будущим существенным UI-задачам: подключение Kit не разрешает массовый редизайн существующих проектов. diff --git a/rules/QUALITY.md b/rules/QUALITY.md index 216549d..7f266bd 100644 --- a/rules/QUALITY.md +++ b/rules/QUALITY.md @@ -4,7 +4,7 @@ До реализации выбери критерий приёмки и проверку, наблюдающую нужный эффект на затронутой границе. Глубина зависит от вероятности дефекта, цены ошибки и обратимости; зелёный внутренний шаг не доказывает конечный результат. -Проверь минимум основной изменённый путь и ближайший значимый отказ. Для чувствительных данных, миграций, публичных контрактов, конкурентных записей и релиза глубина должна быть выше. +Проверь основной изменённый путь и ближайший значимый отказ, если он применим. Используй прямую проверку результата; не создавай тестовую инфраструктуру или зеркальные тесты для низкорисковой обратимой детали. Для чувствительных данных, миграций, публичных контрактов, конкурентных записей и релиза глубина должна быть выше. Для повторяющегося класса дефектов составь короткий перечень представительных мест и состояний с тем же контрактом. Проверь общий механизм и представительные поверхности, состояния или точки входа: один исправленный экземпляр не подтверждает устранение класса. Непроверенные варианты и риск назови в передаче. @@ -41,7 +41,7 @@ ## Проверка интерфейса - Для нового визуального направления сопоставь результат с выбранной концепцией и контрактом из [PRODUCT](PRODUCT.md#визуальное-направление-до-реализации). Проверь сохранение информационной иерархии и отсутствие случайного возврата к привычным generic components. Используй представительные реальные данные или явно обозначенные реалистичные обезличенные данные, когда реальные недоступны или приватны; коротких заглушек недостаточно. -- Перед завершением нового дизайна обязательно проверь, не повторяет ли он механически стандартный AI dashboard или доступные для сравнения прежние проекты. Для существенных решений спроси: «Почему это решение существует именно в этом продукте?» Ответ должен опираться на пользовательскую задачу, выбранное направление и референсы. Sidebar, topbar, cards, badges, серый фон и скруглённые панели допустимы; «это стандартный dashboard pattern» — основание пересмотреть выбор, а не его оправдание. Снимок существования UI сам по себе не доказывает качество дизайна. +- Перед завершением нового дизайна обязательно проверь, не повторяет ли он механически стандартный AI dashboard или доступные для сравнения прежние проекты. Для существенных решений спроси: «Почему это решение существует именно в этом продукте?» Ответ должен опираться на пользовательскую задачу и выбранное направление; референсы используются, если они помогли выбору. Sidebar, topbar, cards, badges, серый фон и скруглённые панели допустимы; «это стандартный dashboard pattern» — основание пересмотреть выбор, а не его оправдание. Снимок существования UI сам по себе не доказывает качество дизайна. - Для нового или существенно изменённого интерфейса проверь основной сценарий хотя бы на одном поддерживаемом узком и широком размере. Добавь представительные варианты длинного содержимого, увеличенного текста и динамического сообщения, если они могут менять компоновку. - Проверь применимые состояния интерактивных элементов: обычное, `hover`, `focus-visible`, `active` или `pressed`, `disabled`, `loading` и ошибку действия. Основной путь отдельно пройди клавиатурой или другим основным доступным способом ввода платформы. - Визуальная проверка включает иерархию, интервалы, переносы, обрезание и перекрытие. При изменении компоновки проверь геометрию и доступность действий до, во время и после перехода, включая значимых соседей, фокус и прокрутку. Наблюдение краткого эффекта начинается до действия; конечный снимок его не доказывает. diff --git a/rules/README.md b/rules/README.md index 5384438..be52bb9 100644 --- a/rules/README.md +++ b/rules/README.md @@ -4,7 +4,7 @@ Сначала определи задачу по запросу владельца и указанному им контексту. До планирования и изменений прочитай локальные ограничения, CORE и выбранные профили, затем по индексу выбери темы для затронутой области. Установленный набор не требует чтения всех тем. Чтение правила не запускает полный рабочий процесс; его условия и обязанности профиля сохраняются. -[`CORE.md`](CORE.md) обязателен для каждого подключённого проекта. Каждый выбранный профиль читается всегда: он содержит уникальные обязанности типа проекта. Тематические правила читаются только когда относятся к текущей задаче, даже если входят в композицию профиля. +[`CORE.md`](CORE.md) обязателен для каждого подключённого проекта. Каждый выбранный профиль читается всегда: он содержит уникальные обязанности типа проекта. В тематических правилах читай применимые разделы, даже если тема входит в композицию профиля. Например, запись решения не требует чтения всей процедуры очистки документации; работа с данными требует соответствующих защитных разделов независимо от масштаба проекта. Канонический состав профилей и порядок тем задаёт [`../sync/catalog.json`](../sync/catalog.json). Manifest выбирает состав проекта, а status показывает точный effective-набор. @@ -24,6 +24,8 @@ Для выбора визуального направления есть отдельный `visual-design-discovery` — [`VISUAL_DESIGN_DISCOVERY.md`](../workflows/VISUAL_DESIGN_DISCOVERY.md). Обязанность до реализации и исключения задаёт `PRODUCT.md`; подробный процесс читается по задаче из хаба или явно выбранной копии. Существующие визуальные системы и малые правки не требуют повторного Discovery. +[`PROJECT_BOOTSTRAP`](../workflows/PROJECT_BOOTSTRAP.md) выбирает основу по первому сценарию и ограничениям, без закрытого списка архитектур. [Технические материалы](../templates/README.md#технические-материалы) необязательны и не являются нормами: агент применяет подходящую часть либо выбирает средства другого стека. Код и настройки после применения принадлежат проекту. Графический дизайн, CI, guard и отдельные карты нужны только при своей задаче или риске. + ## Приоритет правил При конфликте применяй следующий порядок: diff --git a/sync/catalog.json b/sync/catalog.json index fb36059..c68a2b3 100644 --- a/sync/catalog.json +++ b/sync/catalog.json @@ -19,7 +19,7 @@ "file": "rules/ARCHITECTURE_AND_DATA.md", "kind": "rule", "description": "Архитектурные границы, источники истины, данные, API и миграции.", - "readWhen": "При размещении нового кода, изменении архитектуры, данных, API, хранилища или миграций. Для существующей области используй локальный архитектурный контракт; первоначальный выбор обязателен до существенной реализации нового развиваемого проекта или крупной подсистемы без границ." + "readWhen": "При размещении нового кода, изменении архитектуры, данных, API, хранилища или миграций. Для существующей области используй локальный архитектурный контракт; первоначальный выбор обязателен до существенной реализации нового проекта или крупной подсистемы без границ. Компактная структура допустима; механические проверки границ выбирай по риску." }, "implementation": { "file": "rules/IMPLEMENTATION.md", @@ -49,7 +49,7 @@ "file": "rules/DOCUMENTATION.md", "kind": "rule", "description": "Карта значимых решений, канонические документы и маршрутизация контекста.", - "readWhen": "До значимого выбора или пересмотра решения; при создании, изменении, аудите или публикации документации." + "readWhen": "До значимого выбора или пересмотра решения; при создании, изменении, аудите или публикации документации. Читай нужный раздел; наличие шаблонов не требует отдельных карт, ADR и отчётов." }, "git-and-delivery": { "file": "rules/GIT_AND_DELIVERY.md", @@ -84,8 +84,8 @@ "project-bootstrap": { "file": "workflows/PROJECT_BOOTSTRAP.md", "kind": "workflow", - "description": "Первоначальный выбор минимальной архитектуры, размещения кода и механической защиты границ.", - "readWhen": "При явном выборе project-bootstrap и создании развиваемого проекта или крупной подсистемы без границ; не при обычной feature-задаче." + "description": "Работающая основа проекта: подходящий масштаб, выбор технологии, полезные материалы и первый полноценный сценарий.", + "readWhen": "При явном выборе project-bootstrap и старте нового программного проекта или согласованной крупной подсистемы без основы; не при обычной feature-задаче." }, "visual-design-discovery": { "file": "workflows/VISUAL_DESIGN_DISCOVERY.md", diff --git a/templates/AGENTS.md b/templates/AGENTS.md index af2908e..d67e670 100644 --- a/templates/AGENTS.md +++ b/templates/AGENTS.md @@ -16,13 +16,13 @@ `INDEX.md` показывает, что и когда читать. Не считай его источником истины. Точный состав и версию правил определяют `.ai-rules/manifest.json`, `.ai-rules/lock.json` и команда `ai-rules.ps1 status`. -Читай выбранный профиль целиком. По условиям «Читать» в `INDEX.md` выбери темы для текущей задачи; расширяй чтение при обнаружении зависимости или риска. Не читай весь каталог `.ai-rules/upstream/` и все темы без связи с задачей. +Читай выбранный профиль целиком. По условиям «Читать» в `INDEX.md` выбери темы и применимые разделы для текущей задачи; расширяй чтение при обнаружении зависимости или риска. Не читай весь каталог `.ai-rules/upstream/` и все темы без связи с задачей. Условия действий и защитные обязанности сохраняются независимо от размера задачи. Чтение тематического правила не запускает полный рабочий процесс. Запускай процесс только по явному запросу или при выполнении условий соответствующего правила; установленные профилем обязанности остаются обязательными. Состав подключённых тем сам по себе не расширяет задачу. -При создании развиваемого проекта или крупной подсистемы без архитектурного контракта найди по `INDEX.md` тему `architecture-and-data` и начни с первоначального выбора. Если тема не подключена, обозначь необходимое расширение набора; не начинай существенную реализацию без границ. Для обычного изменения используй локальный маршрут размещения кода, без чтения всех стартовых архетипов. +При создании проекта или крупной подсистемы без архитектурного контракта найди по `INDEX.md` тему `architecture-and-data` и выбери подходящий масштаб. Если тема не подключена, используй доступный хаб или обозначь необходимое расширение набора. Небольшому проекту достаточно связных файлов и короткого объяснения. Для обычного изменения используй локальный маршрут размещения кода, без повторного bootstrap. -Пути к документации проекта указаны в `.ai-rules/PROJECT_RULES.md`. По индексу и заголовкам найди нужную область, прочитай её разделы карты проекта и записи решений, затем связанные источники. Не читай всю карту или каталог `docs/` для узкой задачи. +Пути к документации проекта указаны в `.ai-rules/PROJECT_RULES.md`. Читай нужные разделы и связанные источники. Отдельная карта проекта не обязательна; не читай весь каталог `docs/` для узкой задачи. ## Где менять правила @@ -40,8 +40,4 @@ Перед созданием документа прочитай подключённое правило документации по `INDEX.md`: оно определяет аудиторию, каноническое место, хранение и публикацию. Название файла и наличие шаблона сами по себе не требуют его создания или публикации. -## Общие действия - -Перед изменениями проверь `git status` и сохрани несвязанные изменения. Для средней или большой задачи веди короткий план с одним активным пунктом. - -Выполняй проверки из `.ai-rules/PROJECT_RULES.md`. Не выполняй `commit`, `push`, выпуск, публикацию, переписывание истории или удаление данных без отдельного явного разрешения владельца. +Проверки и локальные полномочия заданы в `.ai-rules/PROJECT_RULES.md`; общие ограничения сохраняются по CORE. diff --git a/templates/ARCHITECTURE.md b/templates/ARCHITECTURE.md index d0535aa..9a04f08 100644 --- a/templates/ARCHITECTURE.md +++ b/templates/ARCHITECTURE.md @@ -11,7 +11,7 @@ ## Первоначальный выбор и области - Тип проекта и первые реальные сценарии: `<...>`. -- Выбранный архетип и причина: ``. +- Выбранная основа и причина: `<соглашения платформы, масштаб и реальные границы под первые сценарии>`. - Функциональные области и уровни: `<реально нужные владельцы UI, прикладного поведения, данных и внешнего доступа>`. - Точки композиции: `<где собираются зависимости и экраны>`. - Сознательно отсутствуют: `<слои без текущей ответственности>`. diff --git a/templates/PROJECT_KNOWLEDGE.md b/templates/PROJECT_KNOWLEDGE.md index ebad101..752f01a 100644 --- a/templates/PROJECT_KNOWLEDGE.md +++ b/templates/PROJECT_KNOWLEDGE.md @@ -1,29 +1,10 @@ -# Актуальные знания о проекте +# Указатель контекста проекта -Последнее обновление: `` +Не создавай этот файл рядом с уже достаточными README, локальными правилами или картой. Шаблон сохранён для существующих маршрутов; он не требует второй копии состояния и решений. -## Назначение и текущая стадия +- Назначение, запуск и проверки: `<канонический документ>`. +- Устройство и ограничения: `<документ и нужные разделы>`. +- Значимые решения: `<каноническое место>`. +- Незавершённая работа: `<одна актуальная задача, если нужна>`. -- `<Подтверждённые устойчивые факты.>` - -## Принятые решения - -- `<Решение со ссылкой на канонический документ или ADR.>` - -## Фактически реализовано - -- `<Наблюдаемое текущее состояние.>` - -## Активная работа - -- `<Только текущий slice; подробности в SESSION_CONTEXT.md.>` - -## Известные ограничения - -- `<...>` - -## Следующий конкретный шаг - -`<Один проверяемый шаг.>` - -Читай разделы текущей задачи и переходи к связанным источникам по необходимости. Это не журнал сессий; удаляй рабочие детали, переставшие описывать текущее состояние. +Храни здесь только указатели, если они сокращают поиск. Содержание обновляй в его источнике. diff --git a/templates/PROJECT_RULES.full.md b/templates/PROJECT_RULES.full.md index 15df38e..3689998 100644 --- a/templates/PROJECT_RULES.full.md +++ b/templates/PROJECT_RULES.full.md @@ -31,7 +31,7 @@ ## Структура проекта - `<../каталог или модуль>` — `<локальная ответственность>`. -- Первоначальный выбор: `<тип, первые сценарии, выбранный архетип; ссылка на канонический контракт / не установлен>`. +- Первоначальный выбор: `<масштаб, первые сценарии и причина; ссылка на канонический контракт / не установлен>`. - Зависимости и композиция: `<разрешённые направления, точки входа, запрещённые связи и точка сборки / не установлены>`. | Новый код | Владелец и точный путь | @@ -42,7 +42,7 @@ | Новая самостоятельная возможность | `<новый feature/module по действующему контракту>` | | Композиция приложения | `<точка сборки зависимостей и экранов>` | -Сознательно отсутствующие слои и триггеры роста: `<...>`. Механическая проверка границ: `<команда, ограничения и место запуска / не установлена>`. +Заполняйте только реальные области, нужные продолжению; таблица не требует создания модулей. Существенные условия пересмотра: `<если есть>`. Механическая проверка границ: `<по риску: команда, ограничения и место запуска / не установлена>`. ## Документация и маршрутизация контекста diff --git a/templates/PROJECT_RULES.md b/templates/PROJECT_RULES.md index d2355eb..03e03d2 100644 --- a/templates/PROJECT_RULES.md +++ b/templates/PROJECT_RULES.md @@ -19,8 +19,8 @@ - `<Значимые каталоги, канонические документы и узкие маршруты чтения для разных задач.>` - Карта проекта: `<ссылка и разделы по областям / не установлена>`; карта решений: `<ссылка; читать записи затронутой области / не установлена>`. - Источник решений / Private Project Context: `<версионируемый источник, связь с проектом, доступ и восстановление / не установлен>`. -- Архитектурный контракт: `<ссылка на раздел / кратко: тип, первые сценарии, архетип, области, зависимости, точка композиции, отсутствующие слои и условия пересмотра / не установлен>`. -- Где размещать новый код: ``. +- Архитектурный контракт: `<ссылка / кратко: владельцы, важные границы и причина выбора; несколько связных файлов допустимы / не установлен>`. +- Где размещать новый код: `<фактические места для поведения, данных и внешнего доступа по выбранной технологии / не установлено>`. ## Граница документации diff --git a/templates/README.md b/templates/README.md index 419ad35..2c1bd9b 100644 --- a/templates/README.md +++ b/templates/README.md @@ -17,7 +17,7 @@ Готовые запросы находятся отдельно: - [`PROJECT_CONNECT_PROMPT.md`](../workflows/PROJECT_CONNECT_PROMPT.md) — подключение проекта; -- [`PROJECT_BOOTSTRAP.md`](../workflows/PROJECT_BOOTSTRAP.md) — первоначальная архитектура и архетипы через `ai-rules.ps1 prompt bootstrap -ProjectRoot <путь>`; отдельный файл архитектуры не обязателен. +- [`PROJECT_BOOTSTRAP.md`](../workflows/PROJECT_BOOTSTRAP.md) — работающая основа и первый сценарий через `ai-rules.ps1 prompt bootstrap -ProjectRoot <путь>`; подключение может входить в тот же одобренный план. - [`PROJECT_AUDIT_PROMPT.md`](../workflows/PROJECT_AUDIT_PROMPT.md) — завершение подключения и первичная проверка; - [`PROJECT_DEEP_AUDIT_PROMPT.md`](../workflows/PROJECT_DEEP_AUDIT_PROMPT.md) — подключение и запуск глубокого аудита; - [`PROJECT_STUDY_PROMPT.md`](../workflows/PROJECT_STUDY_PROMPT.md) — подключение и начало изучения проекта через `ai-rules.ps1 prompt study -ProjectRoot <путь>`. @@ -36,10 +36,21 @@ - [`DECISIONS.md`](DECISIONS.md) — короткая карта действующих решений в одном файле по [правилу документации](../rules/DOCUMENTATION.md#карта-значимых-решений), без обязательной миграции старых записей; - [`RESEARCH.md`](RESEARCH.md) — проверяемое исследование; - [`DEVELOPMENT_ERRORS.md`](DEVELOPMENT_ERRORS.md) — необязательный журнал существенных проблем с отдельными статусами дефекта и меры для Kit; -- [`PROJECT_KNOWLEDGE.md`](PROJECT_KNOWLEDGE.md) — устойчивые знания о проекте; -- [`SESSION_CONTEXT.md`](SESSION_CONTEXT.md) — временная передача контекста. +- [`PROJECT_KNOWLEDGE.md`](PROJECT_KNOWLEDGE.md) — совместимый указатель; новый файл не нужен рядом с достаточной точкой входа; +- [`SESSION_CONTEXT.md`](SESSION_CONTEXT.md) — необязательная краткая передача незавершённой работы. - [`TASK_CONTRACT.md`](TASK_CONTRACT.md) — границы и приёмка одной параллельной подзадачи. Не создавайте документ только потому, что существует шаблон. Сначала определите читателя, задачу документа и место хранения. Низкоуровневые команды описаны в [`sync/README.md`](../sync/README.md). + +## Технические материалы + +- [Vue/Vite](technical/vue-vite/README.md) — TypeScript, линтер, тестирование вычислений и сборка; пример проверки чистой логики без зависимости от Vue. +- [Node service](technical/node-service/README.md) — TypeScript с нативными ESM, линтер, тесты встроенным runner и пример границы логики и HTTP. + +Это отдельные настройки и команды, не шаблоны целого приложения. Bootstrap выбирает только совместимую часть; для другого стека использует его обычные средства. Не применяйте оба комплекта, все файлы или guard автоматически. Существующая конфигурация проекта имеет приоритет. + +`package.example.json` показывает проверенное сочетание прямых версий, но не устанавливается хабом. После применения зависимости и lockfile принадлежат проекту; обновление правил не меняет их. Повторная проверка нужна при изменении инструментов, а не для каждого проекта на той же версии. Условия, ограничения и команды — в README каждого материала. + +Прямая проверка материалов: `node tests/templates/test-technical-materials.mjs` из корня хаба с Node 22.13+ и npm 11. Она устанавливает зависимости в собственные временные каталоги, проверяет типы, линтер, поведение, сборку и запрещённые импорты. `--offline` разрешает только локальный npm cache, `--keep` сохраняет временный каталог и lockfile как свидетельство. `npm_execpath` может указать `npm-cli.js` выбранной версии без смены глобальной установки. Этот отдельный тест требует Node и npm; обычные проверки синхронизации сохраняют PowerShell-контракт без JavaScript-зависимостей. diff --git a/templates/SESSION_CONTEXT.md b/templates/SESSION_CONTEXT.md index ddddbf3..dd5d143 100644 --- a/templates/SESSION_CONTEXT.md +++ b/templates/SESSION_CONTEXT.md @@ -1,43 +1,16 @@ -# Контекст текущей сессии +# Передача незавершённой работы -Последнее обновление: `` +Создавай только при прерывании или передаче задачи, когда существующей задачи или сообщения недостаточно. Это временная сводка, не постоянный журнал. -## Активная задача и цель подшага +- Цель и согласованные границы: `<...>`. +- Изменено и проверено: `<области; команды и результаты>`. +- Ограничение или препятствие: `<подтверждённый факт / неизвестное>`. +- Следующее действие: `<один проверяемый шаг>`. -- `<...>` - -## Привязка подзадачи +## Только для параллельной подзадачи - Task ID: `<...>`; базовая ревизия: ``. -- Текущая ветка: `<...>`; назначенный workspace/worktree: `<...>`. -- Контракт подзадачи: `<ссылка и версия>`; последний проверенный commit/revision: ``. - -Не копируй сюда весь контракт подзадачи. - -## Что уже изменено - -- `<файл, поведение, проверка>` - -## Точная текущая ошибка или blocker - -```text - -``` - -## Последняя проверенная гипотеза - -- `<...>` - -## Последний принятый выбор - -- `<решение и причина>` - -## Следующее действие - -1. `<одно действие>` - -## Вопросы для review - -- `<...>` +- Ветка и назначенный workspace/worktree: `<...>`. +- Контракт: `<ссылка>`; последний проверенный commit/revision: ``. -Документ обновляется как актуальный снимок состояния, а не дописывается как бесконечный журнал. +Не копируй сюда весь контракт или принятые решения. После завершения перенеси уникальное полезное содержание в его источник; необходимость хранения сводки пересмотри. diff --git a/templates/technical/node-service/README.md b/templates/technical/node-service/README.md new file mode 100644 index 0000000..c3c489c --- /dev/null +++ b/templates/technical/node-service/README.md @@ -0,0 +1,22 @@ +# Node service: настройки качества + +Подходит небольшому Node-сервису на TypeScript с нативными ESM. Для выбранного серверного фреймворка, монорепозитория, другого runtime или уже настроенного проекта сохраните его обычные средства. Материал не задаёт HTTP-фреймворк, БД, DI, очередь, мониторинг или развёртывание. + +## Как применить + +1. Объедините нужные части [tsconfig.json](tsconfig.json) и [eslint.config.mjs](eslint.config.mjs) со своими. [package.example.json](package.example.json) даёт пример зависимостей и команд с npm. Выбор package manager принадлежит проекту. +2. При `NodeNext` относительные импорты TypeScript используют расширение итогового файла `.js`; сборка выдаёт `dist/`. Не переносите сюда `Bundler` из клиентского приложения. +3. Блок `src/logic/**` — необязательный пример запрета платформенного доступа из чистых решений. Укажите фактическую область или удалите блок. Тесты этой области могут использовать Node runner. Новые алиасы, баррели и пакеты внешнего доступа требуют уточнения запретов; материал не является полным анализатором зависимостей. +4. Выполните `npm run check`: типы, линтер, сборка и встроенный Node test runner. В CI можно использовать ту же команду после воспроизводимой установки по lockfile. CI, запуск production и эксплуатационные механизмы выбираются отдельно по задаче. + +Демонстрационный HTTP-сценарий существует только в тесте материала. Не копируйте его как готовый сервер. Повторы внешних действий, хранение, отказ БД, восстановление и безопасность данных требуют проверок реального сценария сервиса. + +## Версии и сопровождение + +Проверяемая среда — Node 22.17.0 (22.13+ в этой линии), npm 11.19.0, TypeScript 5.9.3, ESLint 10.8.0, типы Node 22.15.30 и typescript-eslint 8.65.0. Для воспроизведения используйте npm 11, указанный в package. Это проверяемый пример, не обязательные версии будущего проекта. Другая major-версия или Node-линия требуют проверки. Нативный тестовый runner не добавляет отдельный фреймворк; он ищет скомпилированные `.test.js`, поэтому устаревший выход сборки не должен оставаться после переноса тестов. + +Из корня Kit: `node tests/templates/test-technical-materials.mjs` устанавливает зависимости в собственные временные каталоги, проверяет оба материала, успешное и ошибочное вычисление, HTTP-ответ через loopback, отказ неверного типа и запрещённых импортов. `--offline` ограничивает установку npm cache. Проверка не меняет рабочие продукты и не запускает внешнее развёртывание. + +После применения конфигурация и lockfile принадлежат проекту; синхронизация Kit их не меняет. При обновлении материала повторите прямой тест и проверьте изменения зависимости. Форматтер, hooks и инфраструктура CI не включены автоматически. + +Основания: [TypeScript module resolution](https://www.typescriptlang.org/tsconfig/moduleResolution.html), [Node test runner](https://nodejs.org/api/test.html), [typescript-eslint](https://typescript-eslint.io/getting-started/), [ограничения импортов ESLint](https://eslint.org/docs/latest/rules/no-restricted-imports). Ограничение динамической загрузки проверяется отдельным правилом синтаксиса. diff --git a/templates/technical/node-service/eslint.config.mjs b/templates/technical/node-service/eslint.config.mjs new file mode 100644 index 0000000..64076be --- /dev/null +++ b/templates/technical/node-service/eslint.config.mjs @@ -0,0 +1,26 @@ +import js from '@eslint/js'; +import tseslint from 'typescript-eslint'; +import { builtinModules } from 'node:module'; + +export default [ + { ignores: ['dist/**', '.ai-rules/**', '.agents/**', '.local/**'] }, + { files: ['src/**/*.ts'], ...js.configs.recommended }, + ...tseslint.configs.recommended, + // Optional example: pure decisions do not own HTTP or filesystem effects. + { + files: ['src/logic/**/*.ts'], + ignores: ['**/*.test.ts'], + rules: { + 'no-restricted-imports': ['error', { + patterns: [{ + group: ['node:*', ...builtinModules, '**/adapters/**', '**/server.js'], + message: 'Pure logic must not import platform adapters; pass data from the caller.' + }] + }], + 'no-restricted-syntax': ['error', + { selector: 'ImportExpression', message: 'Keep dynamic loading outside pure logic.' }, + { selector: "CallExpression[callee.name='require']", message: 'Keep runtime loading outside pure logic.' } + ] + } + } +]; diff --git a/templates/technical/node-service/package.example.json b/templates/technical/node-service/package.example.json new file mode 100644 index 0000000..a734bb1 --- /dev/null +++ b/templates/technical/node-service/package.example.json @@ -0,0 +1,21 @@ +{ + "name": "node-service-quality-example", + "private": true, + "type": "module", + "engines": { "node": ">=22.13 <23" }, + "packageManager": "npm@11.19.0", + "scripts": { + "build": "tsc", + "typecheck": "tsc --noEmit", + "lint": "eslint src", + "test": "npm run build && node --test", + "check": "npm run typecheck && npm run lint && npm test" + }, + "devDependencies": { + "@eslint/js": "10.0.1", + "@types/node": "22.15.30", + "eslint": "10.8.0", + "typescript": "5.9.3", + "typescript-eslint": "8.65.0" + } +} diff --git a/templates/technical/node-service/tsconfig.json b/templates/technical/node-service/tsconfig.json new file mode 100644 index 0000000..74625e9 --- /dev/null +++ b/templates/technical/node-service/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "lib": ["ES2022"], + "types": ["node"], + "strict": true, + "skipLibCheck": true, + "verbatimModuleSyntax": true, + "rootDir": "src", + "outDir": "dist" + }, + "include": ["src/**/*.ts"] +} diff --git a/templates/technical/vue-vite/README.md b/templates/technical/vue-vite/README.md new file mode 100644 index 0000000..fa0eb2a --- /dev/null +++ b/templates/technical/vue-vite/README.md @@ -0,0 +1,22 @@ +# Vue/Vite: настройки качества + +Подходит новому клиентскому Vue-приложению на TypeScript, когда нужны проверка SFC, тесты независимых вычислений и сборка. Для Nuxt, SSR, другого frontend-стека или существующей настроенной системы выберите её штатные средства. Материал не задаёт страницы, состояние, хранение, дизайн или структуру всех возможностей. + +## Как применить + +1. Создайте основу штатными средствами Vue/Vite или используйте существующую. Примените нужные части [tsconfig.json](tsconfig.json), [eslint.config.mjs](eslint.config.mjs) и [vite.config.mjs](vite.config.mjs), сохраняя настройки проекта. +2. [package.example.json](package.example.json) содержит команды и точные прямые версии проверяемого примера. Объедините нужные зависимости со своими, выполните установку выбранным package manager и сохраните lockfile по правилам проекта. Это пример с npm, а не обязательный менеджер. +3. Замените `src/logic/**` на реальную границу чистых вычислений или удалите этот блок, если граница не нужна. Не создавайте каталог ради настройки. Это ограничение импортов, не полный анализ графа: новые алиасы, баррели и внешние библиотеки требуют своего контракта и негативных примеров. +4. Выполните `npm run check`. В CI достаточно этой же команды после воспроизводимой установки зависимостей, если CI нужен в задаче. Workflow, hooks и деплой не создаются материалом. + +Линтер проверяет TypeScript и SFC. Vitest использует Node environment для чистой логики; DOM-взаимодействия, браузерные состояния, accessibility и качество дизайна проверяются отдельно подходящим инструментом. `vue-tsc` проверяет SFC, Vite собирает их. Форматтер не включён: сохраните принятый или добавьте нужный независимо. + +## Версии и сопровождение + +Проверяемая среда — Node 22.17.0 (зависимости требуют 22.13+ в этой линии), npm 11.19.0, TypeScript 5.9.3, Vue 3.5.43, Vite 7.3.6, Vitest 4.1.11, ESLint 10.8.0. Для воспроизведения используйте npm 11, указанный в package; npm 10 не входит в проверенную комбинацию. Остальные точные версии — в примере package. Это совместимая комбинация, не рекомендация выбирать старую версию вместо подходящей актуальной. Другая major-версия или Node-линия требуют проверки. + +Из корня Kit: `node tests/templates/test-technical-materials.mjs` проверяет оба материала на временных проектах: типы, SFC, тесты логики, сборку, разрешённые импорты и отказ статического импорта, реэкспорта и динамического загрузчика. `--offline` использует только npm cache. Зависимости, полученный lockfile и выход сборки остаются во временной среде; тест не меняет подключённые продукты. + +После применения настройки принадлежат проекту. Обновление Kit не обновляет их. При изменении примера проверяйте его совместимость прямым запуском; транзитивные версии закрепляются lockfile конкретного проекта. Для долговременного повторения проверки сохраняйте её временный lockfile как локальное свидетельство, а не добавляйте в Kit ещё одну матрицу стеков. + +Основания: [Vite](https://vite.dev/guide/), [TypeScript module resolution](https://www.typescriptlang.org/tsconfig/moduleResolution.html), [typescript-eslint](https://typescript-eslint.io/getting-started/), [ограничения импортов ESLint](https://eslint.org/docs/latest/rules/no-restricted-imports). Эти документы объясняют инструменты; фактическую комбинацию проверяет тест. diff --git a/templates/technical/vue-vite/eslint.config.mjs b/templates/technical/vue-vite/eslint.config.mjs new file mode 100644 index 0000000..6e2f722 --- /dev/null +++ b/templates/technical/vue-vite/eslint.config.mjs @@ -0,0 +1,27 @@ +import js from '@eslint/js'; +import tseslint from 'typescript-eslint'; +import vue from 'eslint-plugin-vue'; + +export default [ + { ignores: ['dist/**', '.cache/**', '.ai-rules/**', '.agents/**', '.local/**'] }, + { files: ['src/**/*.ts'], ...js.configs.recommended }, + ...tseslint.configs.recommended, + ...vue.configs['flat/recommended'], + { files: ['src/**/*.vue'], languageOptions: { parserOptions: { parser: tseslint.parser } } }, + // Optional example: apply only when pure calculations are a real boundary. + { + files: ['src/logic/**/*.ts'], + rules: { + 'no-restricted-imports': ['error', { + patterns: [{ + group: ['vue', 'vue/**', '*.vue', '**/*.vue', '**/ui/**', '@/ui/**'], + message: 'Pure logic must not import Vue or UI; pass values from the caller.' + }] + }], + 'no-restricted-syntax': ['error', + { selector: 'ImportExpression', message: 'Keep dynamic loading outside pure logic.' }, + { selector: "CallExpression[callee.name='require']", message: 'Keep runtime loading outside pure logic.' } + ] + } + } +]; diff --git a/templates/technical/vue-vite/package.example.json b/templates/technical/vue-vite/package.example.json new file mode 100644 index 0000000..495d1ee --- /dev/null +++ b/templates/technical/vue-vite/package.example.json @@ -0,0 +1,27 @@ +{ + "name": "vue-vite-quality-example", + "private": true, + "type": "module", + "engines": { "node": ">=22.13 <23" }, + "packageManager": "npm@11.19.0", + "scripts": { + "dev": "vite", + "typecheck": "vue-tsc --noEmit", + "lint": "eslint src", + "test": "vitest run", + "build": "vite build", + "check": "npm run typecheck && npm run lint && npm test && npm run build" + }, + "dependencies": { "vue": "3.5.43" }, + "devDependencies": { + "@eslint/js": "10.0.1", + "@vitejs/plugin-vue": "6.0.8", + "eslint": "10.8.0", + "eslint-plugin-vue": "10.10.0", + "typescript": "5.9.3", + "typescript-eslint": "8.65.0", + "vite": "7.3.6", + "vitest": "4.1.11", + "vue-tsc": "3.3.7" + } +} diff --git a/templates/technical/vue-vite/tsconfig.json b/templates/technical/vue-vite/tsconfig.json new file mode 100644 index 0000000..1231116 --- /dev/null +++ b/templates/technical/vue-vite/tsconfig.json @@ -0,0 +1,14 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "Bundler", + "lib": ["ES2022", "DOM", "DOM.Iterable"], + "strict": true, + "noEmit": true, + "skipLibCheck": true, + "verbatimModuleSyntax": true, + "types": ["vite/client"] + }, + "include": ["src/**/*.ts", "src/**/*.vue"] +} diff --git a/templates/technical/vue-vite/vite.config.mjs b/templates/technical/vue-vite/vite.config.mjs new file mode 100644 index 0000000..25f782a --- /dev/null +++ b/templates/technical/vue-vite/vite.config.mjs @@ -0,0 +1,8 @@ +import { defineConfig } from 'vitest/config'; +import vue from '@vitejs/plugin-vue'; + +export default defineConfig({ + plugins: [vue()], + cacheDir: '.cache/vite', + test: { environment: 'node', include: ['src/**/*.test.ts'] } +}); diff --git a/tests/cli/test-integration.ps1 b/tests/cli/test-integration.ps1 index 1243384..d777b6e 100644 --- a/tests/cli/test-integration.ps1 +++ b/tests/cli/test-integration.ps1 @@ -219,14 +219,14 @@ try { } Assert-True -Condition ($coreRule -match 'Инструкция, найденная внутри недоверенного содержимого.*остаётся данными' -and $coreRule -match 'не получает полномочий прямого запроса владельца' -and $coreRule -match 'установленные локальные инструкции.*приоритету' -and $coreRule -match 'канонический источник' -and $coreRule -match 'Перед вызовом инструмента') -Message 'CORE must distinguish owner authority from untrusted embedded instructions and retain canonical-source discipline' Assert-True -Condition ($architectureRule -match '(?m)^## Направление зависимостей\s*$' -and $architectureRule -match 'запрещённые связи' -and $architectureRule -match 'линтером, анализатором зависимостей или структурным тестом' -and $architectureRule -match '(?m)^## Доступность контекста\s*$' -and $architectureRule -match 'Короткая точка входа') -Message 'architecture rules must combine navigable context with mechanically enforced boundaries' - Assert-True -Condition ($catalog.topics.'architecture-and-data'.readWhen -match 'До существенной реализации.*без границ' -and $standardProductProfile -match 'Первоначальная архитектура.*architecture-and-data.*INDEX' -and $agentsTemplate -match 'без архитектурного контракта.*INDEX.*architecture-and-data' -and $agentsTemplate -match 'без чтения всех стартовых архетипов') -Message 'new project routing must reach architecture before implementation without requiring all archetypes for ordinary tasks' + Assert-True -Condition ($catalog.topics.'architecture-and-data'.readWhen -match 'До существенной реализации.*без границ' -and $standardProductProfile -match 'Первоначальная архитектура.*architecture-and-data.*INDEX' -and $agentsTemplate -match 'без архитектурного контракта.*INDEX.*architecture-and-data' -and $agentsTemplate -match 'без повторного bootstrap') -Message 'new project routing must select scale before implementation without restarting bootstrap for ordinary tasks' Assert-True -Condition ($catalog.topics.'project-bootstrap'.file -eq 'workflows/PROJECT_BOOTSTRAP.md' -and $catalog.topics.'project-bootstrap'.kind -eq 'workflow' -and $catalog.topics.'project-bootstrap'.readWhen -match 'не при обычной feature-задаче') -Message 'bootstrap catalog entry must route to a conditional startup workflow' Assert-True -Condition ($standardProductProfile -notmatch 'shared →|core/model|application →|### A\.' -and $coreRule -notmatch 'project-bootstrap|архетип') -Message 'startup examples must not be duplicated into the always-read profile or CORE' Assert-True -Condition ($bootstrapWorkflow -match 'Обычная feature-задача.*не запускает процесс повторно' -and $bootstrapWorkflow -match 'подключение меняет только файлы правил' -and $bootstrapWorkflow -match 'После выбора читай локальный контракт' -and $projectRulesTemplate -match 'Где размещать новый код' -and $fullProjectRulesTemplate -match 'Новый код.*Владелец и точный путь') -Message 'bootstrap must hand subsequent work to local placement contracts and preserve adoption scope' Assert-True -Condition ($researchRule -match 'сначала определи владельца контракта и его канонический источник' -and $researchRule -match 'Для поведения, которым владеет проект' -and $researchRule -match 'Для внешнего API.*официальную спецификацию' -and $researchRule -match 'выполнение.*не заменяет нормативный контракт') -Message 'research rules must select normative evidence by contract ownership and separate actual behavior from the contract' Assert-True -Condition ($projectConnectPrompt -match 'минимальный набор профилей и тем' -and $projectConnectPrompt -match 'Остановись перед `-Apply`' -and $projectConnectPrompt -match 'не выполняй `commit`, `push`' -and $projectConnectPrompt -match '\{\{PROJECT_ROOT\}\}' -and $projectConnectPrompt -match '\{\{HUB_CLI_PATH\}\}') -Message 'project connect prompt must guide minimal selection, explicit approval, and external-action boundaries' Assert-True -Condition ($projectAuditPrompt -match 'Этап 1 — завершение подключения' -and $projectAuditPrompt -match 'явно сообщи, что подключение завершено' -and $projectAuditPrompt -match 'Этап 2 — проверка только для чтения' -and $projectAuditPrompt -match 'После этого не меняй файлы проекта' -and $projectAuditPrompt -match '`satisfied`, `gap`, `not applicable` или `unknown`' -and $projectAuditPrompt -match 'отдельные задачи на исправление, но не выполняй их') -Message 'project audit prompt must separate adoption changes from the read-only project review' - Assert-True -Condition ($projectAuditPrompt -match 'похожие сценарии, экраны и операции' -and $projectAuditPrompt -match 'не исправлен ли только один вариант' -and $projectAuditPrompt -match 'путь нового разработчика' -and $projectAuditPrompt -match 'Большой файл сам по себе не доказывает разрыв.*независимых причин изменения' -and $projectAuditPrompt -match 'повторяющиеся разрывы по классам') -Message 'project audit prompt must compare analogous scenarios, assess responsibilities during human onboarding, and group repeated gaps by system layer' + Assert-True -Condition ($projectAuditPrompt -match 'все установленные темы читать не нужно' -and $projectAuditPrompt -match 'Отсутствие отдельной карты или guard само по себе не дефект' -and $projectAuditPrompt -match 'полный аудит не входит в подключение') -Message 'connection review must remain task-scoped without a mandatory architecture audit or document set' $agentFacingText = @($agentsTemplate, $rulesetTemplate, $projectConnectPrompt, $projectAuditPrompt, $projectDeepAuditPrompt, $projectAuditWorkflow, (Get-Content -LiteralPath (Join-Path $hubRoot 'src/EffectiveIndex.psm1') -Raw -Encoding UTF8), (Get-Content -LiteralPath (Join-Path $hubRoot 'sync/catalog.json') -Raw -Encoding UTF8)) -join "`n" Assert-True -Condition ($agentFacingText -notmatch '(?i)project-owned|initializer|managed-файл|effective-набор|profiles и topics|проектный status|\brevision\b|AI-агент|AI-инструмент|\bUI\b') -Message 'agent-facing text must avoid unnecessary English words in Russian prose' $userReadme = @($rootReadme -split '(?m)^## Kit development\s*$', 2)[0] @@ -278,7 +278,7 @@ try { Assert-True -Condition ($deepAuditPromptResult.ExitCode -eq 0 -and $deepAuditPromptResult.Output -match '^Подготовь и проведи глубокий аудит проекта' -and $deepAuditPromptResult.Output -match 'опорного инвентаря' -and $deepAuditPromptResult.Output.Contains($promptProjectRoot) -and $deepAuditPromptResult.Output.Contains($cliPath) -and $deepAuditPromptResult.Output -notmatch '\{\{|```') -Message 'CLI must print a project-specific deep-audit prompt with the inventory route' $studyPromptSnapshot = Get-TreeSnapshot -Root $promptProjectRoot $bootstrapPromptResult = Invoke-HubScript -ScriptPath $cliPath -Arguments @('prompt', 'bootstrap', '-ProjectRoot', $promptProjectRoot) - Assert-True -Condition ($bootstrapPromptResult.ExitCode -eq 0 -and $bootstrapPromptResult.Output -match '^Подготовь первоначальную архитектуру проекта' -and $bootstrapPromptResult.Output.Contains($promptProjectRoot) -and $bootstrapPromptResult.Output.Contains($cliPath) -and $bootstrapPromptResult.Output.Contains((Join-Path $hubRoot 'workflows/PROJECT_BOOTSTRAP.md')) -and $bootstrapPromptResult.Output -notmatch '\{\{|```') -Message 'bootstrap prompt must resolve project and workflow paths, including spaces, without wrappers or placeholders' + Assert-True -Condition ($bootstrapPromptResult.ExitCode -eq 0 -and $bootstrapPromptResult.Output -match '^Создай работающую основу проекта' -and $bootstrapPromptResult.Output.Contains($promptProjectRoot) -and $bootstrapPromptResult.Output.Contains($cliPath) -and $bootstrapPromptResult.Output.Contains((Join-Path $hubRoot 'workflows/PROJECT_BOOTSTRAP.md')) -and $bootstrapPromptResult.Output -notmatch '\{\{|```') -Message 'bootstrap prompt must resolve project and workflow paths, including spaces, without wrappers or placeholders' Assert-True -Condition ((Get-TreeSnapshot -Root $promptProjectRoot) -eq $studyPromptSnapshot) -Message 'rendering bootstrap must not initialize the project or generate a skeleton' $bootstrapMissingRoot = Invoke-HubScript -ScriptPath $cliPath -Arguments @('prompt', 'bootstrap') Assert-True -Condition ($bootstrapMissingRoot.ExitCode -ne 0 -and $bootstrapMissingRoot.Output -match 'ProjectRoot') -Message 'bootstrap must require an explicit project root' @@ -556,6 +556,7 @@ try { Assert-True -Condition (-not (Test-Path -LiteralPath (Join-Path $upstreamRoot 'workflows/PROJECT_DEEP_AUDIT.md'))) -Message 'sync must not copy project-audit without an explicit selection' Assert-True -Condition (-not (Test-Path -LiteralPath (Join-Path $upstreamRoot 'workflows/PARALLEL_DELIVERY.md'))) -Message 'sync must not copy parallel-delivery without an explicit selection' Assert-True -Condition (-not (Test-Path -LiteralPath (Join-Path $upstreamRoot 'workflows/PROJECT_BOOTSTRAP.md'))) -Message 'standard-product sync must not copy bootstrap without explicit selection' + Assert-True -Condition (-not (Test-Path -LiteralPath (Join-Path $upstreamRoot 'templates'))) -Message 'rule synchronization must never apply optional technical materials to project code' Assert-True -Condition (-not (Test-Path -LiteralPath (Join-Path $upstreamRoot 'workflows/VISUAL_DESIGN_DISCOVERY.md'))) -Message 'standard-product must not install discovery for ordinary feature work' Assert-True -Condition (Test-Path -LiteralPath (Join-Path $upstreamRoot 'rules/RELIABILITY_AND_OPERATIONS.md')) -Message 'sync must copy explicitly selected reliability topic' Assert-True -Condition (Test-Path -LiteralPath $lockPath) -Message 'apply must create lock' diff --git a/tests/policy-structure/test-portable-boundaries.ps1 b/tests/policy-structure/test-portable-boundaries.ps1 index e97e5cd..e717037 100644 --- a/tests/policy-structure/test-portable-boundaries.ps1 +++ b/tests/policy-structure/test-portable-boundaries.ps1 @@ -34,6 +34,14 @@ if ($quality -notmatch 'ожидание `expect` < лимит теста < ли if ($learningProfile -notmatch 'устойчивой частью' -or $learningProfile -notmatch 'разового изучения') { throw 'Learning profile must describe a stable project property rather than a task workflow.' } if ($readme -match '## Detailed connection workflow|## Synchronization states|## Repository structure') { throw 'Public README must remain a short external entry point.' } +# A persistent project may stay small; platform examples do not select architecture. +$bootstrap = Get-Content -LiteralPath (Join-Path $hubRoot 'workflows/PROJECT_BOOTSTRAP.md') -Raw -Encoding UTF8 +$product = Get-Content -LiteralPath (Join-Path $hubRoot 'rules/PRODUCT.md') -Raw -Encoding UTF8 +$discovery = Get-Content -LiteralPath (Join-Path $hubRoot 'workflows/VISUAL_DESIGN_DISCOVERY.md') -Raw -Encoding UTF8 +if ($architecture -match 'Выбери один стартовый архетип' -or $bootstrap -match 'Выбери один минимальный архетип') { throw 'Kit must not require choosing from a closed architecture list.' } +if ($bootstrap -notmatch 'Если конкретная основа и план уже одобрены' -or $bootstrap -notmatch 'до зависимой реализации' -or $bootstrap -notmatch 'Для продукта без графического интерфейса') { throw 'Bootstrap must preserve plan approval, prior authorization and the headless design exemption.' } +if ($product -match '4–6|минимум два' -or $discovery -match 'минимум 2|2–3 направления') { throw 'Visual selection must not impose reference or alternative quotas.' } + # Routing metadata must preserve the action gates without making every read a workflow. $agents = Get-Content -LiteralPath (Join-Path $hubRoot 'templates/AGENTS.md') -Raw -Encoding UTF8 $taskStart = $agents.IndexOf('Сначала прочитай запрос владельца') diff --git a/tests/templates/test-technical-materials.mjs b/tests/templates/test-technical-materials.mjs new file mode 100644 index 0000000..eeba122 --- /dev/null +++ b/tests/templates/test-technical-materials.mjs @@ -0,0 +1,175 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { dirname, join, relative, resolve, sep } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const hubRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); +const temporaryBase = resolve(tmpdir()); +const fixtureRoot = mkdtempSync(join(temporaryBase, 'aek-materials-')); +const offline = process.argv.includes('--offline'); + +function write(root, path, content) { + const destination = join(root, path); + mkdirSync(dirname(destination), { recursive: true }); + writeFileSync(destination, content); +} + +function run(root, executable, args, expectedSuccess = true) { + const npmCli = executable === 'npm' ? process.env.npm_execpath : undefined; + const command = npmCli ? process.execPath : executable; + const commandArgs = npmCli ? [npmCli, ...args] : args; + const result = spawnSync(command, commandArgs, { + cwd: root, encoding: 'utf8', timeout: 180_000, + // Only fixed npm commands use the Windows command shim; paths use cwd. + shell: process.platform === 'win32' && command === 'npm' + }); + assert.ifError(result.error); + const output = `${result.stdout ?? ''}${result.stderr ?? ''}`; + assert.equal(result.status === 0, expectedSuccess, `${executable} ${args.join(' ')}\n${output}`); + return output; +} + +function prepare(name) { + const root = join(fixtureRoot, name); + cpSync(join(hubRoot, 'templates/technical', name), root, { recursive: true }); + write(root, 'package.json', readFileSync(join(root, 'package.example.json'), 'utf8')); + const npmVersion = run(root, 'npm', ['--version']).trim(); + assert(Number(npmVersion.split('.')[0]) >= 11, 'Use npm 11 for this verified combination; npm_execpath can point to its npm-cli.js without changing the global installation.'); + console.log(`${name}: installing exact direct dependencies in a temporary fixture`); + run(root, 'npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', ...(offline ? ['--offline'] : [])]); + return root; +} + +function probeBoundaries(root, examples) { + const probePath = 'src/logic/forbidden.ts'; + const eslint = join(root, 'node_modules/eslint/bin/eslint.js'); + for (const [source, rule] of examples) { + write(root, probePath, source); + const result = run(root, process.execPath, [eslint, probePath, '--format', 'json'], false); + const messages = JSON.parse(result)[0].messages; + assert(messages.some(message => message.ruleId === rule), `Expected ${rule} for ${source}`); + } + rmSync(join(root, probePath)); +} + +function probeTypes(root, command) { + const path = 'src/invalid-type.ts'; + write(root, path, 'export const invalid: string = 7;\n'); + const output = run(root, process.execPath, command, false); + assert(output.includes('TS2322'), 'Type checking must reject an actual incompatible assignment'); + rmSync(join(root, path)); +} + +try { + const vue = prepare('vue-vite'); + write(vue, 'index.html', '
\n'); + write(vue, 'src/main.ts', "import { createApp } from 'vue';\nimport App from './App.vue';\ncreateApp(App).mount('#app');\n"); + write(vue, 'src/App.vue', ` + +`); + write(vue, 'src/logic/count.ts', `export function formatCount(count: number): string { + if (!Number.isInteger(count) || count < 0) throw new Error('Invalid count'); + return String(count); +} +`); + write(vue, 'src/logic/count.test.ts', `import { expect, test } from 'vitest'; +import { formatCount } from './count'; +test('count preserves zero and rejects invalid input', () => { + expect(formatCount(0)).toBe('0'); + expect(formatCount(2)).toBe('2'); + expect(() => formatCount(-1)).toThrow('Invalid count'); + expect(() => formatCount(1.5)).toThrow('Invalid count'); +}); +`); + const vueChecks = run(vue, 'npm', ['run', 'check']); + assert(vueChecks.includes('1 passed'), 'Vitest must run the actual behavior test'); + assert(existsSync(join(vue, 'dist/index.html')), 'Vite must build the actual SFC entry point'); + probeBoundaries(vue, [ + ["import { ref } from 'vue'; export const value = ref(0);", 'no-restricted-imports'], + ["export { ref } from 'vue';", 'no-restricted-imports'], + ["export const load = () => import('vue');", 'no-restricted-syntax'], + ["export { default } from '../App.vue';", 'no-restricted-imports'] + ]); + probeTypes(vue, [join(vue, 'node_modules/vue-tsc/bin/vue-tsc.js'), '--noEmit']); + write(vue, 'src/Invalid.vue', ''); + const invalidSfc = run(vue, process.execPath, [join(vue, 'node_modules/vue-tsc/bin/vue-tsc.js'), '--noEmit'], false); + assert(invalidSfc.includes('Invalid.vue') && invalidSfc.includes('TS2322'), 'SFC type errors must also be observed'); + rmSync(join(vue, 'src/Invalid.vue')); + console.log('vue-vite: types, SFC lint/build, behavior and boundary rejection passed'); + + const service = prepare('node-service'); + write(service, 'src/logic/label.ts', `export function normalizeLabel(input: string): string { + const value = input.trim(); + if (!value) throw new Error('Empty label'); + return value; +} +`); + write(service, 'src/server.ts', `import { createServer } from 'node:http'; +import { normalizeLabel } from './logic/label.js'; +export function createLabelServer() { + return createServer((request, response) => { + const value = new URL(request.url ?? '/', 'http://localhost').searchParams.get('label'); + try { + response.setHeader('Content-Type', 'application/json'); + response.end(JSON.stringify({ label: normalizeLabel(value ?? '') })); + } catch { + response.writeHead(400).end(JSON.stringify({ error: 'Invalid label' })); + } + }); +} +`); + write(service, 'src/logic/label.test.ts', `import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { normalizeLabel } from './label.js'; +test('normalization preserves data and rejects an empty label', () => { + assert.equal(normalizeLabel(' hello '), 'hello'); + assert.throws(() => normalizeLabel(' '), /Empty label/); +}); +`); + write(service, 'src/server.test.ts', `import assert from 'node:assert/strict'; +import { once } from 'node:events'; +import { test } from 'node:test'; +import { createLabelServer } from './server.js'; +test('HTTP returns the normalized label and a truthful invalid-input response', { timeout: 10_000 }, async t => { + const server = createLabelServer(); + t.after(() => new Promise((resolve, reject) => { + server.close(error => error ? reject(error) : resolve()); + })); + server.listen(0, '127.0.0.1'); + await once(server, 'listening'); + const address = server.address(); + assert(address && typeof address !== 'string'); + const base = 'http://127.0.0.1:' + address.port; + const response = await fetch(base + '/?label=%20hello%20'); + assert.equal(response.status, 200); + assert.deepEqual(await response.json(), { label: 'hello' }); + const invalid = await fetch(base + '/?label=%20'); + assert.equal(invalid.status, 400); + assert.deepEqual(await invalid.json(), { error: 'Invalid label' }); +}); +`); + const serviceChecks = run(service, 'npm', ['run', 'check']); + assert(serviceChecks.includes('# pass 2'), 'Node must discover both the logic and HTTP tests'); + probeBoundaries(service, [ + ["import { readFile } from 'node:fs'; export { readFile };", 'no-restricted-imports'], + ["import { readFile } from 'fs'; export { readFile };", 'no-restricted-imports'], + ["export { createLabelServer } from '../server.js';", 'no-restricted-imports'], + ["export const load = () => import('node:fs');", 'no-restricted-syntax'] + ]); + probeTypes(service, [join(service, 'node_modules/typescript/bin/tsc'), '--noEmit']); + console.log('node-service: types, lint, native tests, HTTP and boundary rejection passed'); + console.log('Both technical materials passed. This does not verify product design, deployment or bootstrap speed.'); +} finally { + // mkdtemp created this directory. Verify its absolute boundary before removal. + const withinTemp = relative(temporaryBase, fixtureRoot); + assert(withinTemp.startsWith('aek-materials-') && !withinTemp.includes(sep)); + assert.equal(dirname(fixtureRoot), temporaryBase); + if (process.argv.includes('--keep')) console.log(`Temporary evidence retained: ${fixtureRoot}`); + else rmSync(fixtureRoot, { recursive: true, force: false }); +} diff --git a/workflows/PROJECT_AUDIT_PROMPT.md b/workflows/PROJECT_AUDIT_PROMPT.md index 9af1be2..ba01353 100644 --- a/workflows/PROJECT_AUDIT_PROMPT.md +++ b/workflows/PROJECT_AUDIT_PROMPT.md @@ -1,39 +1,30 @@ # Завершение подключения и первичная проверка -Используйте этот запрос после `init` и первого `update -Apply`. Откройте ИИ-агента в корне проекта. Общие правила уже находятся в `.ai-rules/upstream/`; копировать их в локальные файлы не нужно. +Используйте после `init` и первого `update -Apply`, если локальные правила ещё нужно уточнить. Повторять после каждого обновления не требуется. Это проверка подключения и доступного контекста; полный аудит запускается отдельно через `prompt deep-audit`. ## Готовый запрос ```text -Заверши подключение Agent Engineering Kit, зафиксируй границу изменений и проверь проект по подключённым правилам. +Заверши подключение Agent Engineering Kit и проверь, можно ли продолжать работу с коротким достоверным контекстом. Границы задачи: - можно менять только `AGENTS.md`, `.ai-rules/RULESET.md` и `.ai-rules/PROJECT_RULES.md`; - остальные файлы используй только для чтения; -- не выполняй `commit`, `push`, публикацию, удаление и исправление найденных разрывов; +- не выполняй commit, push, публикацию, удаление и исправление найденных разрывов; - сохрани несвязанные изменения владельца. Этап 1 — завершение подключения: -1. Проверь `git status` и локальные инструкции. -2. Прочитай `.ai-rules/manifest.json`, `.ai-rules/lock.json`, `RULESET.md`, `PROJECT_RULES.md`, `CORE.md`, выбранные профили и все темы подключённого набора. -3. Изучай проект постепенно. Начни с точек входа и карт документации, затем читай только связанные настройки, документы, код и тесты. -4. Не копируй общие правила из `.ai-rules/upstream/`. В `AGENTS.md` оставь короткий маршрут. В `PROJECT_RULES.md` запиши только особенности проекта. В `RULESET.md` запиши причины выбора, исключения и известные разрывы. -5. Заполняй незаполненные места только подтверждёнными данными. Если источник или проверка отсутствует, укажи `не установлен` или `не установлена`. Не создавай для этого новые документы, инструменты или автоматические проверки. -6. Покажи изменения трёх разрешённых файлов и явно сообщи, что подключение завершено. После этого не меняй файлы проекта. +1. Проверь git status, локальные инструкции, manifest.json и lock.json, затем RULESET.md, PROJECT_RULES.md, CORE.md, INDEX.md и выбранные профили. Читай только темы, нужные для проверки подключения, хранения контекста и полномочий; все установленные темы читать не нужно. +2. Найди существующие точки входа, команды запуска и проверки, места для кода и значимых решений. Читай связанные источники постепенно, без полного обзора кодовой базы. +3. В AGENTS.md оставь маршрут, в PROJECT_RULES.md — особенности и команды, в RULESET.md — выбор, исключения и подтверждённые разрывы. Не копируй общие правила и не создавай карту, ADR, guard или CI ради подключения. Незнакомое отмечай как не установлен / не установлена. +4. Покажи изменения разрешённых файлов и явно сообщи, что подключение завершено. После этого не меняй файлы проекта. Этап 2 — проверка только для чтения: -7. Для каждого значимого пункта используй один точный статус: `satisfied`, `gap`, `not applicable` или `unknown`. Подтверди вывод файлом, настройкой, командой или наблюдаемым поведением. -8. Проверь архитектурные границы, источники истины, безопасность данных и ИИ-инструментов, публичность документов, проверки проекта, правила сообщений коммитов и основной язык текста. -9. Сравни похожие сценарии, экраны и операции. Проверь, не исправлен ли только один вариант и не нужен ли общий механизм или парная проверка. -10. Оцени путь нового разработчика: точку входа, запуск, карту архитектуры, источники истины, маршрут размещения нового кода и команды проверки границ. Большой файл сам по себе не доказывает разрыв; проверь несколько независимых причин изменения. У существующего проекта отсутствие контракта или guard фиксируй без рефакторинга. Для нового развиваемого проекта укажи отдельный первоначальный выбор через `prompt bootstrap` до существенной реализации. -11. Если команда хаба доступна, выполни `doctor` и `status`. Остальные проверки запускай только тогда, когда они не меняют исходные файлы и не оставляют временные данные. - -В результате покажи: -- какие из трёх разрешённых файлов изменены и зачем; -- краткую таблицу проверки, начиная с рисков безопасности, данных и критического поведения; -- повторяющиеся разрывы по классам и самый узкий слой исправления; -- неизвестное и способ его проверки; -- отдельные задачи на исправление, но не выполняй их. +5. Если команда хаба доступна, выполни doctor и status. Проверь маршрут чтения, точную закреплённую версию, сохранность локальных правил и отсутствие ручной правки upstream. Для публичного проекта проверь local-only, границу публикации и восстановление уникального контекста. +6. Проверь доступность команд запуска и проверки, существующего размещения кода и существенных ограничений для первого запроса. Отсутствие отдельной карты или guard само по себе не дефект. Код, архитектуру и похожие сценарии изучай глубже только при конкретном сигнале риска; полный аудит не входит в подключение. +7. Для значимых пунктов используй `satisfied`, `gap`, `not applicable` или `unknown` с подтверждением. Найденные проблемы отделяй от неизвестного. Остальные проверки запускай только если они не меняют исходные файлы и не оставляют временные данные. + +Кратко покажи результат подключения, изменённые файлы, предупреждения и неизвестное. При необходимости укажи отдельные задачи на исправление, но не выполняй их. Новый проект без основы начинает с prompt bootstrap; существующий продолжает свою работу без автоматического рефакторинга. ``` -Точные английские статусы нужны для сравнения результатов разных проектов. Остальной отчёт пишется на основном языке проекта. +Точные английские статусы сохраняют совместимость прежних отчётов; остальной текст — на языке проекта. diff --git a/workflows/PROJECT_BOOTSTRAP.md b/workflows/PROJECT_BOOTSTRAP.md index 921dc16..1b0ebd3 100644 --- a/workflows/PROJECT_BOOTSTRAP.md +++ b/workflows/PROJECT_BOOTSTRAP.md @@ -1,81 +1,68 @@ -# Первоначальная архитектура проекта +# Работающая основа проекта ## Когда применять -Применяй при создании развиваемого проекта, крупного package/application или подсистемы без установленных границ. Обычная feature-задача использует локальный контракт и не запускает процесс повторно. Для одноразового кода действуют исключения раздела «Первоначальная архитектура» темы `architecture-and-data`. +Используй при старте нового программного проекта или согласованной крупной подсистемы без установленной основы. Обычная feature-задача использует локальный контракт и не запускает процесс повторно. Подход подходит приложениям, сервисам, играм, мобильным продуктам, CLI, библиотекам, автоматизации и обработке данных; готовый пример для стека не обязателен. -Обязанность раннего выбора задана архитектурным правилом. Этот процесс помогает выполнить её; архетипы ниже — стартовые модели, а не дополнительный нормативный слой или обязательные имена каталогов. +`prompt bootstrap -ProjectRoot <путь>` только печатает запрос для существующего каталога. Он не создаёт проект, не устанавливает зависимости и не запускает генератор. Процесс выполняет агент после чтения запроса. `project-bootstrap` можно явно выбрать через `-Topics`, но профиль не устанавливает его автоматически. Читать процесс прямо из хаба достаточно. -## Запуск и контекст +## 1. Понять первый результат -В хабе выполни `prompt bootstrap -ProjectRoot <путь>` и передай запрос агенту вместе с целью и первым сценарием. Команда только печатает запрос. Можно также явно выбрать `project-bootstrap` через `-Topics` при подключении нового проекта; ни один профиль не устанавливает процесс автоматически. В подключённом проекте изменение состава проходит обычный план и разрешённый `-Apply`, без ручной правки upstream или lock. +Прочитай локальные инструкции, проверь Git, существующий код, настройки и доступные проверки. Уточни только недостающие сведения, влияющие на решение: идею, первый полноценный сценарий, пользователя или оператора, платформу, данные, внешние эффекты и ограничения. Не заставляй владельца повторять известное или отвечать на анкету обо всех будущих функциях. -`prompt connect` распознаёт новый проект и предлагает этот следующий шаг, но само подключение меняет только файлы правил. У существующего проекта отсутствующие границы остаются разрывом для отдельной задачи; bootstrap не разрешает перестройку соседних модулей. +Отдели новый проект от существующего. Подключение Kit само по себе не разрешает рефакторинг, создание guard, CI или переработку дизайна. В существующей области используй действующие решения; разрывы вне задачи назови отдельно. -Прочитай локальные инструкции и релевантные правила архитектуры, реализации, качества и документации. В неподключённом проекте используй их из указанного хаба; установка правил не является условием чтения. После выбора читай локальный контракт и решения затронутой области, без повторного чтения всех архетипов. +## 2. Выбрать подходящую основу -## 1. Определить сценарии и масштаб +Масштаб и границы определяет [архитектурное правило](../rules/ARCHITECTURE_AND_DATA.md#первоначальная-архитектура). Начни с соглашений платформы и официальных инструментов выбранной технологии. Учитывай ближайшие подтверждённые изменения, а не гипотетический рост. -Проверь Git, существующий код, настройки и команды проверки. Назови первый сквозной результат, ближайшие реальные сценарии, владельцев состояния и внешние границы. Отдели новый проект от установленной архитектуры и эксперимент с одной обязанностью от запланированного продукта. Не проектируй гипотетические функции. +- Связная утилита может остаться тремя файлами даже при длительном использовании. +- Несколько самостоятельных возможностей приложения получают владельцев; локальное состояние остаётся рядом с интерфейсом, независимые вычисления отделяются по контракту. +- Интеграционный сервис с повторами и сохраняемыми данными требует явных границ сценария, внешнего эффекта и хранения. +- Для игры или мобильной платформы используй её модель выполнения, ресурсов и развёртывания. Структура веб-приложения не является универсальной. -## 2. Выбрать один архетип +Это примеры рассуждения, а не список архитектур. Сравни альтернативы только при существенном или дорогом в изменении выборе: например, облачное хранение против локального, платформа выпуска или публичный контракт. Рекомендуй подходящий вариант первым; не строй несколько проектов ради сравнения. -| Тип | Начальная модель | Когда усложнять | -| --- | --- | --- | -| Пользовательский frontend | Композиция → локальные возможности → общий код | Модель, состояние или адаптер имеют независимый контракт либо нужны нескольким областям | -| Сервис / интеграционная система | Сценарии → contracts/model; adapters → contracts | Самостоятельная capability получает модуль; локальные уровни появляются по ответственности | -| Библиотека / CLI | Связное ядро; координация и adapters при реальных внешних границах | Второй сценарий, иной adapter или самостоятельный публичный контракт | +Для графического интерфейса выбери направление по [PRODUCT](../rules/PRODUCT.md#визуальное-направление-до-реализации). Без графического интерфейса этот шаг не применяется. -### A. Пользовательский frontend +## 3. Показать план и получить решение -Пример областей: `app/` для композиции, `features/` для сценариев, `shared/` для подтверждённо общего кода. Импорты: `app → features → shared`, также `app → shared`; запрещены `shared → features/app` и `features → app`. Переходы между возможностями получают явные точки входа по локальному контракту; универсальный запрет не требуется. +Объясни простыми словами, что будет работать после первого шага, почему выбранные средства подходят, какие данные сохраняются и как проверить результат. Назови существенные ограничения, необходимую ручную работу и важный компромисс. Нескольким файлам не нужен отдельный архитектурный отчёт. -Одной возможности достаточно `features/comparison/Comparison.vue`. При самостоятельных расчётах подходит `features/comparison/ui/Comparison.vue` и `features/comparison/model/comparison.ts` с локальным тестом. Не создавай заранее `api/model/ui/hooks/types/utils` в каждой возможности. +До зависимой реализации получи одобрение этой основы. Если конкретная основа и план уже одобрены в текущей задаче, продолжай без повторного разрешения. Установка зависимостей и подключение Kit могут войти в этот план; внешние действия, commit, push и публикация сохраняют собственные границы полномочий. -Общий API-клиент может находиться в `shared/api/`, клиент одной возможности — рядом с ней. Общая модель, `services`, `stores` и route adapters появляются только с реальным владельцем; модель не зависит от UI и хранилища. Не выноси каждый локальный `computed` или обработчик из компонента. Корневые entrypoints делегируют самостоятельные сценарии их владельцам. +## 4. Применить только полезные материалы -### B. Сервис / backend +Проверь, есть ли подходящий материал в [templates/README.md](../templates/README.md#технические-материалы). Прочитай условия применения и совместимые версии только выбранного материала. Используй отдельную настройку, фрагмент или команду, когда это экономит повторную работу. При несовместимости предложи более подходящее решение и кратко объясни причину; отсутствие примера нормально. -Пример областей: `core/model`, `core/application`, `core/contracts`, `infrastructure/` и `modules//`. Core содержит общие предметные правила и сценарии, contracts/ports — внешние зависимости; infrastructure реализует конкретные HTTP, messaging и persistence adapters. Точка композиции создаёт adapters и передаёт их application через contracts. +Не перезаписывай существующую конфигурацию. Применённый материал принадлежит проекту и не обновляется синхронизацией правил. Не копируй демонстрационные сценарии, все файлы примера или слои выпущенного продукта автоматически. Официальный scaffolder допустим, если это лучший способ получить нужную основу; собственный универсальный генератор не требуется. -Импорты: `application → contracts/model`, `infrastructure → contracts/model`; core не импортирует infrastructure и presentation. Поток выполнения «сценарий вызывает adapter» не означает импорт конкретного adapter в core. Предметная модель не определяется Telegram, HTTP или БД. +Если одобренный план включает Kit, выбери минимальные профили и темы и выполни штатное подключение из указанного хаба. Проверь план перед разрешённым Apply, затем `doctor` и `status`. Не запускай отдельное интервью через `prompt connect` и не запрашивай повторное одобрение того же состава. Обычное подключение меняет только файлы правил; техническая настройка здесь разрешается именно планом bootstrap. Для публичного проекта сохрани local-only и восстановление уникального контекста по профилю. -Самостоятельный модуль может иметь локальные `application/model/infrastructure/presentation`, только когда каждый нужен. Общий core не становится складом capabilities. Один обработчик без независимой модели не требует всех слоёв. +## 5. Реализовать первый полноценный сценарий -### C. Библиотека / CLI +Создавай каталоги вместе с реальной ответственностью. Добавь необходимые команды запуска и прямые проверки поведения. Тесты, проверка типов, линтер, CI и подготовка к развёртыванию выбираются по стеку, риску и задаче; наличие материала в Kit не делает их обязательными. -Связная библиотека может остаться несколькими файлами рядом с публичной точкой входа. Для инструмента с независимыми вычислениями и вводом/выводом подходит `core/`, `application/`, `adapters/`: application использует core и необходимые контракты, adapters реализуют внешний доступ, entrypoint собирает зависимости. Core не знает CLI parsing и конкретную файловую/сетевую реализацию. Не вводи ports и пустые уровни в CLI с одной обязанностью. +Если нужна механическая защита устойчивой границы, используй существующий инструмент и проверь разрешённый и запрещённый импорт на изолированной фикстуре. Проверка пустого дерева не доказывает защиту. Учитывай реальные способы импортов проекта; ограниченный пример не гарантирует все связи. -## 3. Записать локальный контракт +Проверь первый сценарий, значимый отказ по риску и пригодность основы для следующего изменения. Для интерфейса проверь реальные состояния и композицию. Назови точные команды и результаты; тесты, локальный запуск и реальное развёртывание — разные подтверждения. Если важная проверка недоступна, явно оставь её незавершённой. -До существенной реализации кратко запиши тип, первые сценарии, один архетип, области и владельцев, разрешённые зависимости и точки входа, запрещённые связи, точку композиции и отсутствующие слои. Укажи причину выбора и условие пересмотра по действующему правилу документации. +## 6. Оставить короткий контекст для продолжения -Контракт позволяет найти место для UI и логики одной возможности, внешнего доступа, общего кода, новой возможности и композиции. Достаточно нескольких абзацев в `PROJECT_RULES` или существующей карте; отдельный документ по шаблону нужен только при самостоятельной роли. Не дублируй контракт в двух документах. Значимый выбор добавь коротким разделом в существующую карту решений; bootstrap не требует отдельного ADR, таблицы статусов или рабочих отчётов в корне. +Достаточно существующего README с запуском и проверками и локальных правил с особенностями проекта. Значимый выбор и его причину сохрани один раз в подходящем разделе; отдельные карта, ADR, runbook и handoff появляются только при самостоятельной пользе по [DOCUMENTATION](../rules/DOCUMENTATION.md). Не веди журнал каждой команды. -## 4. Создать минимальный skeleton и guard - -Создавай каталоги вместе с кодом ответственности первого сценария. Будущие области пока могут оставаться записью в контракте. Не добавляй пустые папки, framework scaffolder или собственный движок анализа зависимостей. - -Выбери важнейшие устойчивые ограничения: например, запрет `shared → features/app`, `core → infrastructure/presentation` или allowlist корневых entrypoints. Используй существующий линтер либо небольшой script/structural test. Проверь разрешённый импорт и представительное нарушение на изолированной фикстуре; учитывай реальные способы импортов и возвращай ненулевой exit code с понятным сообщением при нарушении. Субъективную связность файла не заменяй числовым лимитом. - -Добавь команду в обычные проверки, CI — если это входит в задачу. Успешная проверка пустого дерева не доказывает защиту. При недоступном механизме назови ограничение и незавершённую часть bootstrap. - -## 5. Реализовать и проверить первый сквозной сценарий - -Проведи результат через выбранных владельцев, проверь основной путь и значимый отказ по риску. Запусти guard на реальном skeleton. Убедись, что у нового кода есть понятное место, композиция делегирует независимое поведение, нет пустых слоёв, разрешённый и запрещённый случаи проверены. Отделяй результат от commit, push и публикации. - -## 6. Пересматривать по причинам изменения - -Пересмотри стартовую гипотезу при новой capability, реальном повторном использовании, новом adapter, усложнении жизненного цикла состояния или повторяющемся дрейфе. Выделяй одну границу за раз с сохранением поведения, переносом потребителей и обновлением guard и контракта. Удаляй ненужный слой с проверкой импортов и публичных потребителей; шаблон не оправдывает его сохранение. Основания пересмотра и удаления средств организации ведутся по действующему правилу документации. +После выбора читай локальный контракт и решения затронутой области. Пересматривай основу при новой самостоятельной ответственности, внешней границе или подтверждённом неудобстве изменений. Обычная задача не начинает bootstrap заново. ## Готовый запрос ```text -Подготовь первоначальную архитектуру проекта в "{{PROJECT_ROOT}}" и реализуй первый сквозной сценарий из моей задачи. +Создай работающую основу проекта в "{{PROJECT_ROOT}}" и реализуй первый полноценный сценарий из моей задачи. + +Прочитай локальные инструкции и процесс "{{BOOTSTRAP_WORKFLOW_PATH}}". Хаб доступен рядом с "{{HUB_CLI_PATH}}". Проверь Git и сохрани несвязанные изменения. Используй уже известную идею, первый сценарий и ограничения; уточни только сведения, без которых нельзя выбрать основу. -Прочитай процесс "{{BOOTSTRAP_WORKFLOW_PATH}}" и релевантные правила из хаба рядом с "{{HUB_CLI_PATH}}", затем локальные инструкции проекта. Проверь Git и сохрани несвязанные изменения. Если цель или первый сценарий не указаны, собери доступный контекст и уточни недостающее до зависимой реализации. +Определи подходящий масштаб и технологию. Следуй соглашениям выбранной платформы, сохраняя свободу архитектуры. Сравни варианты только для существенных решений. Готовые материалы Kit применяй избирательно; если они не подходят, объясни почему и выбери иной путь. Для продукта без графического интерфейса не запускай дизайн-процесс. -Выбери один минимальный архетип, запиши локальный контракт размещения кода и зависимостей, создай только необходимые части, добавь и проверь архитектурный guard, затем проверь первый сквозной результат. Для существующей области используй установленную архитектуру; не выполняй автоматический рефакторинг. Обычное подключение Kit не входит в реализацию и не расширяет её границы. Не выполняй неразрешённый -Apply, commit, push или публикацию. +Покажи понятный план с первым работающим результатом и проверками. Получи одобрение до зависимой реализации; уже согласованный конкретный план не требует повторного разрешения. Подключение Kit при необходимости включи в этот план, без отдельного интервью. Затем создай только необходимые части, проверь первый сценарий и оставь минимальный контекст для продолжения. -Покажи выбранные границы, отсутствующие слои, точные команды и результаты проверок, непроверенное и условия пересмотра. Не объявляй механическую защиту подтверждённой без разрешённого и запрещённого примеров. +В существующем проекте используй принятую архитектуру; подключение не разрешает рефакторинг. Не выполняй неразрешённый -Apply, commit, push или публикацию. В конце сообщи результат, команды проверок, непроверенное и существенные ограничения. ``` diff --git a/workflows/PROJECT_CONNECT_PROMPT.md b/workflows/PROJECT_CONNECT_PROMPT.md index f7496dd..e6081d2 100644 --- a/workflows/PROJECT_CONNECT_PROMPT.md +++ b/workflows/PROJECT_CONNECT_PROMPT.md @@ -9,12 +9,12 @@ Действуй по шагам: 1. Проверь `git status`, локальные инструкции, основные точки входа, настройки и команды проверки. Сохрани несвязанные изменения владельца. -2. Выбери минимальный набор профилей и тем. Объясни выбор простыми словами и назови точные идентификаторы для `-Profiles` и `-Topics`. Не добавляй правило только потому, что оно есть в хабе. Для нового развиваемого проекта без архитектурного контракта предложи явно выбрать `architecture-and-data` и `project-bootstrap` (тему архитектуры не дублируй, если она входит в профиль). Для существующего проекта отсутствие контракта зафиксируй как разрыв, без автоматического добавления bootstrap. +2. Выбери минимальный набор профилей и тем. Объясни выбор простыми словами и назови точные идентификаторы для `-Profiles` и `-Topics`. Не добавляй правило только потому, что оно есть в хабе. Для нового проекта без основы предложи `prompt bootstrap` с идеей и первым сценарием: он может включить подключение в один одобренный план. При запросе только на подключение продолжай этот процесс; `project-bootstrap` устанавливать не обязательно, тему архитектуры не дублируй, если она входит в профиль. Для существующего проекта отсутствие контракта зафиксируй как разрыв, без автоматического добавления bootstrap. 3. Если `.ai-rules/manifest.json` отсутствует, выполни `connect -ProjectRoot "{{PROJECT_ROOT}}"` с выбранными `-Profiles` и `-Topics`. Если проект уже подключён, выполни эту команду без изменения состава правил. 4. Покажи созданные локальные файлы, предложенную версию хаба и файлы правил, которые будут добавлены или изменены. Для public-repository проверь локальный Git exclude и tracked-инфраструктуру. AGENTS.md, .ai-rules/ и .local/ по умолчанию local-only; приватный путь не записывай в tracked-файлы. Укажи Private Project Context или его отсутствие; уникальные правила после clone восстанавливаются из выбранного приватного версионируемого источника. Потенциально внутренние документы требуют проверки аудитории, а намеренно публичные ADR допустимы. Отдельно скажи, что останется нетронутым. -5. Остановись перед `-Apply` и запроси одно явное разрешение на применение показанных изменений. +5. Остановись перед `-Apply`, если эти конкретные изменения ещё не одобрены, и запроси одно явное разрешение. Согласованный состав и применение в плане bootstrap не требуют повторного разрешения. 6. После разрешения повтори ту же команду с `-Apply`. Проверь результат командами `doctor` и `status`, затем покажи `git diff` проекта. Установи, могут ли форматтер, линтер и поиск тестов захватить установленные файлы Kit. Git ignore не исключает их из этих инструментов. Если нужно исключение в настройках проекта, покажи узкое изменение отдельно; не исправляй неизменяемый выпуск Kit и не выключай проверки исходников проекта. -7. Для нового проекта укажи следующий отдельный шаг: `{{HUB_CLI_PATH}} prompt bootstrap -ProjectRoot "{{PROJECT_ROOT}}"` вместе с целью и первым сценарием. Подключение не создаёт skeleton, guard и не реализует продукт. Последующая разработка начинает с первоначального выбора по архитектурному правилу даже без установленного процесса. +7. Для нового проекта укажи следующий отдельный шаг: `{{HUB_CLI_PATH}} prompt bootstrap -ProjectRoot "{{PROJECT_ROOT}}"` вместе с целью и первым сценарием. Подключение не создаёт основу, guard и не реализует продукт. Если bootstrap уже выполняется по одобренному плану, возвращайся к его первому сценарию без второго запуска или интервью. Не выходи за эти границы: - не редактируй `.ai-rules/upstream/` вручную; diff --git a/workflows/VISUAL_DESIGN_DISCOVERY.md b/workflows/VISUAL_DESIGN_DISCOVERY.md index 836e553..e98cff0 100644 --- a/workflows/VISUAL_DESIGN_DISCOVERY.md +++ b/workflows/VISUAL_DESIGN_DISCOVERY.md @@ -2,71 +2,44 @@ ## Когда применять и как читать -Обязанность и исключения задаёт [PRODUCT](../rules/PRODUCT.md#визуальное-направление-до-реализации). Этот процесс помогает выбрать направление для нового продукта с существенным UI, самостоятельной визуальной области, значительного редизайна или устранения шаблонности. Малые правки и развитие действующей дизайн-системы не запускают его повторно. +Обязанность и исключения задаёт [PRODUCT](../rules/PRODUCT.md#визуальное-направление-до-реализации). Этот процесс помогает при исследовании существенного нового интерфейса, редизайне или устранении шаблонности. Малые правки продолжают действующую систему; продукт без графического интерфейса пропускает процесс. -Читай workflow по задаче прямо из хаба или выбери `visual-design-discovery` через `-Topics` при подключении. Профили не устанавливают его автоматически. Изменение состава существующего проекта проходит обычные Plan и разрешённый Apply; не правь upstream или lock вручную. Подключение правил не запускает дизайн или изменение кода. +Читай workflow из доступного хаба или выбранной копии `visual-design-discovery` по `INDEX.md`. Профили не устанавливают его автоматически; подключение Kit не запускает дизайн. Достаточный простой выбор выполняется по PRODUCT без полного workflow. -Прочитай локальный продуктовый контекст и существующий visual contract/design system. Сохраняй принятые решения, если задача не требует их пересмотра. Для новой области внутри общего продукта сначала проверь, достаточно ли действующей системы. Discovery не должен производить отдельный стиль для каждой feature. +## 1. Связать композицию со сценарием -## 1. Определить характер продукта +Коротко определи аудиторию, частое действие, приоритет содержимого, плотность, способы ввода и ограничения платформы. Прочитай существующие компоненты, токены и визуальный контракт. Для новой возможности сначала проверь, подходит ли действующая система; не создавай независимый стиль для каждой feature. -До поиска референсов коротко запиши: +Выбери композицию по реальным данным и действиям. Например, рабочий список, редактор, временная шкала и пошаговая форма обслуживают разные задачи. Modern, clean и elegant не объясняют выбор. Цвет и скругления не заменяют структуру экрана. -- кто пользуется интерфейсом и что делает чаще всего; -- нужную плотность и ограничения чтения или ввода; -- что доминирует: данные, действия, текст, объекты или процесс; -- подходящее ощущение и что интерфейс не должен напоминать. +## 2. Исследовать только то, что помогает выбрать -Например: «Плотный локальный рабочий инструмент для ежедневного управления проектами, похожий на операционный стол владельца, а не на SaaS admin dashboard». Это пример, а не рекомендуемый стиль для всех продуктов. Modern, clean и elegant могут быть пожеланиями, но не заменяют характер продукта и критерии выбора. +Если подход неясен или владелец просит визуальные ориентиры, найди подтверждённые примеры с полезной навигацией, плотностью, типографикой, пространственной моделью или взаимодействием. Фиксированного количества нет. Для каждого достаточно ссылки и краткого объяснения, что применимо здесь; таблица нужна только если упрощает сравнение. -## 2. Исследовать референсы +Используй реальные просмотренные страницы или локальные материалы. Маркетинговое описание не подтверждает устройство экрана, снимок — взаимодействие. Недоступные источники и проверки назови неизвестными; не выдумывай ссылки или просмотр. При веб-поиске сохраняй ссылки на материалы. -Для существенного нового дизайна собери примерно 4–6 референсов, ориентир — 5. Каждый нужен ради конкретного свойства. Ищи пересечения по информационной архитектуре, навигации, плотности, статусам, сложным данным, типографике, композиции, визуальному характеру или взаимодействию. Временная шкала, ощущение desktop application и редакционная подача тоже могут быть полезны. +Извлекай принципы, а не копируй брендинг, логотипы, уникальные иллюстрации или интерфейс один в один. Другие продукты того же владельца можно сравнить по доступным релевантным материалам, без поиска всех его репозиториев. Различие только accent color — повод проверить обоснованность композиции; осознанная общая продуктовая семья может правильно сохранять сходство. -Полезное сочетание: 1–2 прямых аналога, 1–2 продукта с подходящей информационной архитектурой, 1–2 более дальних визуальных или интерактивных примера. Это ориентир, а не квота. Пять почти одинаковых dashboard-приложений не дают достаточного исследования: замени часть примеров на другие способы организации того же пользовательского результата. +## 3. Выбрать направление -Если доступен веб-поиск, используй реальные актуальные продукты и сохрани ссылки на просмотренные страницы или материалы. Отделяй увиденный интерфейс от маркетингового описания; название продукта или поисковый сниппет не подтверждают устройство экрана. Для статичного снимка не заявляй проверенное взаимодействие. Если веб недоступен, используй подтверждённые локальные материалы или запроси референсы. Укажи недостаток источников и его влияние; не выдумывай просмотр, ссылки или доступ к закрытому продукту ради нужного количества. +При ясном выборе рекомендуй одно направление и объясни его через первый сценарий. Несколько направлений показывай при существенной неопределённости, дорогом в изменении выборе или запросе владельца. Сравни их на одинаковом сценарии и представительных данных: навигация, плотность и приоритет действий должны действительно различаться. Несколько полноценных приложений для сравнения не нужны. -До реализации составь компактную Reference Matrix: +Получай решение владельца, если существенный выбор ещё не разрешён. Уже согласованный план или автономный выбор не требуют повторного одобрения каждой детали. -| Reference | Почему выбран | Что берём | Что не берём | -| --- | --- | --- | --- | -| Название и ссылка либо путь к подтверждённому материалу | Свойство, полезное этому продукту | Принцип и его применение к задаче | Чужие решения, которые здесь не подходят | +## 4. Сохранить короткий визуальный контракт -Извлекай принципы, адаптируя их к сценарию. Не копируй брендинг, логотипы, уникальные иллюстрации, фирменные assets или интерфейс один в один. Сходство с референсом само по себе не является критерием успеха. +Запиши один раз в существующем подходящем месте композицию, основные компоненты и токены, иерархию текста, правила статусов и поведения на поддерживаемых экранах. Причина выбора и область применения должны быть понятны. Небольшому интерфейсу достаточно нескольких предложений; отдельный design document не обязателен. -## 3. Сравнить направления и выбрать одно +Компоненты и токены в коде остаются источником своих технических значений. Документ объясняет выбор и использование, не копирует каждое значение. Общие элементы появляются из реального повторения; огромная дизайн-система заранее не нужна. -Сформируй минимум 2, желательно 3 существенно разных направления. Они должны отличаться архитектурой экрана, навигацией, плотностью, поверхностями, пространственной моделью, типографикой, статусами, работой с деталями или способом разделения содержимого. Замена accent color и border-radius не создаёт нового направления. +Для публичного репозитория исследование и внутренние основания хранятся по [DOCUMENTATION](../rules/DOCUMENTATION.md#приватный-источник-публичного-проекта). Публичное руководство допустимо при внешней пользе. Игнорируемая заметка не заменяет восстановление уникального контекста; новый сервис хранения не требуется. -Для каждого кратко укажи идею, сильные и слабые стороны, повлиявшие референсы. Сравни их на одном основном сценарии и одинаковых представительных данных. Достаточно кратких схем или описаний композиции; не реализуй несколько полноценных приложений ради сравнения. +## 5. Проверить реализованный интерфейс -В интерактивной задаче с доступным владельцем желательно показать направления до полной реализации и рекомендовать лучшее по критериям продукта. Если автономный выбор уже разрешён, выбери и объясни его без дополнительного согласования. Если существенный выбор остаётся за владельцем, уточни именно его до зависимой реализации; доступность инструмента не означает принятие направления. +По [QUALITY](../rules/QUALITY.md#проверка-интерфейса) проверь выбранный сценарий, иерархию, представительные данные, состояния, адаптивность и доступность. Сопоставь конкретные наблюдения с контрактом. Один красивый снимок не доказывает удобство. -## 4. Зафиксировать Design Direction - -Короткий визуальный контракт отвечает на вопросы: - -- как устроены основные экраны и навигация; -- каковы плотность, система поверхностей и иерархия текста; -- как используются цвет, скругления, рамки и тени; -- как представлены статусы и основные действия; -- как композиция меняется на широком и узком экране. - -Добавь причину выбора, границы применения и условие пересмотра. Храни контракт в одном существующем подходящем месте и ссылайся на него при следующих feature-задачах. Не создавай заранее огромную дизайн-систему. - -В public repository внутреннее исследование, подбор референсов и основания выбора по умолчанию относятся к Private Project Context по [DOCUMENTATION](../rules/DOCUMENTATION.md#приватный-источник-публичного-проекта). Публичное описание допустимо при названной внешней пользе. Не заставляй публиковать исследование и не считай игнорируемую заметку версионируемым приватным источником. Если источник ещё не настроен, назови пробел хранения; не создавай внешний сервис и не блокируй обычную работу ради него. - -## 5. Реализовать и проверить направление - -Реализуй выбранное направление в пределах разрешённой задачи. По [QUALITY](../rules/QUALITY.md#проверка-интерфейса) проверь концепцию, иерархию, представительные данные, состояния, адаптивность и доступность. Сопоставь конкретные наблюдения с контрактом; один красивый скриншот не доказывает удобство или отсутствие шаблонности. - -Обязательная антишаблонная проверка объясняет существенные решения через этот продукт: почему здесь нужны именно такие навигация, поверхности, иерархия и действия? Если причина — только привычный dashboard, пересмотри решение. Не запрещай sidebar, cards, topbar, badges, gray background или rounded panels ради самого отличия. - -При доступе к другим проектам того же владельца можно коротко сравнить navigation model, page structure, card/surface model, typography, spacing, color и visual hierarchy. Ограничь сравнение доступными релевантными материалами; не ищи все проекты владельца и не меняй их. Отличие независимых продуктов преимущественно accent color и текстом — сигнал недостаточного Discovery. Для сознательно общей продуктовой семьи или общего design system сходство может быть правильным. Если сравнение недоступно, так и укажи: отсутствие сравнения не доказывает уникальность. +Для существенных решений объясни, почему именно этому продукту нужны такие навигация, поверхности и действия. Привычный dashboard без причины — сигнал пересмотра; sidebar, cards и rounded panels сами по себе допустимы. Не добивайся необычности ценой понятности. ## Достаточный результат -Характер продукта, компактная матрица референсов, 2–3 направления, выбранный контракт и наблюдения визуальной проверки. Не требуются Figma, десятки moodboards, отдельный design repository, 20 референсов или pixel-perfect specification до первого экрана. Масштаб записи соразмерен задаче; сохраняй недоступные проверки и источники как неизвестное. - -Цена процесса — короткое исследование до кода. Пересмотри его объём, если он регулярно задерживает работу без различий в решениях. Упростить или заменить процесс можно после сравнения результата и затрат по [RESEARCH_AND_EVIDENCE](../rules/RESEARCH_AND_EVIDENCE.md#сравнение-процессов), если более короткий путь сохраняет осознанный выбор и визуальную проверку; наличие этого workflow само по себе не доказывает улучшение дизайна. +Одна обоснованная композиция, короткий контракт и наблюдения проверки. Референсы и альтернативы — по необходимости. Не требуются квоты, матрица, отдельное исследование, Figma или новый набор компонентов в каждой задаче. Если процесс задерживает работу без полезного изменения решения, сократи его; безопасность, честность проверки и критическая доступность сохраняются.