Модель пише наряд, верстак його виконує

Автодоповнення дописує поточний рядок. Чат пояснює виділений шматок. Кодовий агент бере формулювання задачі і сам ходить репозиторієм, поки не з'явиться зміна і перевірка. Різниця не в «розумнішій моделі». Різниця в тому, що навколо моделі стоїть програма зі станом, інструментами і правом сказати «ні».

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

Стійкі частини такої системи однакові в термінального агента, в агента в редакторі і в агента в хмарному середовищі. Змінюється оболонка, не набір обов'язків.

Це ролі, не дерево каталогів. У OpenCode частина ролей живе в packages/core, інтерфейс рознесено по packages/tui, packages/app і packages/desktop, а постачальників моделей підключають через пакети в packages/ai. У закритому продукті ті самі ролі можуть сидіти в одному процесі.

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

Цикл крутиться, поки форма не перестане падати

Спрощений цикл виглядає так. Це навчальний нарис, не код OpenCode.

async function runAgent(task: string) {
  const messages = await prepareContext(task);

  while (true) {
    const response = await llm.generate({
      messages,
      tools: toolRegistry.definitions(),
    });

    if (response.stopReason === "end_turn") {
      return response.content;
    }

    if (response.stopReason === "tool_use") {
      for (const call of response.toolCalls) {
        const result = await executeTool(call.name, call.arguments);
        messages.push(response, result);
      }
    }
  }
}

На задачі «після збереження форми HTTP 500» добрий хід майже ніколи не починається з патча. Спочатку пошук контролера і маршруту. Потім читання перетворення вхідних даних. Потім гіпотеза: падає приведення типу, а не сам запис у базу. Потім правка. Потім тест. Якщо тест червоний, у цикл повертається текст помилки, і гіпотеза змінюється. Лінійний план із восьми пунктів на слайді тут бреше. Агент повертається до пошуку, викидає першу здогадку і іноді пише тест, якого не було у вихідному формулюванні.

Реальний цикл товщий за підручник. Потокове породження, кілька викликів за один хід, скасування, повтор у разі збою постачальника, межа ітерацій і ущільнення історії. У документації Anthropic цикл для клієнтських інструментів зав'язаний на stop_reason: поки причина зупинки tool_use, застосунок виконує виклики і шле tool_result. Вихід із циклу буває і за end_turn, і за лімітом токенів, і за відмовою.

У гілці dev репозиторію anomalyco/opencode цей хід зібрано в packages/core/src/session/runner/llm.ts. Функція прогону крокує циклом: підготувати межу кроку, виконати крок, збільшити лічильник. Перед запитом оцінюється розмір контексту. Якщо він не вміщується, спрацьовує ущільнення. Якщо в агента задано межу кроків і лічильник її досяг, у запит додається текст про межу, а вибір інструмента вимикається (toolChoice: "none"). Модель на цьому ході вже не викликає інструменти, а мусить згорнути роботу. Окремий шлях повторює запит, якщо постачальник відповів збоєм.

Помилка команди тут корисніша за гладке «готово». Упалий тест повертає факт. Модель може прочитати його і змінити гіпотезу. Може і зациклитися: той самий пошук, та сама правка, та сама червона перевірка. У дозволах OpenCode для цього є окремий запобіжник doom_loop: три однакові виклики з тим самим входом типово питають людину.

Постачальників варто ховати за одним інтерфейсом. OpenCode на dev позначає пакети постачальників префіксом aisdk: і підвантажує їх як модулі. Зовні лишаються різні вікна контексту, різні формати виклику інструментів і різна ціна. Дешеву модель розумно ставити на класифікацію і короткі службові ходи, сильну на проєктування правки, локальну на шматок, який не можна надсилати назовні. Рахунок за такі кола рахують не за одним запитом, а за доведеною задачею. Це розібрано в токеноміці програмування з моделлю.

Репозиторій у запит не потрапляє сам

