Посібник із шаблонів

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

Як розпочати

Спочатку скопіюйте ці чотири файли до кореня вашого проекту:

1. AGENTS.md або CLAUDE.md
2. init.sh
3. claude-progress.md
4. feature_list.json

Решту файлів додавайте в міру розвитку проекту.

---

AGENTS.md

Кореневий файл інструкцій. Це перше, що агент читає на початку сесії. Він визначає операційні правила: що робити перед написанням коду, як працювати і як завершувати роботу.

Як використовувати:

• Скопіюйте до кореневої директорії вашого проекту
• Замініть кроки робочого процесу запуску на реальні шляхи та команди вашого проекту
• Скоригуйте правила роботи відповідно до угод вашої команди
• Залиште розділ визначення завершеності — це найважливіша частина

Що він дає агенту:

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

Використовуйте AGENTS.md для Codex або інших агентів. Використовуйте CLAUDE.md, якщо ви працюєте з Claude Code — структура однакова, просто відформатована під стиль інструкцій Claude.

init.sh

Скрипт запуску. Виконує встановлення залежностей, верифікацію і виводить команду запуску — все за один раз.

Як використовувати:

• Скопіюйте до кореня вашого проекту
• Відредагуйте ці три змінні на початку файлу:
  • INSTALL_CMD — команда встановлення залежностей (наприклад, npm install, pip install -r requirements.txt)
  • VERIFY_CMD — базова команда верифікації (наприклад, npm test, pytest)
  • START_CMD — команда запуску dev-сервера (наприклад, npm run dev)
• Зробіть файл виконуваним: chmod +x init.sh

Що він робить:

1. Виводить поточну директорію (щоб підтвердити, що запущений у правильному місці)
2. Встановлює залежності
3. Запускає команду верифікації
4. Виводить команду запуску (або запускає її, якщо встановлено RUN_START_COMMAND=1)

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

claude-progress.md

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

Як використовувати:

• Скопіюйте до кореня вашого проекту
• Заповніть розділ «Поточний верифікований стан» інформацією про ваш проект
• Після кожної сесії оновлюйте запис сесії

Що означає кожне поле:

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

feature_list.json

Трекер функцій. Машинозчитуваний список кожної функції, яку має реалізувати агент, разом із її статусом, кроками верифікації та доказами.

Як використовувати:

• Скопіюйте до кореня вашого проекту
• Замініть приклади функцій своїми власними
• Кожна функція потребує:
  • id — короткий унікальний ідентифікатор
  • priority — ціле число, менше = вищий пріоритет
  • area — яка частина застосунку (наприклад, "chat", "import", "search")
  • title — короткий опис
  • user_visible_behavior — що користувач має побачити, коли функція працює
  • status — одне з: not_started, in_progress, blocked, passing
  • verification — покрокові інструкції для підтвердження роботи функції
  • evidence — зафіксовані докази того, що верифікація пройшла (заповнює агент)
  • notes — будь-який додатковий контекст

Правила статусів:

• not_started — до неї ще не торкалися
• in_progress — єдина функція, над якою зараз ведеться робота (лише одна за раз)
• blocked — неможливо продовжити через задокументовану проблему
• passing — верифікація пройшла і докази зафіксовані

Агент повинен мати лише одну функцію зі статусом in_progress у будь-який момент часу.

session-handoff.md

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

Як використовувати:

• Скопіюйте до кореня вашого проекту
• Заповніть наприкінці кожної сесії (або попросіть агента заповнити)

Що охоплює кожен розділ:

• Верифіковано зараз — що підтверджено як таке, що працює, і яка верифікація запускалася
• Змінено в цій сесії — який код або інфраструктура змінилися
• Зламане або не верифіковане — відомі проблеми та ризиковані ділянки
• Найкращий наступний крок — що має зробити наступна сесія і що не можна чіпати
• Команди — команди запуску, верифікації та відлагодження для швидкої довідки

Цей файл необов'язковий для невеликих сесій. Він стає важливим, коли сесії тривалі або коли в проекті є кілька активних напрямків.

clean-state-checklist.md

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

Як використовувати:

• Скопіюйте до кореня вашого проекту
• Пройдіться по ньому перед закриттям сесії
• Агент також має перевіряти ці пункти як частину свого процесу завершення сесії

Що перевіряється:

• Стандартний запуск досі працює
• Стандартна верифікація досі виконується
• Журнал прогресу оновлено
• Список функцій відображає реальний стан (жодних хибних записів passing)
• Жодна незавершена робота не залишена незафіксованою
• Наступна сесія може продовжити роботу без ручних виправлень

evaluator-rubric.md

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

Як використовувати:

• Скопіюйте до кореня вашого проекту
• Після сесії (або набору сесій) оцініть роботу агента за шістьма вимірами
• Кожен вимір оцінюється від 0 до 2

Шість вимірів:

1. Коректність — чи відповідає реалізація цільовій поведінці?
2. Верифікація — чи були дійсно виконані необхідні перевірки з доказами?
3. Дисципліна обсягу — чи залишався агент у межах обраної функції?
4. Надійність — чи витримує результат перезапуск або повторний запуск?
5. Супроводжуваність — чи є код і документація достатньо зрозумілими для наступної сесії?
6. Готовність до передачі — чи може нова сесія продовжити роботу, спираючись лише на артефакти репозиторію?

Варіанти висновку:

• Прийняти — відповідає вимогам
• Переробити — потрібні виправлення перед прийняттям
• Заблокувати — фундаментальні проблеми, які потрібно вирішити спочатку

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

1. Запустіть оцінювач на завершеному спринті.
2. Порівняйте його оцінки з вашою власною людською думкою.
3. Де вони розходяться, зробіть рубрику конкретнішою щодо критеріїв прийнятності.
4. Перезапустіть і перевірте узгодженість.
5. Повторюйте, доки оцінювач стабільно не збігатиметься з людським переглядом.

Плануйте 3–5 раундів налаштування. Фіксуйте кожну зміну, щоб відстежувати, що покращило узгодженість.

quality-document.md

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

Як використовувати:

• Скопіюйте до кореня вашого проекту
• Перед початком сесії: прочитайте, щоб зрозуміти найслабші місця кодової бази
• Після сесії: оновіть оцінки на основі змін
• З часом: порівнюйте знімки, щоб побачити, які зміни harness дійсно покращили здоров'я кодової бази

Що оцінюється:

• Продуктові домени (наприклад, імпорт документів, потік Q&A, індексація): кожен домен отримує оцінку (A–D) за верифікаційним статусом, зрозумілістю для агентів, стабільністю тестів і ключовими прогалинами
• Архітектурні шари (наприклад, головний процес, preload, renderer, сервіси): кожен шар отримує оцінку за дотриманням меж і зрозумілістю для агентів

Чому це важливо:

Рубрика оцінювача оцінює окремі виводи агента. Документ якості оцінює саму кодову базу. Вони відповідають на різні питання:

• Рубрика оцінювача: «Чи добре агент попрацював у цій сесії?»
• Документ якості: «Чи стає проект міцнішим або слабшим з часом?»

Коли оновлювати:

• Після кожної значущої сесії
• Перед порівняльними тестуваннями
• Після проходів з очищення або спрощення
• При підключенні нового агента або моделі до проекту

Зв'язок зі спрощенням harness:

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

1. Зробіть знімок документа якості.
2. Видаліть один компонент harness.
3. Запустіть еталонний набір завдань.
4. Зробіть ще один знімок.
5. Порівняйте — якщо оцінки не впали, компонент був зайвим. Якщо впали — відновіть його.