🧠 Что это — Instinct-базированное обучение для Claude Code

Intelligent Continuous Learning v2.1 — это система, которая автоматически наблюдает за вашими сессиями в Claude Code, извлекает из них маленькие повторяющиеся поведенческие паттерны («instinct'ы») и со временем превращает их в переиспользуемые навыки (skills), команды (commands) или агентов (agents). По сути, это механизм персонализации, который учится вашим предпочтениям на ходу.

Ключевое отличие от v1: вместо вероятностного срабатывания «скиллов» система использует детерминированные Hook'и (PreToolUse / PostToolUse), которые срабатывают при каждом вызове инструмента — это даёт 100% полноту наблюдения.

🛠️ Как работает

🔍 Наблюдение через Hook'и

На этапе PreToolUse (до вызова инструмента) и PostToolUse (после) срабатывает скрипт observe.sh. Он записывает в observations.jsonl:

• какие промпты задавались,
• какие инструменты вызывались и с какими параметрами,
• какие были результаты или ошибки,
• контекст проекта (определяется автоматически).

📌 Проектный контекст и изоляция

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

• переменная окружения CLAUDE_PROJECT_DIR,
• git remote get-url origin (хэшируется — даёт стабильный ID репозитория на разных машинах),
• git rev-parse --show-toplevel (запасной вариант),
• если проект не определён — instinct'ы попадают в глобальную область.

Каждый проект получает 12-символьный хэш ID (например, a1b2c3d4e5f6). Таблица соответствия хранится в ~/.claude/homunculus/projects.json. Вся файловая структура изолирована по проектам — никакой «контаминации» между проектами по умолчанию.

🧬 Instinct'ы — атомарные единицы знания

Instinct — это маленький поведенческий паттерн с одним триггером и одним действием. Пример структуры:

---
id: prefer-functional-style
trigger: "при написании новых функций"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---
# Функциональный стиль предпочтительнее
# Действие: использовать функциональные паттерны вместо классов, когда уместно.
# Доказательства:
# - 5 наблюдений предпочтения функционального стиля
# - Пользователь исправил классовый подход на функциональный 15.01.2025

Где хранятся?

• ~/.claude/homunculus/instincts/personal/ — глобальные instinct'ы (подходят для всех проектов),
• ~/.claude/homunculus/projects/project-hash/instincts/personal/ — проектные instinct'ы (только для этого проекта).

🎯 Confidence score — мера уверенности

Каждый instinct имеет оценку confidence от 0.3 до 0.9:

• 0.3 — временная догадка, рекомендуется, но не обязательно.
• 0.5 — средняя уверенность, применяется когда уместно.
• 0.7 — сильная уверенность, авто-одобрение применения.
• 0.9 — почти абсолютная уверенность, базовое поведение.

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

🔄 Эволюция — от instinct'а к готовым артефактам

Когда накоплено достаточно instinct'ов одной тематики (например, про React hooks), команда /evolve запускает кластеризацию и создаёт:

• skills/testing-workflow.md — готовый skill в Markdown,
• commands/new-feature.md — команда для быстрого доступа,
• agents/refactor-specialist.md — определение специализированного агента.

Все эволюционировавшие артефакты попадают в projects/hash/evolved/ или ~/.claude/homunculus/evolved/ (для глобальных).

🚀 Повышение scope (Promote)

Если один и тот же instinct (средняя уверенность >= 0.8) появляется в двух и более проектах, он становится кандидатом на повышение до глобального. Можно сделать это вручную:

# Повысить конкретный instinct
python3 instinct-cli.py promote prefer-explicit-errors

# Повысить все подходящие
python3 instinct-cli.py promote

# Предпросмотр без изменений
python3 instinct-cli.py promote --dry-run

✅ Когда использовать

• Автоматическое обучение — когда вы хотите, чтобы Claude Code запоминал ваши стилистические и архитектурные предпочтения по мере работы.
• Проектная адаптация — например, в React-проекте автоматически запомнять использование хуков, а в Python-проекте — dataclass'ы.
• Извлечение и повторное использование знаний — вы можете экспортировать instinct'ы (только паттерны, без кода и контента диалогов) и импортировать их в другую среду или поделиться с командой.
• Построение базы знаний — со временем система накопит библиотеку лучших практик, специфичных именно для вашего стиля работы.

⚠️ Важно знать

🛡️ Конфиденциальность

Наблюдения хранятся локально (~/.claude/homunculus/). Экспортируются только instinct'ы (поведенческие паттерны), а не сырые логи с кодом или промптами. Проектные instinct'ы изолированы друг от друга. Вы полностью контролируете, что повышается до глобального уровня и что экспортируется.

🔧 Конфигурация

Основные настройки — в ~/.claude/homunculus/config.json:

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20
  }
}

• observer.enabled — включает/выключает фоновый агент анализа (Haiku model), который переодически пересматривает наблюдения и обновляет instinct'ы.
• run_interval_minutes — как часто запускать анализ.
• min_observations_to_analyze — минимальное количество наблюдений перед анализом.

🧩 Совместимость с предыдущими версиями

• v2.1 полностью совместима с v2.0 и v1.
• Старые глобальные instinct'ы из ~/.claude/homunculus/instincts/ работают как глобальные.
• Skill'ы из ~/.claude/skills/learned/ (из v1) продолжают работать.
• Можно запускать v1 и v2 параллельно для постепенного перехода.

📋 Список команд

📁 Структура файлов (кратко)

~/.claude/homunculus/
├── identity.json              # Профиль, уровень знаний
├── projects.json              # Реестр: хэш -> имя/путь/remote
├── instincts/personal/        # Глобальные автоматические instinct'ы
├── instincts/inherited/       # Глобальные импортированные instinct'ы
├── evolved/{agents,skills,commands}/  # Глобальные эволюционировавшие артефакты
└── projects/
    └── a1b2c3d4e5f6/         # Проектный каталог
        ├── observations.jsonl
        ├── instincts/personal/  # Проектные instinct'ы
        ├── instincts/inherited/
        └── evolved/{skills,commands,agents}/  # Проектные артефакты

🤝 Интеграция с другими инструментами

• ECC-Tools GitHub App — может извлекать instinct'ы из истории репозитория.
• Homunculus — community-проект, вдохновивший архитектуру v2 (атомарные наблюдения, confidence scoring, pipeline эволюции).

Синхронизируйте навыки с Claude Cowork, Claude Code, Codex и другими.

Установка одной командой.

npx skillfish add affaan-m/everything-claude-code continuous-learning-v2