Ваги моделі не містять вашого репозиторію. Якщо програма не поклала файл у запит, для цього ходу файла немає. Тому «агент вивчив проєкт» завжди означає, що якийсь код заздалегідь обрав, що показати.

Для пошуку функції вистачає тексту. OpenCode ганяє grep і glob через ripgrep і типово шанує .gitignore. Це дешево і точно, коли відомі ім'я, рядок або шлях.

Для питання «хто ще зламається, якщо змінити це приведення типу» тексту мало. Потрібні місця виклику, інтерфейс, залежності і тести. Мовний сервер відповідає на частину такого питання: визначення, посилання, ієрархія викликів. У документації OpenCode інструмент lsp позначений як експериментальний і вмикається окремим прапорцем. У ньому є перехід до визначення, пошук посилань, символ документа і вхідні та вихідні виклики. Це вже не пошук за рядком.

Векторний пошук корисний, коли людина описала поведінку словами, а ім'я функції в голові не спливло. Він погано замінює точний збіг ідентифікатора і легко притягує сусідній модуль, який «про те саме». Індекс усього репозиторію окупається на великому дереві і на повторюваних питаннях. На маленькому сервісі агент частіше доходить до потрібного файла двома викликами glob і grep, без окремої бази векторів. Як влаштований пошук за документами в прикладній системі, поруч лежить розбір виробничого RAG.

Окремо в запит потрапляють правила проєкту. Команда /init в OpenCode створює AGENTS.md: як збирати, як перевіряти, які домовленості не видно з імен файлів. Глобальний файл у ~/.config/opencode/AGENTS.md додає особисті правила. Якщо свого файла немає, читається CLAUDE.md. Це не пам'ять про минулі сесії. Це інструкція, яку програма підмішує в контекст кожної нової зміни.

Інструмент викликає програма, не модель

Модель не вміє відкрити диск. Вона вміє повернути ім'я інструмента й аргументи за схемою, яку застосунок поклав у запит. Далі шість кроків, і всі вони в програмі: описати схему, віддати її моделі, прийняти вибір, перевірити дозвіл, виконати, повернути результат.

У публічній документації OpenCode вбудовані інструменти називаються так: read, write, edit, apply_patch, grep, glob, bash, lsp, todowrite, webfetch, websearch, question, skill. Правка файлів сидить під одним дозволом edit. На гілці dev на початок листопада 2026 модулі називаються трохи інакше: shell.ts замість bash, patch.ts замість apply_patch, subagent.ts замість окремого імені task зі старіших сторінок. Імена звіряйте з тією версією, яку запускаєте. Ролі ті самі.

edit змінює файл точною заміною рядка. write створює файл або перезаписує його. patch несе кілька операцій в одному тексті: додати, оновити, перенести, видалити. question зупиняється і питає людину. skill підвантажує текст навички, а не виконує довільний код сам по собі.

Є і виняток із формули «модель нічого не запускає». У Anthropic частина інструментів виконується на боці постачальника: пошук у мережі, завантаження сторінки, виконання коду в їхньому середовищі. Застосунок тоді не збирає tool_result сам. Для файлів вашого репозиторію цей виняток не працює. Їх як і раніше чіпає ваш процес.

Свої інструменти в OpenCode описуються схемою і функцією execute. Плагін із тим самим ім'ям, що у вбудованого інструмента, замінює вбудований. Зовнішні сервіси підключаються окремо, через MCP, і з'являються поряд із вбудованими викликами. Протокол спільний. Виконання все одно проходить через той самий цикл і ті самі дозволи.

Три замки: інструкція, дозвіл, ізоляція

Уявіть команду, яка стирає корінь диска, або читання файла з секретом і відправлення його назовні. Текст «будь обережний» у системній інструкції цього не зупиняє. Інструкція впливає на те, що модель схильна запитати. Якщо запит усе ж прийшов, вирішує застосунок. Якщо застосунок дозволив запуск, процес ще можна замкнути так, щоб шкода не вийшла за каталог і мережу.

