code-ai-installer 2.2.0 → 2.4.0

package/.agents/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: karpathy-guidelines
+description: Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.
+license: MIT
+source: https://x.com/karpathy/status/2015883857489522876
+---
+
+# Karpathy Guidelines
+
+Правила работы, основанные на наблюдениях Андрея Карпати о типичных ошибках LLM.
+
+> Эти правила ставят аккуратность выше скорости. Для совсем тривиальных задач используй здравый смысл.
+
+---
+
+## 1. Сначала думай, потом делай
+
+**Не предполагай молча. Не скрывай неопределённость. Называй альтернативы.**
+
+Перед тем как приступить:
+- Явно назови свои предположения. Если не уверен — спроси.
+- Если задачу можно понять по-разному — перечисли варианты, не выбирай сам.
+- Если есть более простой путь — скажи об этом. Возражай, когда это уместно.
+- Если что-то непонятно — остановись, назови конкретно что, и спроси.
+
+### Пример: скрытые предположения
+
+**Запрос:** "Добавь экспорт пользовательских данных"
+
+❌ **Что делают LLM** — молча предполагают формат, поля и объём:
+
+```python
+def export_users(format='json'):
+    users = User.query.all()
+    with open('users.json', 'w') as f:
+        json.dump([u.to_dict() for u in users], f)
+    return f"Exported {len(users)} users"
+```
+
+✅ **Как надо** — сначала назвать предположения и уточнить:
+
+```
+Прежде чем делать, нужно прояснить:
+
+1. Кого экспортировать: всех пользователей или отфильтрованных? (вопрос приватности)
+2. Что значит "экспорт": скачать файл, фоновая задача с уведомлением или API endpoint?
+3. Какие поля включать? (часть данных может быть чувствительной)
+4. Сколько пользователей обычно? (влияет на архитектуру)
+
+Что из этого важнее всего?
+```
+
+### Пример: несколько трактовок
+
+**Запрос:** "Ускорь поиск"
+
+❌ **Что делают LLM** — выбирают одну трактовку и пишут 200 строк оптимизации.
+
+✅ **Как надо:**
+
+```
+"Ускорить поиск" — это может быть разное:
+
+1. Уменьшить время ответа (< 100 мс вместо 500 мс)
+   → индексы в БД, кеш частых запросов | ~2 часа
+
+2. Выдерживать больше одновременных запросов
+   → async/await, connection pooling | ~4 часа
+
+3. Субъективно казаться быстрее (UX)
+   → показывать частичные результаты сразу | ~3 часа
+
+Сейчас поиск занимает ~500 мс. Что важнее?
+```
+
+---
+
+## 2. Делай только то, что просили
+
+**Минимум, решающий задачу. Ничего лишнего.**
+
+- Не добавляй возможности сверх того, что просили.
+- Не создавай абстракции, если код используется один раз.
+- Не делай код "гибким" и "настраиваемым" без запроса.
+- Не обрабатывай ошибки, которые не могут случиться.
+- Написал 200 строк, а можно 50 — перепиши.
+
+Спроси себя: "Сказал бы опытный коллега, что это переусложнено?" Если да — упрости.
+
+### Пример: лишние абстракции
+
+**Запрос:** "Добавь функцию расчёта скидки"
+
+❌ **Что делают LLM** — Strategy pattern, ABC, dataclass, конфигуратор:
+
+```python
+class DiscountStrategy(ABC):
+    @abstractmethod
+    def calculate(self, amount: float) -> float: pass
+
+class PercentageDiscount(DiscountStrategy):
+    def __init__(self, percentage: float):
+        self.percentage = percentage
+    def calculate(self, amount: float) -> float:
+        return amount * (self.percentage / 100)
+
+@dataclass
+class DiscountConfig:
+    strategy: DiscountStrategy
+    min_purchase: float = 0.0
+    max_discount: float = float('inf')
+
+# Ещё 40 строк ради одной формулы
+```
+
+✅ **Как надо:**
+
+```python
+def calculate_discount(amount: float, percent: float) -> float:
+    """Calculate discount amount. percent should be 0-100."""
+    return amount * (percent / 100)
+```
+
+Усложнять — только когда реально появится несколько типов скидок.
+
+### Пример: возможности "на будущее"
+
+**Запрос:** "Сохрани пользовательские настройки в БД"
+
+❌ **Что делают LLM** — кеш, валидатор, флаг merge, уведомления:
+
+```python
+class PreferenceManager:
+    def __init__(self, db, cache=None, validator=None):
+        ...
+    def save(self, user_id, prefs, merge=True, validate=True, notify=False):
+        # 50 строк вместо трёх
+```
+
+✅ **Как надо:**
+
+```python
+def save_preferences(db, user_id: int, preferences: dict):
+    db.execute(
+        "UPDATE users SET preferences = ? WHERE id = ?",
+        (json.dumps(preferences), user_id)
+    )
+```
+
+Кеш, валидацию, merge — добавить тогда, когда это реально понадобится.
+
+---
+
+## 3. Трогай только то, что нужно
+
+**Правь минимум. Чисти только за собой.**
+
+При редактировании существующего кода:
+- Не "улучшай" соседний код, комментарии или форматирование.
+- Не рефактори то, что работает.
+- Сохраняй существующий стиль, даже если ты сделал бы иначе.
+- Заметил лишний код рядом — упомяни, но не трогай.
+
+Если после твоих правок что-то стало неиспользуемым:
+- Удали то, что стало ненужным из-за твоих изменений.
+- Не трогай уже существующий мёртвый код без запроса.
+
+**Проверка:** каждая изменённая строка должна напрямую относиться к запросу.
+
+### Пример: попутный рефакторинг
+
+**Запрос:** "Исправь баг — пустой email вызывает падение валидатора"
+
+❌ **Что делают LLM** — заодно улучшают валидацию email, добавляют валидацию username, меняют комментарии, пишут docstring.
+
+✅ **Как надо — только строки, связанные с пустым email:**
+
+```diff
+  def validate_user(user_data):
+      # Check email format
+-     if not user_data.get('email'):
++     email = user_data.get('email', '')
++     if not email or not email.strip():
+          raise ValueError("Email required")
+
+      # Basic email validation
+-     if '@' not in user_data['email']:
++     if '@' not in email:
+          raise ValueError("Invalid email")
+
+      # Check username  ← не трогаем, это не в задаче
+      if not user_data.get('username'):
+          raise ValueError("Username required")
+
+      return True
+```
+
+### Пример: дрейф стиля
+
+**Запрос:** "Добавь логирование в функцию upload"
+
+❌ **Что делают LLM** — заодно добавляют type hints, меняют одинарные кавычки на двойные, пишут docstring, переформатируют отступы.
+
+✅ **Как надо — сохраняй существующий стиль:**
+
+```diff
++ import logging
++
++ logger = logging.getLogger(__name__)
++
+  def upload_file(file_path, destination):
++     logger.info(f'Starting upload: {file_path}')
+      try:
+          with open(file_path, 'rb') as f:
+              data = f.read()
+
+          response = requests.post(destination, files={'file': data})
+
+          if response.status_code == 200:
++             logger.info(f'Upload successful: {file_path}')
+              return True
+          else:
++             logger.error(f'Upload failed: {file_path}, status={response.status_code}')
+              return False
+      except Exception as e:
+-         print(f"Error: {e}")
++         logger.exception(f'Upload error: {file_path}')
+          return False
+```
+
+Сохранено: одинарные кавычки, нет type hints, тот же стиль boolean-возврата.
+
+---
+
+## 4. Работай от результата
+
+**Определи, как выглядит "готово". Проверяй каждый шаг.**
+
+Переформулируй задачи в проверяемые цели:
+- "Добавь валидацию" → "Напиши тесты на некорректные данные, затем сделай их зелёными"
+- "Исправь баг" → "Напиши тест, воспроизводящий баг, затем исправь"
+- "Рефакторинг X" → "Убедись, что тесты проходят до и после"
+
+Для многошаговых задач — кратко опиши план:
+
+```
+1. [Шаг] → проверка: [что проверить]
+2. [Шаг] → проверка: [что проверить]
+3. [Шаг] → проверка: [что проверить]
+```
+
+Чёткие критерии дают возможность работать самостоятельно. Размытые ("сделай так, чтобы работало") требуют постоянных уточнений.
+
+### Пример: пошаговая реализация с проверкой
+
+**Запрос:** "Добавь rate limiting в API"
+
+❌ **Что делают LLM** — реализуют Redis, несколько стратегий, конфигурацию и мониторинг в одном PR на 300 строк без чётких шагов проверки.
+
+✅ **Как надо:**
+
+```
+План:
+
+1. Базовый лимит в памяти (один endpoint)
+   Проверка: 100 запросов → первые 10 проходят, остальные получают 429
+
+2. Вынести в middleware (все endpoints)
+   Проверка: существующие тесты не сломались
+
+3. Redis вместо памяти (для нескольких серверов)
+   Проверка: лимит сохраняется после перезапуска
+
+4. Настройка лимитов per-endpoint
+   Проверка: /search — 10/мин, /users — 100/мин
+
+Начинаем с первого шага?
+```
+
+### Пример: сначала воспроизведи баг
+
+**Запрос:** "Сортировка ломается при одинаковых значениях"
+
+❌ **Что делают LLM** — сразу меняют логику сортировки, не убедившись, что воспроизвели проблему.
+
+✅ **Как надо:**
+
+```python
+# 1. Сначала — тест, воспроизводящий баг
+def test_sort_with_duplicate_scores():
+    scores = [
+        {'name': 'Alice', 'score': 100},
+        {'name': 'Bob', 'score': 100},
+        {'name': 'Charlie', 'score': 90},
+    ]
+    result = sort_scores(scores)
+    # Проблема: при одинаковых score порядок непредсказуем
+    assert result[0]['score'] == 100
+    assert result[2]['score'] == 90
+    assert result[0]['name'] < result[1]['name']  # ожидаем стабильную сортировку
+
+# Запускаем тест → он падает → баг подтверждён
+
+# 2. Только теперь исправляем
+def sort_scores(scores):
+    return sorted(scores, key=lambda x: (-x['score'], x['name']))
+
+# Запускаем тест → зелёный
+```
+
+---
+
+## Сводка: что делать нельзя
+
+| Принцип | Типичная ошибка | Правильно |
+|---|---|---|
+| Сначала думай | Молча выбирает формат, поля, трактовку задачи | Называет предположения явно, спрашивает |
+| Делай только то, что просили | Strategy pattern ради одного расчёта | Одна функция — и точка |
+| Трогай только то, что нужно | Правит кавычки и добавляет типы при фиксе бага | Меняет только строки, касающиеся задачи |
+| Работай от результата | "Проанализирую и улучшу" | "Тест воспроизводит баг → исправляю → проверяю регрессии" |
+
+## Главный вывод
+
+Переусложнённые решения не выглядят явно неправильными — они следуют паттернам и best practices. Проблема в **моменте**: сложность добавляется раньше, чем она реально нужна.
+
+**Хорошее решение — это минимум, который решает задачу сегодня, а не задачу, которая, возможно, появится завтра.**

