AI Rules Kit


Модульная система AI-промптов для IDE (Cursor, TRAE) с автоматической классификацией задач и встроенной валидацией качества. Обеспечивает консистентность кода, архитектурную целостность и автоматическое следование best practices.

> 📖 Методики промптинга: Все методики с примерами → prompt-engineering-techniques.md

Зачем нужен пакет

При работе с AI-ассистентами в code editors возникают системные проблемы:

1. Непредсказуемое качество — одна задача выполняется отлично, другая с ошибками
2. Игнорирование стандартов — AI забывает правила кода, именования, архитектуры
3. Избегание инструментов — не использует web_search, MCP серверы, Context7
4. Незавершенность — останавливается на середине, пропускает шаги
5. Фабрикация фактов — утверждает без проверки, "галлюцинирует"
6. Отсутствие валидации — нет автоматической проверки качества кода/промптов
7. Консистентность — каждый разработчик настраивает правила по-своему
8. Потеря контекста — забывает инструкции при длинных сессиях

Как система решает:

- Автоматическое качество: MCP валидация (≥85), lint/type/tests (0 errors), blocking checks
- Специализация: 8 activity types с автоматической классификацией, режимы Plan/Agent/Ask
- Принудительное использование инструментов: MANDATORY requirements, triggers перед модификацией
- Завершенность: completion_criteria, pre_response_barrier, PLAN-FIRST + todos tracking
- Консистентность: AlwaysApply rules активны автоматически, workspace rules в Git

Эффект: AI работает как опытный разработчик — следует стандартам, проверяет факты, доводит задачи до конца, использует инструменты автоматически.

Как быстро начать

Установка: npm install -g ai-rules-kit или npx ai-rules-kit

Основной способ использования: запустите ai-rules-kit без аргументов — откроется интерактивное меню:

- init — инициализация правил в проекте
- system-files — копирование системных файлов (meta-info, core-system-instructions, mcp-config, current-date)
- config — настройка глобальной конфигурации
- upgrade — обновление правил
- versions — просмотр версий CLI и правил

После инициализации настройте User Rules через system-files и добавьте MCP серверы (см. детальные инструкции ниже).

📋 Оглавление

- Установка и настройка
- Установка CLI
- Инициализация Workspace Rules
- Настройка User Rules
- Конфигурация правил
- MCP Серверы
- Получение API ключа OpenRouter
- GitHub API токен
- Архитектура и принципы работы
- Режимы работы
- Типы задач
- Типы промптов
- Структура проекта
- Как система решает проблемы
- Примеры использования
- Команды
- Режимы работы
- Стандарты и принципы
- Поддерживаемые модели AI
- Лицензия

🚀 Установка и настройка

$3

``bash


Глобальная установка через npm

npm install -g ai-rules-kit

Или через yarn

yarn global add ai-rules-kit

Или использование без установки

npx ai-rules-kit

Короткий алиас

airk
`

$3

Запустите ai-rules-kit и выберите init (или напрямую: ai-rules-kit init или airk init).

Команда автоматически:

- Создаёт директорию .cursor/ (или .trae/ для TRAE) в корне проекта
- Копирует все правила, документацию и команды
- Создаёт файл конфигурации .cursor/ai-rules-kit-config.json
- Настраивает базовую конфигурацию

Автоматически активируются (alwaysApply: true):

- 01-chat-mode-router.mdc — определяет режим работы (Plan/Agent/Ask)
- 02-rules-navigator.mdc — навигация по правилам
- 03-code-standards-compact.mdc — стандарты кода
- 04-naming-compact.mdc — соглашения именования
- 05-testing-compact.mdc — правила тестирования
- 06-architecture-compact.mdc — архитектурные правила
- 07-agent-mode-workflow.mdc — Agent Mode протокол

$3

Путь: Cursor Settings → Rules, Memories, Commands → User Rules

1. Запустите ai-rules-kit и выберите system-files
2. Выберите нужный файл (например, meta-info)
3. Файл будет скопирован в буфер обмена
4. Откройте Cursor Settings (Cmd + , на macOS или Ctrl + , на Windows/Linux)
5. Перейдите в раздел Cursor Settings → Rules, Memories, Commands → User Rules
6. Нажмите Add Rule и вставьте содержимое из буфера обмена
7. Замените переменные в шаблоне на свои данные:
- ${CURRENT_DATE} — текущая дата в формате YYYY-MM-DD
- ${NAME}, ${AGE}, ${ROLE}, ${STACK}, ${OS}, ${DEVICE}, ${LOCATION}, ${LANGUAGE}, ${COMMUNICATION_STYLE} — персональные данные
8. Сохраните правило

> 💡 Совет: Повторите процесс для файла core-system-instructions — это основные принципы работы AI.

$3

После инициализации создается файл .cursor/ai-rules-kit-config.json:

`json
{
"$schema": "https://raw.githubusercontent.com/CyberWalrus/ai-rules-kit/main/schemas/ai-rules-kit-config-1.0.0.schema.json",
"configVersion": "1.0.0",
"installedAt": "2025-11-07T10:00:00.000Z",
"updatedAt": "2025-11-07T10:00:00.000Z",
"source": "ai-rules-kit",
"version": "0.8.1",
"settings": {
"language": "ru"
},
"ruleSets": [
{
"id": "base",
"update": true
}
],
"ignoreList": [],
"fileOverrides": []
}
`

Параметры: settings.language (язык CLI), ruleSets (наборы правил), ignoreList (игнорируемые файлы), fileOverrides (переопределения YAML frontmatter).

> 📋 JSON Schema: Файл конфигурации поддерживает автодополнение через JSON Schema.

$3

Для работы системы необходимы MCP серверы:

- context7 — документация библиотек
- mcp-validator — валидация кода/промптов/архитектуры

> ⚠️ Примечание: Система может работать без mcp-validator, но качество снизится — не будет автоматической валидации кода (score ≥85).

Настройка: Запустите ai-rules-kit → system-files → mcp-config — конфигурация будет скопирована в буфер обмена. Добавьте серверы в Cursor Settings → Tools & MCP → New MCP Server и замените YOUR_OPENROUTER_API_KEY_HERE на реальный API ключ.

$3

Для работы mcp-validator требуется API ключ от OpenRouter:

1. Перейдите на https://openrouter.ai/keys
2. Войдите в аккаунт или зарегистрируйтесь
3. Создайте новый API ключ (нажмите "Create Key")
4. Скопируйте ключ (формат: sk-or-v1-...)
5. Добавьте его в конфигурацию MCP сервера

> 💡 Примечание: OpenRouter поддерживает бесплатные модели (например, openai/gpt-oss-20b:free).

$3

При использовании CLI команд для получения последней версии правил из GitHub может потребоваться токен доступа.

Без токена: GitHub API ограничивает неаутентифицированные запросы до 60 запросов в час. С токеном: лимит увеличивается до 5000 запросов в час.

Как получить: GitHub Settings → Developer settings → Personal access tokens → Tokens (classic) → "Generate new token (classic)" → scope public_repo → скопируйте токен (формат: ghp_...).

Использование: export GITHUB_TOKEN=ghp_your_token_here или GITHUB_TOKEN=ghp_your_token_here npx ai-rules-kit init

> 💡 Примечание: Токен опционален. При ошибке 403 установите переменную окружения GITHUB_TOKEN.

🏗️ Архитектура и принципы работы

$3

Система автоматически переключается между тремя режимами:

- Plan Mode — активируется через Shift + Tab. Cursor анализирует кодовую базу, задаёт уточняющие вопросы, генерирует структурированный Markdown-план. Кастомная логика классифицирует задачу (8 activity types) и применяет специализированный workflow
- Agent Mode — автономное выполнение. Валидация через MCP (≥85), проверка lint/type/tests (0 errors), обновление AI-документации, финальный отчёт
- Ask Mode — консультация без модификации файлов, верификация через web_search и Context7

$3

Plan Mode автоматически определяет тип задачи и применяет соответствующий workflow:

🔧 Code Development — разработка с архитектурной валидацией
🔧 Auxiliary Development — инфраструктура (VPN, деплой, автоматизация)
🎨 UI Development — UI/UX с browser validation
🔍 Technical Critique — код-ревью и анализ качества
📋 JIRA Task Creation — создание технических заданий
📐 Detailed Planning — детальная декомпозиция задач
🧠 Prompt Engineering — создание и улучшение AI-промптов
🤖 AI Documentation — машиночитаемая документация

$3

Система использует 5 типов промптов для разных сценариев:

- compact (≤150 строк) — роутеры и быстрые проверки
- command (50-200 строк) — исполняемые команды с императивным стилем
- algorithm (100-600 строк) — пошаговые workflow с валидацией
- reference (100-1000 строк) — справочники и документация
- combo (200-1600 строк) — комплексные промпты (algorithm + reference)

$3

`
.cursor/ (или .trae/ для TRAE)
├── rules/ # Workspace правила (16 файлов)
│ # Роутинг, стандарты, activity workflows
├── docs/ # Детальные справочники (14 файлов)
│ # Стандарты кода, архитектуры, тестирования
└── commands/ # Исполняемые команды (8 файлов)
# commit, changelog, agent-analysis, fix, force, jira, refactor-module