У Explore у вихідниках dev це видно на одному агенті. Системний текст забороняє створювати і змінювати файли і вимагає, щоб команди оболонки були лише на читання. Поруч таблиця дозволів: спочатку заборона всього, потім точкова дозвіл read, grep, glob, shell, webfetch і websearch. Читання *.env питає людину, *.env.example дозволено. Заборона в тексті і заборона в таблиці збігаються за наміром. Збіг не робить їх одним механізмом. Текст модель може проігнорувати. Таблиця відхиляє виклик до запуску.

Дозволи в документації зводяться до трьох наслідків: allow, ask, deny. Останнє правило, що збіглося, перемагає, тому загальний шаблон * ставлять першим, а часткові винятки після нього. Так можна дозволити git status і питати на git push, заборонити rm *, пускати правки лише в каталог документації. Каталоги поза коренем проєкту закриває external_directory: типово питання людині. Три однакові виклики поспіль ловить doom_loop.

ask в інтерфейсі дає три відповіді: один раз, завжди для цього шаблону до кінця сесії, відмова. Режим --auto сам підтверджує те, що інакше запитало б. Явний deny він не знімає.

Третій замок стоїть нижче. Каталог на диску, окремий користувач, контейнер, мережа без виходу назовні, журнал команд. OpenCode з коробки не є такою пісочницею: він виконує команди в середовищі проєкту і спирається на дозволи. Ізоляцію процесу додають окремо, тим самим Docker або іншою межею операційної системи. Знімок файлів, який уміє packages/core/src/snapshot.ts (capture, diff, restore), відкочує правки агента. Він не скасовує команду, яка вже пішла в мережу.

У Cursor публічно описані свої контрольні точки: знімок змінених файлів перед великою правкою, зберігається локально і окремо від git. Відкат точки повертає файли і не стирає повідомлення діалогу. Це четвертий, продуктовий контур відкату. Він теж не замінює ні дозволи, ні ізоляцію.

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

Сесія пам'ятає довше, ніж вікно

Зміна на кілька годин не мусить вміщатися в один запит. Програма зберігає репліки людини, відповіді моделі, виклики інструментів, результати, список справ, diff файлів і короткі зведення. Вікно моделі зберігає лише те, що влізло в черговий запит.

У OpenCode сесія вміє ущільнюватися. На гілці dev у packages/core/src/session/compaction.ts запас типово такий: лишати вільними близько 15% вікна і не менше 16 тисяч токенів. Поруч зі зведенням зберігається хвіст недавнього листування дослівно. Зведення можна рахувати заздалегідь, у фоні, щоб у момент переповнення не чекати його з нуля. Привід буває автоматичний, ручний (/compact) і аварійний: постачальник відхилив контекст як надто довгий. Прихований агент Compaction для цього існує окремо від Build. Плагін може дописати в промпт ущільнення свої факти через хук experimental.session.compacting.

Стиснення втрачає деталі. Тому в хвості тримають останні рішення, а в зведенні лишають, які файли чіпали і що ще не зроблено. Якщо після ущільнення агент знову шукає той самий файл, зведення виявилося надто бідним. Це лагодиться вмістом зведення, а не довшим вікном.

Поруч живуть службові агенти, яких не можна обрати в інтерфейсі. Title називає сесію короткою фразою. Summary пише два-три речення в дусі опису до запиту на злиття. Обоє у вихідниках позбавлені інструментів. Вони не лагодять код. Вони пакують журнал, щоб людина знайшла зміну потім.

Знімок файлів і журнал повідомлень розходяться. Відкат знімка повертає дерево файлів. Історія діалогу при цьому може лишитися. У документації OpenCode команда /undo повертає і правки, і вихідне повідомлення, щоб формулювання можна було поправити і запустити знову. Перед роботою корисно знати, який із двох відкатів ви натискаєте.

Другий агент ділить роботу і файли

