Перейти до основного вмісту

Частина 2: Спроєктуйте контекст

Інженерія контексту — це навичка, яка відрізняє швидкий AI-результат від корисного AI-результату. Файл правил із частини 1 — лише один її елемент. Ця частина присвячена ширшій дисципліні: вирішенню того, що бачить агент і коли.

Зміна мислення полягає у відмові від питання «як сформулювати це, щоб змусити модель писати гарний код?» на користь «що потрібно знати новому члену команди, щоб ефективно вносити внесок, і як передати йому це ефективно?»

Два кошики: статичний і динамічний​

Кожен елемент контексту потрапляє в один із двох кошиків, і вибір кошика — це справжнє інженерне рішення з реальною вартістю.

Статичний контекст завантажується завжди, на кожен запит:

  • Системні інструкції
  • Файли правил (CLAUDE.md та подібні)
  • Глобальна пам'ять і персона

Він надійний — агент його ніколи не забуває — але дорогий, оскільки ви платите за кожен його токен при кожному виклику, незалежно від того, чи потрібен він для поточного завдання.

Динамічний контекст завантажується лише за потребою:

  • Навички, активовані поточним завданням
  • Результати інструментів, отримані під час виконання
  • Документи, отримані з пошукового індексу
  • Нещодавній фрагмент історії розмови

Він ефективний — ви платите лише тоді, коли інформація справді релевантна.

Пастка на обох крайнощах: занадто багато статичного контексту марнує гроші і розмиває сигнал (важливі правила тонуть у шумі), тоді як занадто мало означає, що агент забуде потрібне. Ставтеся до межі статичного/динамічного як до будь-якого іншого архітектурного рішення — переглядайте й версіонуйте його, а не дозволяйте йому складатися випадково.

Швидка інтуїція щодо вартості​

Припустімо, файл правил містить 2 000 токенів, а за сесію ви робите 50 запитів. Це 100 000 токенів лише на файл правил, оплачених 50 разів. Якщо половина цього файлу — довідковий матеріал, релевантний лише для одного завдання, ви марнуєте гроші на 49 запитів, які його не потребували. Перенесіть цю половину в навичку, що завантажується на вимогу, і вартість для решти 49 запитів зникне.

Саме тому «тримайте статичний контекст щільним і наповненим сигналом» — це не стилістична перевага, а рядок у бюджеті.

Навички: патерн для динамічного контексту​

Найефективніший спосіб керувати динамічним кошиком — це навичка: самодостатній пакет процедурних знань, який агент завантажує лише тоді, коли завдання відповідає йому.

Навички працюють через прогресивне розкриття — три шари, що завантажуються лениво:

  1. При запуску агент бачить лише легкі метадані (назву та однорядковий опис).
  2. Коли завдання відповідає, завантажуються повні інструкції.
  3. Лише якщо потрібна глибина, підтягується важкий довідковий матеріал.

Результат: легкий агент-генераліст може нести десятки спеціалізованих можливостей, платячи вартість токенів лише за ту, яку активно використовує.

Мінімальна навичка виглядає так:

---
name: stripe-refunds
description: How to issue and reconcile refunds through our billing layer. Use when a task involves refunds, chargebacks, or payment reversals.
---

# Issuing a refund

1. Look up the charge via `billing.get_charge(charge_id)`.
2. Refunds over $500 require an `approved_by` field — never auto-approve.
3. Call `billing.refund(charge_id, amount, approved_by)`.
4. Write a `RefundRecord` to the ledger in the same transaction.
5. Emit a `refund.issued` event.

See `reference/refund-edge-cases.md` for partial refunds and currency conversion.

Агент читає це лише тоді, коли завдання реально стосується повернень. В інший час воно нічого не коштує — лише однорядковий опис.

Шість видів контексту, якими слід керувати​

Вирішуючи, що надавати, думайте у шести категоріях. Більшість робочих процесів недооцінює середні чотири.

  • Інструкції — роль, цілі та межі агента (ваш файл правил).
  • Знання — документи, архітектурні діаграми, доменні дані.
  • Пам'ять — що щойно сталося (сесія) і що являє собою проєкт (довгострокова).
  • Приклади — референсні патерни з вашої власної кодової бази, а не загальні з інтернету.
  • Інструменти — точні визначення API та скриптів, які може викликати агент.
  • Обмеження — жорсткі обмеження та правила безпеки.

Пункт «приклади» заслуговує окремої уваги: один приклад із вашого реального коду навчає агента вашому стилю швидше, ніж три абзаци опису.

Не вставляйте весь репозиторій​

Поширена помилка — скинути в промпт цілий репозиторій на 100 000 токенів «щоб він мав усе». Це і дорого, і контрпродуктивно — релевантний сигнал ховається. Натомість отримуйте кілька файлів, що мають значення для поточного завдання, і дозвольте агенту запитувати більше. Усвідомлення всієї кодової бази — це завдання інструменту (індексування, пошук), а не те, що ви робите вручну при кожному промпті.

Налаштуйте власний робочий процес​

  • Перелічіть усе, що наразі є у вашому статичному контексті. Для кожного елемента запитайте: чи потрібне це кожному завданню?
  • Перенесіть специфічний для завдань матеріал із файлу правил у навички.
  • Напишіть свою першу навичку для повторюваного спеціалізованого завдання (процес повернення, патерн міграції, формат звіту).
  • Додайте кілька реальних прикладів із вашої кодової бази до файлу правил або навички.
  • Перестаньте вставляти цілі файли; дозвольте пошуку знаходити релевантне.