Розбір дизайну harness у Pi

Pi (npm-пакет @earendil-works/pi-coding-agent) називає себе "minimal agent harness" — мінімалістичним agent harness. Це формулювання варто прочитати уважно: продукт не називає себе «найсильнішим coding agent» чи «найзручнішим інструментом AI-програмування», а чітко закріплює своє позиціонування за словом harness.

У цій статті ми розберемо Pi за допомогою фреймворку п’яти підсистем курсу — інструкцій, інструментів, середовища, стану й зворотного зв’язку — та з’ясуємо, чим його проєктна філософія принципово відрізняється від Claude Code і Codex. Одразу наведемо відповідь: філософія Pi — «мінімізація ядра + програмованість розширень»; інженерія контексту виходить за межі системного промпту, а змінювати harness може користувач (і навіть сам Pi), замість того щоб Pi вирішував за вас, яким має бути harness.

Позиціонування одним реченням

Pi — це мінімалістичне ядро: офіційне позиціонування навмисно робить ядро малим і повертає право вибору вам. На головній сторінці pi.dev дослівно сказано: "Ask Pi to build what you want, or install a package that does it your way". Pi поділяє harness на чотири рівні налаштування:

• Розширення (Extensions): TypeScript hooks, прив’язані до подій життєвого циклу Pi, — програмована поверхня рівня runtime.
• Навички (Skills): пакети можливостей, що завантажуються за потреби, містять інструкції та інструменти й використовують поступове розкриття (progressive disclosure).
• Шаблони промптів (Prompt templates): повторно використовувані Markdown-промпти, які розгортаються командою /name.
• Теми (Themes): зовнішній вигляд TUI.

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

Основний цикл

Як і будь-який coding agent, Pi за своєю суттю виконує цикл while «міркування → виконання інструмента → спостереження → нове міркування». Цікавий не сам цикл, а те, як Pi працює з його зовнішнім контуром: управління контекстом розширено від «compaction» усередині циклу до «контролю» поза ним.

Runtime Pi надає зовнішній програмований інтерфейс: у розділі Programmatic Usage вихідного README, окрім інтерактивного TUI, підтримуються скриптові режими друку/JSON, протокол RPC та вбудовування через SDK. Завдяки цьому той самий harness може керуватися як людиною крок за кроком, так і автоматично через CI/CD або іншу програму. Це відповідає передумові переходу «від ручного керування до автоматичного циклу» з тринадцятої лекції курсу: якщо harness може працювати лише через взаємодію з людиною, він ніколи не стане частиною автоматичного циклу.

Підсистема інструкцій: AGENTS.md і SYSTEM.md

Pi стримано працює з «інструкціями», але має чітку ієрархію:

• AGENTS.md: у розділі Project Context Files вихідного README чітко вказано порядок завантаження: глобальний ~/.pi/agent/AGENTS.md → послідовний обхід батьківських директорій угору → ./AGENTS.md у поточній директорії (також підтримується CLAUDE.md). Це пряме втілення принципу «репозиторій — джерело правди»: інструкції є файлами, а не нагадуваннями в чаті.
• SYSTEM.md: в офіційній документації pi.dev сказано, що для кожного проєкту можна замінити (replace) або доповнити (append) стандартний системний промпт. Це єдиний офіційний спосіб, у який Pi дозволяє змінювати «системний промпт», і водночас його рівень «самоопису середовища».

Pi офіційно наголошує, що його системний промпт мінімалістичний. За цим стоїть чіткий компроміс: ядро не наповнюється довгими правилами «якщо… то…», натомість надає точки розширення, щоб правила з’являлися у формі навичок і розширень лише тоді, коли вони потрібні. Це прямо перегукується з четвертою лекцією курсу «Чому один гігантський файл інструкцій не працює»: завдяки «мінімалістичному ядру + поділу на файли + завантаженню за потреби» Pi природно уникає проблеми гігантських інструкцій.

Стан і контекст: найдетальніша частина Pi

Інженерія контексту Pi заслуговує на особливу увагу, адже такі поняття курсу, як «безперервність контексту» та «запобігання деградації контексту», тут втілені в конкретних механізмах:

1. Програмованість compaction. Коли система наближається до межі контексту, старі повідомлення автоматично підсумовуються. В офіційній документації pi.dev сказано, що сама стратегія compaction налаштовується: через розширення можна реалізувати тематичну compaction, підсумовування з урахуванням коду або навіть використати для підсумовування іншу модель. Вихідний README також розкриває деталі стандартного механізму: автоматична compaction запускається у двох випадках — під час відновлення після переповнення контексту або після перевищення порога збереження; точка поділу залишає близько 20 тисяч останніх token, а попередні повідомлення згортаються в "context handoff" і послідовно стискаються ланцюжком. Отже, Pi розглядає «спосіб compaction» не як незмінну константу, а як частину harness.

2. Динамічний контекст (Dynamic context). В офіційній документації pi.dev сказано, що перед кожним кроком міркування розширення можуть додавати повідомлення, фільтрувати історію повідомлень, реалізовувати RAG і створювати довготривалу пам’ять. Це ще один крок після «compaction, коли контекст заповнився»: ви вирішуєте, що потрапить у контекстне вікно, ще до входу інформації у вікно. У термінах курсу — «зробити процес роботи agent спостережуваним і придатним до налагодження» та «зберігати безперервність контексту» — Pi переносить обидві функції на поверхню розширень.

3. Дерево session (Session tree). На головній сторінці pi.dev прямо сказано: "sessions are stored as trees"; команда /tree дає змогу повернутися до будь-якого історичного вузла й продовжити роботу, а всі гілки зберігаються в одному файлі. Це розв’язує проблему «розриву контексту між session», на якій неодноразово наголошує курс: не через жорстке склеювання підсумками, а через структуроване відтворення історії. Гілку можна експортувати в HTML або завантажити як gist для поширення, що водночас забезпечує спостережуваність.

Підсистема інструментів: навички й розширення

«Інструменти» Pi мають два рівні:

• Навички (Skills): розділ Skills вихідного README дає чітке визначення — "self-contained capability packages that the agent loads on-demand", тобто самодостатні пакети можливостей, які завантажуються за потреби, містять інструкції та інструменти й відповідають стандарту Agent Skills. Поступове розкриття додає деталі навички до контексту лише після спрацювання, не перевантажуючи кеш промпту (prompt cache). Це дизайн harness з погляду вартості: кожен додатковий token у контексті оплачується під час кожного міркування; завантаження навичок за потреби є ще одним вираженням принципу «дайте карту, а не підручник».
• Розширення (Extensions): TypeScript hooks, прив’язані до вбудованих подій життєвого циклу. У розділі Hooks вихідного README наведено офіційні приклади застосування: перехоплення небезпечних команд (permission gate), створення checkpoint стану коду під час перемикання завдань, захист шляхів (наприклад, заборона запису в .env), зміна виводу інструмента перед передаванням моделі, а також додавання повідомлень із зовнішніх джерел (спостерігач за файлами/Webhook/CI), щоб активувати agent. API цих hooks також експортується з @mariozechner/pi-coding-agent/hooks. Своєю чергою, спільнотний harness pi-agent-harness додатково обгортає поверхню hooks у готові розширення skill-router, session-summary, extract-patterns, telemetry тощо.

Розширення — найважливіше проєктне рішення Pi: продукт не просто «дає користувачеві кілька перемикачів», а відкриває всю внутрішню поверхню подій runtime. Потрібна пам’ять? Додайте її через agent/pre-step. Потрібно записувати поведінку? Підпишіться на події session. Потрібно змінити запит до моделі? Підключіться до agent/request. Ви можете дозволити Pi змінювати власний harness — це ближче до визначення «програмованого harness», ніж будь-які «параметри конфігурації».

Зворотний зв’язок і верифікація: навіть «навчання» як harness

Pi не має вбудованого обов’язкового шлюзу тестування — користувач має записати команди верифікації в AGENTS.md. Проте спільнотний harness pi-agent-harness структурує «цикл зворотного зв’язку» через розширення, а розділ Hooks офіційного README надає основу для подібних механізмів:

• session-summary (розширення pi-agent-harness): підтримує ковзні записи в PROGRESS.md — це підсистема стану з курсу, відстеження прогресу тривалих завдань.
• extract-patterns (розширення pi-agent-harness): збирає з session потенційні уроки й зберігає їх у LESSONS.md, перетворюючи домовленість «належно передавати роботу наприкінці кожної session» на механізм.
• telemetry (розширення pi-agent-harness): записує використання token, вартість тощо — спостережуваність.

