У каждой типовой задачи в проекте должен быть назначенный «эталонный» код, к которому отсылается агент.
Описание
Для любой типовой задачи в проекте есть «идеальный» эталонный пример (контроллер, форма, тест, миграция). При постановке задачи агенту разработчик прямо указывает на этот эталон.
Предусловия
- В кодовой базе явно идентифицирована эталонная реализация (или несколько по слоям)
- Эталон поддерживается актуальным
Постусловия / гарантия успеха
- Новый код повторяет структуру эталона
- Снижается риск архитектурного дрейфа
Основной сценарий
- Разработчик при постановке задачи говорит: «реализуй по аналогии с файлом/модулем X»
- Агент изучает указанный эталон
- Генерирует код в той же стилистике и архитектуре
- Разработчик проводит ревью и при необходимости уточняет
Расширения / альтернативные потоки
- 1a. Список эталонов вынесен в AGENTS.md (см. UC-003 · AGENTS.md) — агент сам подбирает релевантный
Исключения и риски
Бизнес-правила и ограничения
- У каждой типовой задачи проекта должен быть назначенный эталон
- Эталоны — это часть документации архитектуры
Примечания
Совмещается с типизацией (статические типы) — агент гораздо точнее работает с типизированным кодом (Go, TypeScript, Sorbet-typed Ruby и т. п.).
Частые вопросы
Чем эталон отличается от шаблона?+
Шаблон — структура без бизнес-логики. Эталон — реальный, рабочий код в проекте, со всеми компромиссами и контекстом. Эталон отвечает не только «как», но и «почему здесь так».
Что делать, если эталоны устарели?+
Обновлять эталон — отдельная регулярная задача (раз в спринт). Иначе агент будет копировать устаревшие паттерны. Лучше иметь 5 свежих эталонов, чем 20 устаревших.
Как ссылаться на эталон в AGENTS.md?+
Прямой путь к файлу + короткое описание, для чего эталон. Пример: «src/controllers/users.controller.ts — эталон REST-контроллера: валидация через zod, error handling через middleware, тесты в users.controller.spec.ts».
Эталоны заменяют типы?+
Нет, дополняют. Типы дают агенту строгий контекст на уровне сигнатур. Эталоны — контекст на уровне паттернов и идиом. Лучший результат — когда есть оба.