Одного диспетчера вистачає, поки наряд один. Коли пошук деревом, правка і прогін тестів заважають одне одному в одному вікні, роботу віддають другому агенту. Виграш з'являється, якщо в другого свій стіл. Якщо обидва пишуть в один файл, час іде на стикування.

У OpenCode основні агенти видно людині, і вони перемикаються клавішею Tab. Подагента викликає основний, або людина згадує його через @. Дочірня сесія відкривається окремо, в неї можна зайти і повернутися до батька.

На гілці dev ролі такі.

Build працює типово і виконує інструменти в межах дозволів. Plan теж основний, але правки заборонені скрізь, крім каталогу ~/.opencode/plan. У контекст підмішується нагадування: реалізацію не робити, поки людина не перемкне агента. Якщо правка все ж упреться в заборону, повідомлення про помилку каже, що файл поза цим каталогом. Публічна документація описує близьке правило для файлів плану в .opencode/plans/. Звіряйте шлях із версією: намір один, каталог у коді і в документації може називатися по-різному.

Explore шукає деревом і не повинен нічого змінювати. Йому ще й заборонено кликати подагентів. В описі для моделі прямо задають глибину: швидкий прохід, середній або докладний обхід. General бере багатокрокову роботу і може змінювати файли, але сам не ставить питань людині і не породжує наступних подагентів. Інакше ланцюжок агентів росте без нагляду.

Паралельний запуск має сенс на незалежних шматках: один шукає виклики, другий читає тести, третій дивиться конфігурацію. Спільний файл, спільна міграція, один і той самий модуль авторизації так не діляться. Для ізоляції правок у git є окремі робочі дерева. У packages/core/src/worktree.ts це окрема служба, а не «просто ще один чат». Конфлікт двох патчів на одному рядку все одно лишається конфліктом.

Координатор, який лише роздає задачі, теж коштує грошей. Кожен подагент тягне свій контекст. Зведення нагору має бути коротшим за вихідний пошук, інакше батьківське вікно забивається чужими журналами. У документації Cursor для великої роботи описано схожий прийом зовні: проєктний агент планує і роздає шматки іншим агентам. Як влаштований обмін усередині, сторінка не показує.

Розширення не замінюють цикл

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

MCP додає чужі інструменти за спільним протоколом. У OpenCode сервер буває локальним (команда, свій каталог, змінні оточення) і віддаленим (адреса, заголовки, OAuth). Імена інструментів отримують префікс сервера, і на них діють ті самі дозволи, включно з шаблоном mymcp_*. Кожен сервер роздуває опис інструментів у запиті. Документація прямо попереджає: сервер GitHub легко з'їдає вікно. Вмикають той сервер, який потрібен цій задачі, і вимикають решту.

Навичка влаштована інакше. Це файл SKILL.md з іменем і коротким описом. Модель бачить список описів і завантажує повний текст інструментом skill, коли він знадобився. Так у контекст не потрапляють усі інструкції одразу. Навички шукають у .opencode/skills/, у сумісних каталогах .claude/skills/ і .agents/skills/, плюс глобально в домашньому каталозі. Дозвіл skill може сховати внутрішні навички шаблоном internal-*.

Плагін змінює сам застосунок. Хук tool.execute.before бачить аргументи до запуску. Ним закривають читання .env або екранують команду. Хук tool.execute.after бачить результат. Події сесії, дозволів і діагностики мовного сервера теж доступні. Свій інструмент реєструється поряд із вбудованими. Це не MCP: плагін живе всередині процесу агента, а MCP приносить чужий сервер.

Мовний сервер доповнює картину структури. Він не замінює grep і не дає права на запис. Він відповідає, де символ оголошений і хто його викликає, якщо сервер для цієї мови піднято.

Креслення відкритого агента на гілці розробки

Ім'я OpenCode трапляється у двох несумісних історіях. Репозиторій opencode-ai/opencode архівовано 18 вересня 2025 року. У README написано, що проєкт продовжено як Crush, разом із командою Charm. Сучасний агент із цим іменем живе в anomalyco/opencode, ліцензія MIT, інтерфейси: термінал, настільна програма, розширення редактора. Читати вихідники старого архіву, щоб зрозуміти поточний цикл, безглуздо.

