code-ai-installer 3.0.0 → 4.0.1-a

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

@@ -1,326 +1,354 @@
----
-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. Проблема в **моменте**: сложность добавляется раньше, чем она реально нужна.
-
-**Хорошее решение — это минимум, который решает задачу сегодня, а не задачу, которая, возможно, появится завтра.**
+---
+name: karpathy-guidelines
+description: Правила работы для предотвращения типичных ошибок LLM — сначала думай, делай только нужное, правь точечно, работай от результата.
+type: mandatory
+domain: content
+owners:
+  - conductor
+  - copywriter
+  - researcher
+  - reviewer
+  - strategist
+  - visual_concept
+gates:
+  - STRATEGIST
+  - RESEARCHER
+  - COPYWRITER
+  - VISUAL_CONCEPT
+  - REVIEWER
+  - RELEASE_GATE
+tech: []
+topic: []
+triggers:
+  - karpathy-guidelines
+  - karpathy
+  - Karpathy Guidelines
+  - сначала думай потом делай
+  - простота прежде всего
+  - хирургические изменения
+related: []
+budget_lines: 354
+schema_version: 1
+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. Проблема в **моменте**: сложность добавляется раньше, чем она реально нужна.
+
+**Хорошее решение — это минимум, который решает задачу сегодня, а не задачу, которая, возможно, появится завтра.**