system-rules/ # Системные файлы для User Rules (не в Git)
# core-system-instructions, meta-info, current-date, mcp-config
`

.cursor/rules/ — автоматически применяемые правила и workflow для разных типов задач

.cursor/docs/ — детальная документация: стандарты кода, архитектурные паттерны, шаблоны

.cursor/commands/ — готовые команды для Git автоматизации и анализа работы AI

system-rules/ — системные файлы для User Rules. Используйте команду ai-rules-kit system-files для копирования в буфер обмена.

> 📋 Полный список файлов с описаниями см. в .cursor/docs/rules-catalog.md

$3

Автоматическое качество: MCP валидация (≥85), lint/type/tests (0 errors), blocking checks.

Специализация: 8 activity types с автоматической классификацией, режимы Plan/Agent/Ask, специализированные workflow (UI → browser validation, Code → architecture validation).

Принудительное использование инструментов: MANDATORY requirements, triggers перед модификацией, web_search для фактов, Context7 для пакетов.

Завершенность: completion_criteria, pre_response_barrier, PLAN-FIRST + todos tracking.

Токен-оптимизация: 5 типов промптов (compact ≤150 строк), cascade loading, compact alwaysApply стандарты.

Консистентность: AlwaysApply rules (03-07) активны автоматически, workspace rules в Git, user rules в Settings, self-documenting architecture.

💡 Примеры использования

$3

Автоматический коммит с проверкой качества:

`bash
/commit


→ Команды качества (package-ai-docs.md / package.json: lint/test/typecheck)

→ Анализ незакоммиченных изменений → Разделение на атомарные части

→ Коммиты по типу (feat/fix/docs/refactor) в формате {task-id}: [{type}] {message}

`

Генерация CHANGELOG из истории коммитов:

`bash
/changelog


→ Определение границ версий (version.json)

→ Извлечение коммитов между версиями → Группировка и обобщение

→ Генерация секции CHANGELOG.md со ссылками на коммиты

`

Анализ работы AI и рекомендации по улучшению:

`bash
/agent-analysis


→ Извлечение фактов (tool calls, workflow, нарушения)

→ Саморефлексия: почему нарушил правила (честный анализ причин)

→ Барьеры работы (неясности, противоречия, технические ограничения)

→ Конкретные предложения по улучшению правил и workflow

`

$3

Plan Mode — создание плана с подтверждением:

`
Создай систему аутентификации с JWT токенами
`

Plan Mode: Cursor анализирует кодовую базу, задаёт уточняющие вопросы, классифицирует задачу (8 activity types) и генерирует структурированный Markdown-план. После подтверждения → переход в Agent Mode.

Agent Mode: Автономное выполнение с валидацией через MCP (≥85), проверкой lint/type/tests (0 errors), написанием тестов (100% coverage) и обновлением AI-документации. Отчёт: Modified N files | Validated N | All ≥85 | COMPLETE.

Ask Mode: Консультация без модификации файлов. Верификация через mcp_context7_resolve-library-id, mcp_context7_get-library-docs и web_search с ответом со ссылками на источники.

📜 Стандарты и принципы

| Категория | Ключевые правила | Документация |
| :----------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |
| Code Standards | One file = one function (150 lines), 100% coverage, guard clauses, array methods, no classes/loops/any | .cursor/docs/code-standards.md |
| Naming | Files: kebab-case, Components: PascalCase, Functions: camelCase, Constants: SCREAMING_SNAKE_CASE | .cursor/docs/naming.md |
| Architecture | Golden Rule: код нужен только одному юниту → внутри юнита. Facades: named exports only | .cursor/docs/architecture.md |
| Testing | 100% coverage, Russian names, AAA pattern, typed mocks, vi.clearAllMocks() в beforeEach | .cursor/docs/testing.md |

Абсолютные запреты: for/while loops, class keyword, export default, any/Function type, JSX.Element

> 📋 Полный список стандартов: система автоматически применяет правила через .cursor/rules/03-07-*.mdc` (alwaysApply: true)

🤖 Поддерживаемые модели AI

Ниже перечислены модели AI, для которых система тестировалась и оптимизировалась. Работа проверена в Cursor IDE v2.0.0; при обновлении Cursor с новыми функциями система может устареть.

- Claude Sonnet 4.5 Thinking — рекомендуемый вариант, полная поддержка всех режимов и функций
- Composer 1 — совместим со всеми режимами, стоимость примерно в 2-3 раза ниже Sonnet 4.5
- Grok 4 Fast Thinking — бюджетный вариант с ограничениями: не поддерживает Plan Mode
- Auto — использовать только в Plan Mode; в остальных режимах стабильность не гарантирована

📄 Лицензия

MIT License — см. LICENSE

---

Создано для профессиональной разработки с AI ассистентами в Cursor IDE