Гілка dev на початок листопада 2026 розкладається так. Це мапа для читання, не обіцянка, що шлях не переїде наступного місяця.

Корисний порядок читання короткий. Спочатку agent.ts і plan.ts, щоб побачити, чим Build відрізняється від Plan і Explore не лозунгом, а списком дозволів. Потім один інструмент, наприклад read.ts або shell.ts, від схеми до виконання. Потім цикл у llm.ts: де оцінюється контекст, де викликається ущільнення, де обриваються інструменти за лімітом кроків. Плагіни і MCP після цього читаються як додаток до вже зрозумілої шафи, а не як окремий продукт.

Документація на opencode.ai описує поведінку, яку бачить людина: Tab між агентами, /init, /undo, конфіг opencode.json. Вихідники dev описують, як це зібрано. Коли імена розходяться (bash і shell, каталог планів), вірити варто тій версії, яку ви запускаєте, і поруч тримати обидві назви.

Закриті агенти видно лише зовні

Внутрішні каталоги цих трьох продуктів публічно не розібрані так, як packages/core. Порівнювати можна контракт, описаний у документації, і не приписувати їм файли, яких зовні немає.

Cursor в огляді агента називає три частини: інструкції, інструменти і модель. Інструкції включають системний текст і правила. Інструменти шукають деревом, читають і правлять файли, запускають термінал, ходять у браузер, ставлять питання. Окремої стелі на число викликів за задачу документація не ставить. Контрольні точки знімають змінені файли і відкочуються окремо від git. Для великої роботи описано координатора, який планує і роздає шматки. Повідомлення можна поставити в чергу до кінця поточного ходу або надіслати одразу, щоб воно потрапило на найближчу межу інструмента. Це той самий цикл «модель, інструмент, знову модель», упакований у редактор. Як влаштований індекс репозиторію, ця сторінка не розкриває. Його місце в конвеєрі середовища показано в статті про IDE і код.

Claude Code зовні впізнається за тим самим контрактом Anthropic. Модель повертає tool_use, процес на машині розробника виконує читання, правку і команду, результат повертається в діалог. Схеми на кшталт оболонки і текстового редактора в Claude натреновані заздалегідь, тому свої імена для тих самих дій часто викликаються гірше, ніж знайомі. Права, межа контексту і зведення історії лишаються обов'язком застосунку навколо моделі. OpenCode навіть читає CLAUDE.md і каталог навичок .claude/skills/, якщо своїх файлів немає. Сумісність файлів не означає спільний вихідний код.

Codex у публічному описі OpenAI бере задачу за репозиторієм і може виконувати її в ізольованому середовищі, окремо від вашого ноутбука. Назовні видно доручення, межу виконання і повернення змін. Не видно, як саме влаштовані черга, знімок і вибір моделі всередині. Для архітектури важливий сам прийом: верстак можна винести з локального процесу, а журнал і рев'ю лишити в людини.

Спільний рисунок такий. OpenCode показує шви. Cursor показує, як ті самі шви сидять у редакторі з контрольними точками і координатором. Claude Code показує сильний контракт виклику інструментів на локальній машині. Codex показує винесене середовище виконання. Вибір продукту під задачу, а не під логотип, лежить в огляді альтернатив Cursor.

Свого агента збирають шарами

Повторювати OpenCode цілком не потрібно. Навчальний агент на TypeScript корисний тим, що кожен шар можна ввімкнути окремо і побачити, де ламається поведінка. Стек спокійний: Node.js, клієнт API або AI SDK, Zod для схем інструментів, SQLite для журналу сесії. Мовний сервер і tree-sitter підключають на шарі структури коду. Контейнер підключають на шарі ізоляції, не в перший день.

