Гайд по шаблонам

Эти шаблоны готовы к копированию в ваш проект. Каждый из них служит конкретной цели в воркфлоу агента. Редактируйте содержимое, чтобы оно соответствовало командам, путям, именам фич и шагам верификации вашего проекта.

Как начать

Сначала скопируйте эти четыре файла в корень вашего проекта:

1. AGENTS.md или CLAUDE.md
2. init.sh
3. claude-progress.md
4. feature_list.json

Добавляйте остальные файлы по мере роста проекта.

---

AGENTS.md

Корневой файл инструкций. Это первое, что читает агент в начале сессии. Он задаёт операционные правила: что делать перед написанием кода, как работать и как заканчивать.

Как использовать:

• Скопируйте в корневую директорию проекта
• Замените шаги стартового воркфлоу на реальные пути и команды вашего проекта
• Настройте рабочие правила под конвенции вашей команды
• Сохраните секцию definition of done — это самая важная часть

Что он делает для агента:

• Заставляет читать прогресс и состояние фич перед началом работы
• Требует работать над одной фичей за раз
• Требует доказательства, прежде чем что-либо помечать как done
• Определяет, как выглядит чистое окончание сессии

Используйте 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

Лог прогресса. Каждая сессия пишет в этот файл, и каждая новая сессия читает его первым делом.

Как использовать:

• Скопируйте в корень проекта
• Заполните секцию «Current Verified State» информацией о вашем проекте
• После каждой сессии обновляйте запись о сессии

Что значит каждое поле:

• Current Verified State — единственный источник истины о том, в каком состоянии проект
  • Repository root directory — где живёт проект
  • Standard startup path — команда для запуска проекта
  • Standard verification path — команда для запуска тестов
  • Highest priority unfinished feature — над чем должна работать следующая сессия
  • Current blocker — всё, что застопорилось
• Session Record — одна запись на сессию
  • Goal — что вы планировали сделать
  • Completed — что реально было сделано
  • Verification run — какие тесты были запущены
  • Evidence recorded — какие доказательства были зафиксированы
  • Commits — что было закоммичено
  • Known risks — что может быть сломано
  • Next best action — с чего должна начать следующая сессия

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

Компактная заметка-передача между сессиями. Используйте её, когда сессия заканчивается, и вы хотите, чтобы следующая быстро подхватила работу.

Как использовать:

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

Что покрывает каждая секция:

• Currently verified — что подтверждённо работает и какая верификация была запущена
• Changes this session — что изменилось в коде или инфраструктуре
• Still broken or unverified — известные проблемы и рискованные участки
• Next best action — что должна сделать следующая сессия и чего не трогать
• Commands — команды старта, верификации и отладки для быстрого доступа

Этот файл опционален для коротких сессий. Он становится важным, когда сессии длинные или когда у проекта несколько активных областей.

clean-state-checklist.md

Чек-лист, который нужно пройти перед окончанием каждой сессии. Гарантирует, что репозиторий в хорошем состоянии для чистого старта следующей сессии.

Как использовать:

• Скопируйте в корень проекта
• Пройдитесь по нему перед тем, как закрыть сессию
• Агент тоже должен проверять эти пункты как часть своей end-of-session рутины

Что он проверяет:

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

evaluator-rubric.md

Оценочный лист для ревью качества вывода агента. Используйте после сессии или на майлстоунах проекта, чтобы оценить, дотягивает ли работа до планки.

Как использовать:

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

Шесть измерений:

1. Correctness — соответствует ли реализация целевому поведению?
2. Verification — реально ли были запущены требуемые проверки, с доказательствами?
3. Scope discipline — оставался ли агент в рамках выбранной фичи?
4. Reliability — переживает ли результат перезапуск или повторный прогон?
5. Maintainability — достаточно ли понятны код и документация для следующей сессии?
6. Handoff readiness — может ли новая сессия продолжить, опираясь только на артефакты репозитория?

Варианты заключения:

• Accept — соответствует планке
• Revise — нужны фиксы перед принятием
• Block — фундаментальные проблемы, которые надо решать в первую очередь

Важно: evaluator нужно калибровать. «Из коробки» агенты — плохие судьи самих себя: они выявляют проблемы, а потом уговаривают себя одобрить. Вам придётся итерировать:

1. Запустите evaluator на завершённом спринте.
2. Сравните его оценки с собственным человеческим суждением.
3. Где они расходятся — сделайте рубрику конкретнее по критериям pass/fail.
4. Перезапустите и проверьте сходимость.
5. Повторяйте, пока evaluator не начнёт стабильно совпадать с человеческим ревью.

Закладывайте 3–5 раундов калибровки. Записывайте каждое изменение, чтобы отслеживать, что улучшило сходимость.

quality-document.md

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

Как использовать:

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

Что он оценивает:

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

Почему это важно:

Рубрика evaluator оценивает отдельные выводы агента. Quality-документ оценивает саму кодовую базу. Они отвечают на разные вопросы:

• Рубрика evaluator: «Хорошо ли агент сработал в этой сессии?»
• Quality-документ: «Проект становится сильнее или слабее со временем?»

Когда обновлять:

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

Связь с упрощением harness:

Quality-документ также поддерживает упрощение harness. Каждый компонент harness кодирует предположение о том, чего модель не умеет. По мере улучшения моделей эти предположения устаревают. Чтобы проверить, нужен ли компонент:

1. Сделайте снимок quality-документа.
2. Удалите один компонент harness.
3. Прогоните набор бенчмарк-задач.
4. Сделайте ещё один снимок.
5. Сравните — если оценки не упали, компонент был излишним. Если упали — верните его обратно.