Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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:

Expand All @@ -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:

Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion ai-rules.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ Agent Engineering Kit
prompt parallel -ProjectRoot ПУТЬ
Подготовить запрос для параллельной задачи.
prompt bootstrap -ProjectRoot ПУТЬ
Выбрать первоначальную архитектуру нового проекта.
Подготовить основу и первый работающий сценарий проекта.
connect -ProjectRoot ПУТЬ
Подготовить проект и показать изменения.
connect -ProjectRoot ПУТЬ -Apply
Expand Down
8 changes: 4 additions & 4 deletions hub/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Целевой результат

Целевой проект должен получить короткую локальную точку входа и читать только тот набор правил, который относится к его типу и текущей задаче.
Целевой проект получает подходящую работающую основу, проверенные настройки по необходимости и короткий контекст для продолжения. Kit сохраняет инженерный опыт между проектами, не выбирая одну архитектуру или технологию для всех. Подключённый агент читает только правила текущей задачи.

```text
запрос владельца и указанный контекст задачи
Expand Down Expand Up @@ -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/` и управляемая копия

Expand Down
6 changes: 5 additions & 1 deletion hub/PROJECT_RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

## Назначение

Хаб хранит проверенный, переносимый каркас правил для новых и существующих проектов. Его результат — не максимальное число инструкций, а небольшой непротиворечивый набор, который можно осознанно подключить, проверить и локально уточнить.
Agent Engineering Kit сокращает повторяющуюся работу при создании и развитии программных проектов: помогает выбрать подходящую основу, применить проверенные настройки и сохранить особенности проекта между сессиями. Последовательность архитектуры, кода, дизайна и документации остаётся практической целью; обучение модели общему программированию не является назначением Kit.

Общие принципы независимы от стека. Готовые материалы применяются избирательно: небольшая долговечная утилита может остаться несколькими файлами, а сервис с независимыми интеграциями и риском повторных эффектов получает необходимые границы. Отсутствие примера для мобильной платформы, игры, обработки данных или другой технологии нормально. Агент использует принятые средства этой технологии и объясняет отказ от неподходящего материала Kit.

Этот репозиторий публичный. Для любых изменений, публикации и внешнего взаимодействия обязателен профиль [`../profiles/public-repository.md`](../profiles/public-repository.md) вместе с подключаемыми им тематическими правилами.

Expand All @@ -22,6 +24,8 @@

Если правило подтверждено одним доменом и несёт его терминологию, оно остаётся профилем либо проектным примером. Базовый набор не растёт из единичного предпочтения.

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

## Нормативная граница

Нормативны только:
Expand Down
2 changes: 1 addition & 1 deletion profiles/standard-product.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Назначение

Для приложения или сервиса, который регулярно доставляет пользовательский либо операционный результат. Состав тем — в `sync/catalog.json` и manifest проекта.
Для программного продукта, который регулярно доставляет пользовательский либо операционный результат: приложения, сервиса, игры, инструмента или пакета. Профиль не выбирает стек, каталоги, UI, CI или развёртывание. Состав тем — в `sync/catalog.json` и manifest проекта.

## Уникальные обязательства

Expand Down
Loading
Loading