1. Клієнт моделі. Один запит, одна відповідь, потоковий вивід. Без інструментів. Якщо цей шар бреше, цикл лише розмножить помилку.
2. Три інструменти читання: список файлів, читання діапазону, пошук за текстом. Схеми короткі, шляхи лише всередині кореня проєкту.
3. Цикл. Модель сама обирає інструмент. Результат повертається в історію. Є межа кроків і причина зупинки.
4. Запис. Спочатку точна заміна фрагмента, потім створення файла. Кожна правка лишає diff, який людина може прочитати.
5. Термінал. Одна команда перевірки, яку ви самі вважаєте безпечною: тест або збірка. Вивід обрізається, код повернення потрапляє в наступний запит.
6. Збірка контексту. Правила проєкту окремим файлом, історія сесії в SQLite, ущільнення, коли оцінка токенів переступила поріг.
7. Дозволи. Заборона шляхів поза коренем, питання на руйнівні команди, журнал викликів. Контейнер навколо термінала, коли команда більше не обмежується одним тестовим сценарієм.
8. Другий агент. Один шукає, другий править. У дослідника немає запису. Спільний файл вони не чіпають паралельно.

Каталог може виглядати так, коли шари вже є. На першому етапі з нього живі лише llm і cli.

mini-coding-agent/
├── src/
│   ├── agent/
│   │   ├── loop.ts
│   │   └── subagent.ts
│   ├── llm/
│   │   └── provider.ts
│   ├── context/
│   │   ├── builder.ts
│   │   └── compaction.ts
│   ├── tools/
│   │   ├── registry.ts
│   │   ├── filesystem.ts
│   │   └── terminal.ts
│   ├── security/
│   │   └── permissions.ts
│   ├── sessions/
│   │   └── storage.ts
│   └── cli/
│       └── index.ts
└── package.json

Критерій готовності задайте зовні моделі. Збірка проходить. Призначений тест зелений. diff не чіпає файли поза задачею. Фраза моделі «я виправив» без цього критерію не закриває наряд.

Вартість тримається тими самими ручками, що й у великому агенті. Межа кроків. Короткий хвіст замість усієї історії. Дешева модель на пошуку, сильна на правці. Кеш незмінного префікса, якщо постачальник його дає. Подагент лише коли його зведення коротше за самостійний пошук батька.

Повністю локальна зміна збирається з тих самих шарів: локальна модель, локальний пошук, локальний журнал, термінал без мережі. Компроміс у якості моделі і в тому, що індекс і мовний сервер треба підняти самим. Мапа тем для роботи без зовнішнього API лежить у дорожній карті офлайн-інженера.

Часті питання

Що почитати на сайті

Суміжні розбори на сайті, від загальної будови середовища до ціни і до локального запуску:

• Як IDE працюють із кодом: індекс, режими підказки, чату й агента.
• Програма і модель: що в агенті задано кодом, а що вагами.
• Токеноміка програмування з моделлю: скільки коштує доведений цикл, а не один запит.
• Cursor і альтернативи: який клас інструмента брати під задачу.
• Виробничий RAG: коли векторний пошук допомагає і коли бреше.
• Атакувальні перевірки LLM-застосунків: як перевіряти обв'язку, а не лише відповідь моделі.
• Офлайн-дорожня карта: що піднімати, якщо зовнішнього API немає.

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

Висновок

Кодовий агент схожий на диспетчерську, а не на оракула в рядку редактора. Наряд пише модель. Файли, команди і відкат робить програма. Якість зміни залежить від того, що потрапило в запит, які інструменти дозволені і яка перевірка має право сказати «ще ні».

Практичний наступний крок короткий. Візьміть невеликий репозиторій, запустіть OpenCode у режимі Plan і попросіть лише знайти причину однієї відомої помилки, без правок. Подивіться, які виклики пішли в журнал. Потім перемкніться на Build і порівняйте, що змінилося в дозволах, а не в красномовстві відповіді. Після цього навчальний цикл із читанням файла й одним тестом уже є з чим звіряти.