Інтелектуальний шар — 4 опори

Як Arc OS валідує, навчається, фокусується та вдосконалюється сам.

Огляд

Інтелектуальний шар розташований між повідомленнями користувача та відповідями Claude. Він працює у чотири етапи:

         INPUT                    PROCESSING                 OUTPUT
    ┌──────────────┐        ┌──────────────────┐       ┌─────────────────┐
    │ User Message  │───────►│  Context Router   │       │ Claude Response  │
    │               │        │  (skill scoring)  │       │  + eval warnings │
    │ Fix It / 👎   │        │                  │       │                 │
    │ (feedback)    │        │  Learnings       │       │ Quality metrics │
    │               │        │  (correction     │       │  logged         │
    └──────────────┘        │   injection)     │       └────────┬────────┘
                            │                  │                │
                            │  buildGsdPrompt()│        ┌───────┴────────┐
                            └────────┬─────────┘        │ Nightly Loop   │
                                     │                  │ (improvement   │
                                     ▼                  │  proposals)    │
                              Claude CLI                └────────────────┘

Опора 1: Binary Eval Engine

Що це: Декларативні правила, які перевіряють кожну відповідь перед доставкою.

Навіщо: Вивід AI повинен мати quality gates — як unit-тести для коду.

Як працює:

Кожен skill може мати файл .evals.json із правилами:

{
  "rules": [
    { "id": "gm-001", "type": "string_not_contains", "value": "--force", "severity": "warning" },
    { "id": "gm-002", "type": "max_length", "value": 4000, "severity": "info" }
  ]
}

Після того як Claude згенерував відповідь, eval engine виконує всі застосовні правила:

Pass: відповідь доставляється як є
Fail: відповідь доставляється + додається попередження-виноска

[Claude's response about git operations]
---
Eval: ⚠️ No force push | ℹ️ Response under 4000 chars

Типи правил

Тип	Що перевіряє
`string_contains`	Відповідь має містити певний текст
`string_not_contains`	Відповідь НЕ повинна містити текст
`regex_match`	Відповідь має відповідати regex-патерну
`regex_not_match`	Відповідь НЕ повинна відповідати regex
`max_length`	Відповідь має бути <= N символів
`min_length`	Відповідь має бути >= N символів

Ключові дизайн-рішення

Non-blocking: Попередження не блокують відповіді. Користувачі бачать і відповідь, і зауваження.
Per-skill: Різні skills мають різні критерії якості.
Per-project: Той самий skill може мати різні правила для різних tech-стеків.
Без AI у валідації: Правила детерміновані. Бінарний pass/fail. Без двозначності.

Дизайн-референс: Anthropic Skill Creator — структуровані evals із бінарними assertions.

Опора 2: Context Router

Що це: Інтелектуальний відбір skills, який інжектить у кожен prompt лише релевантні.

Навіщо: 25 skills, завантажених одночасно = розпорошення контексту. Модель намагається застосувати поради з deployment до code reviews.

Як працює:

Перед побудовою prompt роутер оцінює кожен зареєстрований skill відносно повідомлення користувача:

Score = (trigger matches x 2) + (keyword matches x 1)
Sort by score descending → take top 5

Приклад:

User: "Review this code for XSS vulnerabilities"

Scoring:
  code-review:     trigger "review" (2) + keyword "XSS" (1) = 3
  code-review-protocol: trigger "code review" (2)            = 2
  deployment-flow: no match                                  = 0
  git-manager:     no match                                  = 0

Injected into prompt:
  SKILLS_HINT (focus on these):
  - code-review: Security audit and code quality review...
  - code-review-protocol: Structured code review with OWASP...

Чому advisory, а не filtering

Роутер пропонує skills, але не блокує інші. Claude все одно має повний доступ.

Підхід	Ризик
Жорсткий filtering (`--allowedTools`)	Помилкова класифікація ламає сесію
Symlink-мутації	Зміни файлової системи на робочому процесі
Advisory hints	Безпечно: неправильна підказка = Claude її ігнорує

Triggers vs Keywords

Triggers (2 бали): Явні сигнали виклику. Користувач безпосередньо запитує цю можливість.

"deploy", "review", "scaffold", "audit"

Keywords (1 бал): Ширший семантичний контекст. Натякає на релевантність, не будучи командою.

"OWASP", "Docker", "CI/CD", "performance"

Дизайн-референс: Context priming — фокусована увага без жорсткого filtering.

Опора 3: Reflect Loop

Що це: Автоматичне фіксування корекцій як persistent rules.

Навіщо: Корекції AI повинні переживати рестарти. Одна корекція = постійне покращення.

Як працює:

CEO presses 🛠️ Fix It
    │
    ├── addLearning(source: "fixit", rule: "Fix requested for: <last response>")
    ├── projectLearnings reloaded from disk
    └── Fix prompt sent to Claude for immediate correction

CEO presses 👎
    │
    ├── addLearning(source: "negative", rule: "Negative feedback on: <response>")
    ├── qualityTracker.logFeedback(positive: false)
    └── projectLearnings reloaded from disk

Правила зберігаються у learnings.md:

# Learnings

## Rules

- [2026-04-03T14:22:00Z] [fixit] Always use t-call for translations in Odoo QWeb
- [2026-04-03T15:10:00Z] [negative] Avoid sudo in deployment scripts

При кожному наступному повідомленні накопичені learnings інжектяться:

LEARNINGS (past corrections — follow these rules):
- Avoid sudo in deployment scripts
- Always use t-call for translations in Odoo QWeb

Ключові властивості

Автоматично: Жодного ручного написання правил. Натискаєш кнопку → правило створено.
Persistent: Переживає рестарти бота. Записується на диск у markdown.
Per-project: Кожен child bot має власний learnings.md. Корекції для Odoo не впливають на React bot.
Найновіші першими: Найсвіжіші корекції мають найбільшу видимість у prompt.
Бюджетовано: Максимум 2000 символів у блоці LEARNINGS. Найстаріші правила випадають.

Дизайн-референс: Claude Reflect System — корекції стають постійними правилами, що запобігають регресії.

Опора 4: Karpathy Loop

Що це: Нічний автоматизований аналіз метрик якості з пропозиціями покращень, що надсилаються CEO.

Навіщо: Люди забувають переглядати продуктивність. Система має сама знаходити свої слабкі місця.

Як працює:

Щодня о 03:00 UTC запускається scripts/nightly-improve.ts:

Read registry — перебирає всі child bots із bot_registry.json
Read metrics — завантажує quality-metrics.json для кожного child
Find underperformers — фільтрує skills, де:
- applied_count >= 3 (мінімальний розмір вибірки, щоб уникнути шуму)
- І АБО success_rate < 80%, АБО feedback_negative > feedback_positive
Read learnings — витягує пов'язані патерни корекцій
Generate proposals — на основі шаблонів (детерміновано, без AI)
Send to CEO — підсумковий звіт + індивідуальні картки пропозицій у Telegram

Потік схвалення CEO

Telegram: Proposal Card
┌──────────────────────────────────────┐
│ Improvement Proposal                  │
│                                       │
│ Child: citadel-v2                     │
│ Skill: code-review                    │
│ Reason: low success rate (72%)        │
│ Feedback: 👍 4 / 👎 6                │
│                                       │
│ Related learnings:                    │
│   • Always use t-call for i18n        │
│                                       │
│ [✅ Approve]  [❌ Reject]             │
└──────────────────────────────────────┘

Approve: Backup skill.md → skill.v1.md (максимум 3 версії). Позначити approved.
Reject: Позначити rejected у proposals.json. Жодних змін не відбувається.

Ключові дизайн-рішення

Template-based proposals: AI не генерує покращення. Система визначає проблему; рішення про виправлення приймає людина.
CEO-in-the-loop: Жодного автономного переписування skills. Потрібне схвалення в один тап.
Skill versioning: Бекапи запобігають втраті даних. Максимум 3 версії на skill.
Мінімальний розмір вибірки: Skills із менш ніж 3 використаннями виключаються з аналізу (уникання false positives).

Дизайн-референс: Karpathy AutoResearch Loop — modify → verify → keep/discard → repeat. З критичним доповненням у вигляді людського схвалення.

Як 4 опори працюють разом

Day 1:
  CEO sends message → Context Router suggests relevant skills
  Claude responds → Evals check output → Warning: "No force push"
  CEO sees warning, presses Fix It → Learning saved to learnings.md

Day 2:
  CEO sends similar message → Learnings injected: "Don't use --force"
  Claude avoids the mistake → No eval warnings → thumbs-up
  Quality metrics improve for that skill

Day 30:
  Nightly loop detects git-manager skill has 95% success rate
  No proposal needed — skill is healthy

Day 30 (different skill):
  Nightly loop detects code-review at 68% success
  Sends proposal to CEO → CEO approves → skill backed up
  CEO manually improves skill.md
  Next cycle: success rate climbs

Система створює позитивний цикл зворотного зв'язку: корекції стають постійними правилами → правила покращують якість → метрики відображають покращення → нічний цикл підтверджує здоров'я.

Опора 5: Sage Worker (Phase 40.11+)

Що це: AI-аналіз skills, бенчмарки та виявлення в marketplace.

Навіщо: Ручне покращення skills не масштабується. Потрібен автоматизований аналіз якості skills та доступ до community expertise.

Як працює:

Аналіз skills

Обери будь-який skill у Skill Evolution UI → клікни "Sage Analyze" → Sage (Claude Haiku) оцінює:

Чіткість і повноту інструкцій skill
Покриття eval-правилами
Рекомендації щодо покращення

A/B-бенчмарки

Порівнюй дві версії skill:

Обери оновлення skill (PR)
Запусти бенчмарк → Sage тестує обидві версії на зразкових prompts
Результати показують порівняння якості з підсумком

Виявлення в marketplace

Шукай на claudemarketplaces.com skills, створені спільнотою:

"Sage Scout" → пошук за ключовим словом
Аналіз сумісності з твоїм проєктом
Встанови глобально або зроби fork до конкретного проєкту

Дизайн-референс: Менеджери пакетів (npm, pip) для управління AI-skills, з LLM-аналізом сумісності.