ai-rules-kit

v0.13.3

Published

5 days ago

CLI tool for managing AI rules in IDE projects (Cursor, TRAE)

0High
0Medium
0Low

cyberwalrus

cursor trae ai rules rules-kit cli configuration management

AI Rules Kit

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

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

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

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

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

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

Автоматическое качество: 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

# Глобальная установка через npm
npm install -g ai-rules-kit

# Или через yarn
yarn global add ai-rules-kit

# Или использование без установки
npx ai-rules-kit

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

Инициализация Workspace Rules

Запустите 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 протокол

Настройка User Rules

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

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

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

Конфигурация правил

После инициализации создается файл .cursor/ai-rules-kit-config.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.

MCP Серверы

Для работы системы необходимы 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 ключ.

Получение API ключа OpenRouter

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

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

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

GitHub API токен (опционально)

При использовании 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.

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

Режимы работы

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

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

Типы задач (Activity Types)

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 — машиночитаемая документация

Типы промптов

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

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

Структура проекта

.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

Как система решает проблемы

Автоматическое качество: 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.

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

Команды

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

/commit
# → Команды качества (package-ai-docs.md / package.json: lint/test/typecheck)
# → Анализ незакоммиченных изменений → Разделение на атомарные части
# → Коммиты по типу (feat/fix/docs/refactor) в формате {task-id}: [{type}] {message}

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

/changelog
# → Определение границ версий (version.json)
# → Извлечение коммитов между версиями → Группировка и обобщение
# → Генерация секции CHANGELOG.md со ссылками на коммиты

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

/agent-analysis
# → Извлечение фактов (tool calls, workflow, нарушения)
# → Саморефлексия: почему нарушил правила (честный анализ причин)
# → Барьеры работы (неясности, противоречия, технические ограничения)
# → Конкретные предложения по улучшению правил и workflow

Режимы работы

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

AI Rules Kit

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

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

📋 Оглавление

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

Установка CLI

Инициализация Workspace Rules

Настройка User Rules

Конфигурация правил

MCP Серверы

Получение API ключа OpenRouter

GitHub API токен (опционально)

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

Режимы работы

Типы задач (Activity Types)

Типы промптов

Структура проекта

Как система решает проблемы

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

Команды

Режимы работы

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

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

📄 Лицензия