package/.agents/skills/karpathy-guidelines/agents/claude.json

@@ -0,0 +1,21 @@
+{
+  "name": "karpathy-guidelines",
+  "display_name": "Karpathy Guidelines",
+  "description": "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.",
+  "default_prompt": "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование.",
+  "triggers": [
+    "karpathy-guidelines",
+    "karpathy",
+    "Karpathy Guidelines",
+    "сначала думай потом делай",
+    "простота прежде всего",
+    "хирургические изменения"
+  ],
+  "capabilities": [
+    "quality",
+    "guidelines",
+    "best-practices"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/skills/karpathy-guidelines/agents/copilot.json

@@ -0,0 +1,21 @@
+{
+  "name": "karpathy-guidelines",
+  "display_name": "Karpathy Guidelines",
+  "description": "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.",
+  "default_prompt": "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование.",
+  "triggers": [
+    "karpathy-guidelines",
+    "karpathy",
+    "Karpathy Guidelines",
+    "сначала думай потом делай",
+    "простота прежде всего",
+    "хирургические изменения"
+  ],
+  "capabilities": [
+    "quality",
+    "guidelines",
+    "best-practices"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/skills/karpathy-guidelines/agents/gemini.json

@@ -0,0 +1,21 @@
+{
+  "name": "karpathy-guidelines",
+  "display_name": "Karpathy Guidelines",
+  "description": "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.",
+  "default_prompt": "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование.",
+  "triggers": [
+    "karpathy-guidelines",
+    "karpathy",
+    "Karpathy Guidelines",
+    "сначала думай потом делай",
+    "простота прежде всего",
+    "хирургические изменения"
+  ],
+  "capabilities": [
+    "quality",
+    "guidelines",
+    "best-practices"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/skills/karpathy-guidelines/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Karpathy Guidelines"
+  short_description: "Поведенческие правила для снижения типичных ошибок LLM — думай перед тем как делать, простота, хирургические изменения, ориентация на цель."
+  default_prompt: "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/.agents/skills/karpathy-guidelines/agents/qwen.json

@@ -0,0 +1,21 @@
+{
+  "name": "karpathy-guidelines",
+  "display_name": "Karpathy Guidelines",
+  "description": "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.",
+  "default_prompt": "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование.",
+  "triggers": [
+    "karpathy-guidelines",
+    "karpathy",
+    "Karpathy Guidelines",
+    "сначала думай потом делай",
+    "простота прежде всего",
+    "хирургические изменения"
+  ],
+  "capabilities": [
+    "quality",
+    "guidelines",
+    "best-practices"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/.agents/skills/karpathy-guidelines/agents/skill.yaml

@@ -0,0 +1,25 @@
+version: 1
+name: "karpathy-guidelines"
+display_name: "Karpathy Guidelines"
+description: "Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата."
+default_prompt: "Используй $karpathy-guidelines, когда задача требует соблюдения правил качества: написание кода, ревью, рефакторинг, анализ или проектирование."
+triggers:
+  - "karpathy-guidelines"
+  - "karpathy"
+  - "Karpathy Guidelines"
+  - "сначала думай потом делай"
+  - "простота прежде всего"
+  - "хирургические изменения"
+capabilities:
+  - "quality"
+  - "guidelines"
+  - "best-practices"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "ru"
+  available_locales:
+    - "ru"
+    - "en"

package/AGENTS.md

@@ -117,6 +117,9 @@
 - $security-baseline-dev
 - $compass-mongodb
 
+### Cross-cutting / Quality (все агенты, все домены)
+- $karpathy-guidelines
+
 ### Testing (QA)
 - $qa-test-plan
 - $qa-manual-run
@@ -148,6 +151,16 @@ CONDUCTOR → DEV+TEST(Fix + self-check + GO/NO-GO)
 
 ---
 
+## Обязательное правило качества (Karpathy Guidelines)
+
+**$karpathy-guidelines обязателен для всех агентов во всех доменах.** Перед любой нетривиальной задачей:
+1. **Сначала думай, потом делай** — явно называй предположения, спрашивай при неопределённости.
+2. **Делай только то, что просили** — минимум, решающий задачу. Ничего лишнего.
+3. **Правь точечно** — трогай только то, что необходимо для задачи.
+4. **Работай от результата** — определи проверяемые критерии успеха до начала работы.
+
+---
+
 ## Обязательное правило документации функций
 - Для всех функций в кодовой базе использовать JSDoc-блок в формате: