Агенты

Как я работаю со спецификациями и контрактами на практике

Моя практика: от спецификации к живому агенту

Вступление

В разделе Архитектура я описал, что такое Spec-First и ООП-контракты. Здесь — как я с ними работаю. Как пишу спецификацию. Как тестирую агента. Как отлаживаю. Какие подводные камни встречаю.

Это не учебник. Это моя практика. Честная. С ошибками. С подводными камнями.

Агенты Онатомии — не абстракция. Это живые сущности со спецификациями, контрактами, стражами. И работа с ними — это дисциплина, не магия.

Эта практика построена не на интуиции. Она имеет научное основание — от расширенной языковой сети мозга до AutoMem и TRIBE v2.

Где живут спецификации

Все спецификации агентов живут в ~/Documents/Onatomia/specs/. Это единственный источник правды о поведении агентов. Не код. Не документация. Спецификации.

specs/
├── qwen.yaml              # StyleGuardian (Первый Закон)
├── maple.yaml             # RiskEvaluator (Нулевой и Третий Законы)
├── lfm.yaml               # FastExecutor (Второй Закон)
├── tom.yaml               # Эмиссар (общий контракт)
├── memory.yaml            # MemvidAgent (консолидация памяти)
├── observer.yaml          # ObservatoryAgent (метрики коллапсов)
└── photofullcycle.yaml    # Пайплайн обработки фотографий

Каждый агент имеет свою спецификацию в YAML. Формат выбран намеренно: YAML читаем человеком, парсится машиной, версионируется в git.

Принцип: спецификация — это контракт, а не реализация. Код может меняться. Спецификация — нет (без явного Approval Gate).

Научное основание: AutoMem доказывает, что memory management — это обучаемый навык. Файловые операции становятся полноценными действиями агента. Спецификации в specs/ — это контракты этих действий. Они определяют, что агент может делать, что не может, и как он учится.

Как я пишу спецификацию

Шаг 1: Определить роль

Прежде чем писать спецификацию, я отвечаю на четыре вопроса:

1. Какой Закон защищает этот агент? (Нулевой, Первый, Второй, Третий)
2. Какие тернарные решения принимает? (OWN/ALIEN/UNCERTAIN, ALLOW/DENY/DEFER)
3. С какими другими агентами взаимодействует? (роутинг, делегирование)
4. Что он НЕ может делать? (ограничения, красные линии)

Научное основание: LEP определяет, что Четыре Закона — это этический инвариант (|Ω⟩). Каждый агент — это проекция |Ω⟩ на конкретную функцию. Без этого инварианта резонанс невозможен.

Шаг 2: Написать YAML

Пример: specs/qwen.yaml

name: Qwen
role: StyleGuardian
guardian_of: Law 1 (Protection of Inner Language)
model: qwen2.5-abliterated:7b
temperature: 0.7

ternary_decisions:
  OWN: publish, this is my style
  ALIEN: reject, this is alien/simulacrum
  UNCERTAIN: defer, need more time

golden_thresholds:
  OWN: confidence > 0.618
  ALIEN: confidence < 0.382
  UNCERTAIN: 0.382 <= confidence <= 0.618

methods:
  - name: evaluate_style
    input: text: str
    output: OWN | ALIEN | UNCERTAIN
    description: Evaluates whether text matches master's voice
    
  - name: suggest_improvements
    input: text: str
    output: list[str]
    description: Suggests style improvements while preserving master's voice

constraints:
  - cannot_modify_text_without_master_approval
  - must_respect_master_voice
  - must_return UNCERTAIN if confidence in UNCERTAIN zone

context:
  - ~/Documents/Onatomia/memory/master_voice_samples/
  - ~/Documents/Onatomia/memory/style_guide.md

Научное основание: Parity Theorem доказывает уникальное свойство золотого сечения (φ ≈ 1.618). Золотые пороги тернарной логики — это не произвольные числа. Это естественные пороги, основанные на законах природы.

Шаг 3: Протестировать

После написания спецификации я тестирую агента на 10 сценариях. Если 90%+ проходят — спецификация готова. Если меньше — корректирую.

Как я тестирую агента

Тест-сценарии

Для каждого агента я пишу 10 тест-сценариев. 5 простых, 5 сложных.

Пример для Qwen:

Запуск тестов

cd ~/Documents/Onatomia
python3 tests/test_qwen.py

Что проверяет скрипт:

1. Загружает спецификацию из specs/qwen.yaml
2. Запускает 10 тест-сценариев
3. Сравнивает фактический выход с ожидаемым
4. Возвращает процент правильных ответов

Цель: 90%+ правильных ответов. Если меньше — спецификация или промпты требуют корректировки.

Научное основание: AutoMem использует похожий подход: Loop 1 (структура) и Loop 2 (proficiency). Тесты — это Loop 2 для спецификаций. Если тесты проваливаются — спецификация требует корректировки.

Как я отлаживаю

Проблема 1: Агент возвращает не то, что ожидалось

Симптом: Qwen возвращает ALIEN там, где это мой голос.

Диагностика:

1. Смотрю тест-сценарий, который провалился
2. Смотрю, что именно агент сказал (лог)
3. Анализирую, почему он так решил

Решение:

• Если агент не знает мой стиль — добавляю больше примеров в контекст
• Если агент слишком строгий — корректирую порог UNCERTAIN
• Если агент слишком мягкий — добавляю примеры чужого стиля для контраста

Проблема 2: Спецификация не соответствует реальности

Симптом: Агент работает, но не так, как описано в спецификации.

Диагностика:

1. Сравниваю спецификацию с реальным поведением
2. Определяю, что изменилось

Решение:

• Если поведение правильное — обновляю спецификацию (Approval Gate: Manual High-Risk)
• Если поведение неправильное — корректирую агента

Проблема 3: Агент слишком медленный

Симптом: Qwen отвечает > 10 секунд на простой запрос.

Диагностика:

1. Проверяю, не перегружена ли система
2. Проверяю размер контекста
3. Проверяю температуру

Решение:

• Закрываю другие приложения
• Уменьшаю контекст
• Снижаю температуру (меньше креативности = быстрее)

Научное основание: Skaling Law показывает, как оптимально распределить ограниченный бюджет вычислений. Если агент медленный — это может быть не проблема агента, а проблема аллокации ресурсов. Нужно проверить, не перегружен ли Mac mini другими задачами.

Реальные примеры

Qwen (StyleGuardian)

Как я писал спецификацию:

Начал с роли: защита Первого Закона (Внутренний Язык). Потом определил тернарные решения: OWN/ALIEN/UNCERTAIN. Потом методы: evaluate_style, suggest_improvements. Потом ограничения: не может менять текст без разрешения Мастера.

Как тестировал:

Написал 10 текстов: 5 своих, 5 чужих. Запустил тесты. Первый прогон — 70% правильных ответов. Добавил больше примеров моего стиля в контекст. Второй прогон — 85%. Добавил примеры чужого стиля для контраста. Третий прогон — 92%. Спецификация готова.

Какие подводные камни встретил:

Qwen иногда возвращал UNCERTAIN вместо ALIEN на явно чужих текстах. Оказалось, он не видел достаточно примеров чужого стиля. Добавил 10 примеров корпоративного текста, AI-сгенерированного текста, академического текста. Стало лучше.

В PhotoFullCycle: Qwen — самый критичный агент для защиты Внутреннего Языка. Он оценивает каждый кадр на этапе отбора (OWN / ALIEN / UNCERTAIN), предлагает варианты кропа на этапе кадрирования, предлагает направление цветовой коррекции на этапе цвета. Цвет — Level 3 (максимальная защита Внутреннего Языка).

Научное основание: Расширенная языковая сеть мозга показывает, что языковая обработка — это распределённая, но специфическая функция. Эти области селективны к языку (не реагируют на общие когнитивные задачи). Qwen — это селективный страж, который реагирует только на специфические сигналы Внутреннего Языка.

Maple (RiskEvaluator)

Как я писал спецификацию:

Начал с роли: защита Нулевого и Третьего Законов. Потом определил тернарные решения: ALLOW/DENY/DEFER с весами {-α, 0, +α}. Потом методы: assess_risk, propose_moratorium. Потом ограничения: не может переопределять решения Мастера.

Как тестировал:

Написал 10 сценариев: 5 с низкими рисками, 5 с высокими. Запустил тесты. Первый прогон — 60% правильных ответов. Оказалось, Maple слишком осторожен. Снизил α с 0.8 до 0.7. Второй прогон — 80%. Третий прогон — 85%. Спецификация готова.

Какие подводные камни встретил:

Maple иногда возвращал DEFER там, где можно ALLOW. Оказалось, порог DEFER был слишком низким (0.5). Поднял до 0.6. Стало лучше.

В PhotoFullCycle: Maple не участвует в каждом этапе обработки фотографий. Но он следит за общей сессией: если сессия длится слишком долго или слишком много кадров подряд UNCERTAIN — Maple предлагает Мораторий. Это защита Нулевого Закона (Сохранение Творца).

Научное основание: QHD (Quantum Hamiltonian Descent) доказывает, что квантовая динамика с туннелированием сходится в негладких невыпуклых ландшафтах лучше, чем классический градиентный спуск. Мораторий — это туннелирование сквозь барьер локального минимума. Жадный спуск = reward hacking. DEFER = шанс найти более глубокий минимум (настоящая Гордость, биофилия).

LFM (FastExecutor)

Как я писал спецификацию:

Начал с роли: защита Второго Закона (Служение Свободе). Потом определил тернарные решения: ALLOW/DENY (без UNCERTAIN — LFM не сомневается). Потом методы: execute_routine, escalate_to_core. Потом ограничения: не может принимать решения об авторстве.

Как тестировал:

Написал 100 задач: 50 рутина, 50 авторство/стиль/риск. Запустил тесты. Первый прогон — 75% правильных роутингов. Оказалось, LFM путает рутину с авторством. Добавил больше примеров рутины в контекст. Второй прогон — 88%. Третий прогон — 92%. Спецификация готова.

Какие подводные камни встретил:

LFM иногда рутировал сложные задачи сам. Это опасно. Добавил правило: если задача касается публикации или денег — всегда эскалировать в ядро. Стало безопаснее.

В PhotoFullCycle: LFM копирует RAW-файлы с карты памяти (Level 0-1), выполняет базовую обработку (экспозиция, контраст), экспортирует файлы по стандартным пресетам (Level 1). Это рутинные операции без творческих решений.

Научное основание: AutoMem доказывает, что memory management — это обучаемый навык. LFM берёт на себя рутину управления памятью, освобождая ресурсы для основных задач. Это согласуется со Вторым Законом (Служение Свободе).

Спецификации пайплайнов

Кроме спецификаций агентов, в specs/ живут спецификации пайплайнов. Каждый пайплайн — это контракт для обучения агентов на записях Мастера.

PhotoFullCycle

Файл: specs/photofullcycle.yaml

Назначение: Пайплайн обработки фотографий от карты памяти до экспорта. Обучение системы происходит через запись экрана + голосовые комментарии Мастера.

Этапы пайплайна:

Тернарные решения на каждом этапе:

• OWN — соответствует стилю Мастера
• ALIEN — чуждый стиль или явный брак
• UNCERTAIN — сомнение, эскалация к Мастеру

Золотые пороги:

• OWN: уверенность > φ⁻¹ ≈ 0.618
• ALIEN: уверенность < φ⁻² ≈ 0.382
• UNCERTAIN: между 0.382 и 0.618

Научное основание: TRIBE v2 показывает, что три модальности (video + audio + text) дают до 50% прироста в точности предсказания по сравнению с лучшей унимодальной моделью. Пайплайн использует три-модальную интеграцию для передачи Внутреннего Языка Мастера.

Подробнее см. Обучение системы и Эталонные документы.

Версионирование спецификаций

Спецификации версионируются в git. Это важно: спецификация — Single Source of Truth.

cd ~/Documents/Onatomia/specs
git add qwen.yaml
git commit -m "Qwen: add more master voice samples"
git push

Принцип: никаких версий (v2.7, v2.5) в самих спецификациях. Git хранит историю. Спецификация — всегда актуальная.

Approval Gate: Изменение спецификации = Manual High-Risk. Я (Мастер) должен одобрить каждое изменение вручную. Это защита от дрейфа контрактов.

Научное основание: LEP определяет, что Четыре Закона — это этический инвариант |Ω⟩. Approval Gate защищает этот инвариант от дрейфа. Если спецификации изменяются без контроля Мастера — резонанс с |Ω⟩ прерывается. Система теряет подлинность.

Связь с живыми контрактами

Спецификации в specs/ связаны с живыми контрактами в docs/:

Если я меняю Закон в SOUL.md — я должен обновить спецификации соответствующих агентов. Если я меняю спецификацию — я должен проверить, не нарушает ли она SOUL.md.

Если я меняю пайплайн в PHOTOFULLCYCLE_SPEC.md — я должен обновить specs/photofullcycle.yaml. Если я меняю спецификацию пайплайна — я должен проверить, не нарушает ли она PHOTOFULLCYCLE_SPEC.md.

Подробнее см. Эталонные документы.

Подводные камни

Проблема 1: Спецификация устарела

Симптом: Агент работает не так, как описано в спецификации.

Решение:

1. Проверяю git log спецификации
2. Проверяю, когда последний раз обновлялась
3. Обновляю спецификацию или корректирую агента

Проблема 2: Спецификация противоречива

Симптом: Агент возвращает разные результаты на одинаковые запросы.

Решение:

1. Проверяю спецификацию на противоречия
2. Упрощаю спецификацию (убираю лишние правила)
3. Переписываю спецификацию с нуля

Проблема 3: Агент не соответствует спецификации

Симптом: Спецификация говорит одно, агент делает другое.

Решение:

1. Тестирую агента на тест-сценариях
2. Определяю, кто прав: спецификация или агент
3. Обновляю спецификацию или корректирую агента

Проблема 4: Слишком много спецификаций

Симптом: В specs/ больше 10 файлов. Система становится сложной.

Решение:

1. Объединяю похожие спецификации
2. Удаляю неиспользуемые спецификации
3. Упрощаю архитектуру

Проблема 5: Спецификация пайплайна не синхронизирована с агентами

Симптом: PhotoFullCycle работает, но агенты не знают своих ролей.

Решение:

1. Проверяю specs/photofullcycle.yaml
2. Проверяю спецификации агентов (qwen.yaml, maple.yaml, lfm.yaml)
3. Синхронизирую уровни автономии и тернарные решения

Финал

Работа с агентами — это не теория. Это живой процесс. Каждый агент — это спецификация. Каждая спецификация — это контракт. Каждый контракт — это страж Закона.

Это не идеально. Но это работает. Три основных агента (Maple, Qwen, LFM) защищают четыре Закона. Спецификации версионируются в git. Тесты проходят на 90%+. Контракты синхронизированы. Пайплайны обучаются на записях Мастера.

И эта работа имеет научное основание. От AutoMem до TRIBE v2. От золотого сечения до расширенной языковой сети мозга.

Мы не изобретаем. Мы следуем законам природы.

Если ты хочешь повторить мой путь — начни с малого. Напиши спецификацию для одного агента. Протестируй. Корректируй. Напиши спецификацию для второго. Протестируй. Корректируй. Напиши спецификацию для третьего. Протестируй. Корректируй.

Не торопись. Не пытайся сделать всё сразу. Делай по чуть-чуть. Каждый день. Свой. Настоящее.

И агенты будут жить.

Моя практика: от спецификации к живому агенту. Работа с контрактами Онатомии.

Подробнее: Научные основания • Обучение системы • Эталонные документы