Той самий спільнотний репозиторій розвиває цей патерн: VISION.md (мета), PROGRESS.md (прогрес), LESSONS.md (досвід), STANDARDS.md (стандарти) — усе це Markdown-файли, що зберігаються між session. Це той самий підхід «репозиторій — джерело правди + файл прогресу + механізм передавання роботи», рекомендований курсом, але завдяки механізму розширень Pi він доступний одразу після встановлення.

Відповідність фреймворку курсу

Суб’єктивна оцінка Pi за п’ятьма підсистемами курсу для порівняння:

Підсистема	Реалізація Pi	Оцінка
Інструкції	Ієрархічне завантаження AGENTS.md + SYSTEM.md	Чітка ієрархія, але самі правила має писати користувач
Інструменти	Навички за потреби + hooks для всього життєвого циклу розширень	Надзвичайно сильна реалізація, що перетворює систему інструментів на програмовану поверхню
Середовище	Самоопис середовища через SYSTEM.md; runtime-середовище користувач оголошує в AGENTS.md	Механізм відкритий, але відтворюваність залежить від опису користувача
Стан	Дерево сесій + налаштовуване стиснення + PROGRESS.md	Надзвичайно сильна реалізація; робота між сесіями та відновлюваність лежать у її основі
Зворотний зв’язок	Команди перевірки визначає користувач; session-summary / extract-patterns перетворено на механізми	Механізм надано, наповнення залежить від користувача

Компроміс Pi різко контрастує з Claude Code і Codex: Claude Code вбудовує «пам’ять, permissions, subagent» у ядро й надає їх одразу; Codex робить стандартними «правила репозиторію та ізоляцію середовища»; Pi нічого не вирішує замість вас, а перетворює право вибору на точки розширення. Ціна цього підходу — потреба самостійно писати розширення або встановлювати чужі пакети.

Проєктні рішення, які варто запозичити

1. Зробіть стратегію compaction підключуваною. У вашому harness спосіб compaction контексту має бути не жорстко заданим параметром, а замінним інтерфейсом стратегії.
2. Використовуйте дерево session замість жорсткого підсумовування. Відновлення між session не обов’язково має спиратися на «підсумок попереднього раунду»; структуроване відтворення історії часто є надійнішою підсистемою стану.
3. Дбайте про кеш промпту. Завантажуйте навички за потреби й не додавайте всі правила до системного промпту одразу — це і інженерія контексту, і інженерія вартості.
4. Дайте agent змінювати власний harness. Якщо поверхня розширень harness достатньо відкрита, саме «поліпшення поведінки agent» може частково автоматично виконувати agent.

Довідкові джерела (оригінальні тексти / вихідний код)

Кожне твердження можна простежити до наведеного нижче оригінального тексту або вихідного коду, щоб уникнути переказу з пам’яті:

• Офіційний сайт pi.dev: оригінальне позиціонування "Ask Pi to build what you want, or install a package that does it your way", чотири рівні налаштування, дерево сесій ("sessions are stored as trees", /tree, збереження в одному файлі, експорт у HTML / поширення через gist).
  https://pi.dev/
• Офіційна документація pi.dev · Sessions: підключуване стиснення (topic-based / code-aware / інша модель для підсумовування), механізми автоматичного стиснення й динамічного додавання контексту.
  https://pi.dev/docs/usage/sessions
• Офіційна документація pi.dev · Extensions: розширення можуть перед кожним циклом міркування додавати повідомлення, фільтрувати історію, виконувати RAG і створювати довготривалу пам’ять.
  https://pi.dev/docs/usage/extensions
• Офіційна документація pi.dev · Project Context: семантика replace / append у SYSTEM.md.
  https://pi.dev/docs/usage/project-context
• README вихідного коду Pi Coding Agent (badlogic/pi-mono): трирівневий порядок завантаження AGENTS.md (глобальний → батьківські каталоги → поточний каталог), умови запуску /compact та автоматичного стиснення й точка поділу на 20 тисяч token, завантаження Skills за потреби та стандарт Agent Skills, життєвий цикл Hooks і чотири офіційні приклади, Programmatic Usage (JSON / RPC / SDK).
  https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
• Спільнотний репозиторій pi-agent-harness: розширення skill-router / session-summary / extract-patterns / telemetry і файлова система VISION.md / PROGRESS.md / LESSONS.md / STANDARDS.md.
  https://github.com/LabidySabidy/pi-agent-harness

Пов’язані лекції: Лекція 02. Що таке harness насправді ｜ Лекція 05. Збереження контексту між сесіями ｜ Лекція 13. Інженерія циклів: від ручного керування до автоматизації