Amiga
Оглавление курса · урок 4 из 13

Модуль 1 · Идея и спецификация · урок 4 из 13

Правила проекта с первого дня

В новом проекте нет истории, и агент принимает решения по памяти, то есть по обучающим данным. Пока кода мало, этого не видно. Через двадцать сессий в проекте уже три способа обработки ошибок и два формата дат. Записать правила в первый день дешевле, чем разгребать всё через месяц.

Зачем до первой фичи

Codex воспроизводит шаблоны, которые уже есть в репозитории, и неудачные тоже. Первые срезы становятся образцом для всех следующих. Если в первом эндпоинте нет валидации, её не будет и в двадцатом: агент посмотрит на соседний код и сделает так же.

Основы AGENTS.md есть в уроке курса «Codex с нуля». Здесь поговорим о том, что в него писать для молодого продукта.

Заготовка и правка

Команда /init создаёт стартовый AGENTS.md по содержимому репозитория. В пустом проекте она найдёт немного, поэтому считайте результат черновиком и главное допишите сами. В разделе документации best practices перечислено, что туда класть: устройство репозитория, как запускать проект, команды сборки, тестов и линта, соглашения, запреты и что значит «готово».

markdown · AGENTS.md
# Переговорки

Внутренний сервис брони переговорных. Что строим и правила (R1…R5) —
docs/SPEC.md. Порядок работ — docs/PLAN.md. Решения — docs/decisions/.

## Структура
- apps/api — Fastify + Prisma. Маршруты в src/routes, логика в src/services.
- apps/web — React + Vite. Страницы в src/pages, общие компоненты в src/ui.
- packages/shared — Zod-схемы запросов и ответов. Единственный источник типов API.

## Команды
- npm run dev — API и web локально (нужен docker compose up -d)
- npm run check — lint + typecheck + unit/интеграционные тесты
- npm run test:e2e — Playwright, требует запущенного dev
- npm run db:migrate -- --name <имя> — новая миграция

## Готово, когда
- npm run check зелёный, для изменений интерфейса — ещё test:e2e.
- Новое поведение покрыто тестом, тест ссылается на правило (R3) или сценарий (S2).
- В docs/PLAN.md отмечен пункт; если менялись правила — обновлён docs/SPEC.md.

## Соглашения
- Время в базе — timestamptz, в API — ISO 8601 с зоной, в интерфейсе —
  Europe/Moscow. Даты считаем через date-fns, не вручную.
- Любой вход в API валидируется Zod-схемой из packages/shared.
- Ошибки API: { error: { code, message } }, коды — в shared/errors.ts.
- Без новых зависимостей без явной просьбы. Если очень нужна — спроси.

## Нельзя
- Править или удалять существующие тесты, чтобы они прошли. Сообщи о конфликте.
- Писать SQL строками с подстановкой значений. Только Prisma или $queryRaw с параметрами.
- Читать и создавать .env; секреты не печатать в логах и ответах.
- Менять применённые миграции — только новая миграция.

## Code Review Rules
- Каждый маршрут, меняющий данные, проверяет права (R4); без проверки — P1.
- Проверка пересечения броней только в базе (R3); проверка лишь в коде — гонка.

Файл ссылается на правила из спецификации. Пересказывать агенту бизнес-логику незачем, достаточно сказать, где она описана.

Держите файл коротким

AGENTS.md загружается в каждую сессию и занимает место в контексте. У Codex есть предел суммарного объёма инструкций, по умолчанию 32 KiB. Файлы сверх него просто не добавляются (подробнее в документации AGENTS.md). Но проблемы начинаются раньше: если важным объявлено всё, агент не отличит главное от второстепенного.

В best practices есть рабочее правило: добавлять строку в AGENTS.md, когда видите повторяющуюся ошибку, а не про запас. Если агент дважды ошибся одинаково, попросите его разобрать, почему:

text
Ты второй раз считаешь конец брони через getHours() вместо date-fns.
Разбери, почему так вышло, и предложи одну строку в AGENTS.md,
которая предотвратит это в будущих сессиях. Не меняй код.

Проверьте, что правила загружены

После правки AGENTS.md перезапустите сессию: файлы читаются при старте. Что агент видит, можно проверить так:

bash
codex --sandbox read-only --ask-for-approval never "Summarize the current instructions."

Если пересказ расходится с тем, что вы написали, ищите конфликт: другой AGENTS.md в подкаталоге или AGENTS.override.md.

От правила к проверке

Правило в AGENTS.md агент воспринимает как просьбу. Он может о ней забыть или решить, что здесь она неприменима. Поэтому всё, что проверяется механически, переносите в инструменты. Тогда нарушение поймает npm run check, а сообщение об ошибке подскажет, как исправить:

javascript · apps/api/eslint.config.js
import tseslint from "typescript-eslint";

export default tseslint.config(...tseslint.configs.recommended, {
  rules: {
    "no-restricted-syntax": [
      "error",
      {
        selector: "CallExpression[callee.property.name=/^(getHours|setHours)$/]",
        message: "Время брони считаем через date-fns в зоне Europe/Moscow, см. AGENTS.md → Соглашения.",
      },
    ],
    "no-restricted-imports": [
      "error",
      { patterns: [{ group: ["**/web/src/**"], message: "API не импортирует код интерфейса. Общее — в packages/shared." }] },
    ],
  },
});

В статье OpenAI о harness engineering описан тот же приём: сообщения линтера пишут как инструкцию по исправлению, и агент получает её прямо в контекст. Подробнее об этом в уроке об инвариантах.

Раздел для ревью

Раздел ## Code Review Rules читает ревью Codex в GitHub. Как с ним работает интеграция с GitLab (она пока в бете), смотрите в документации по ревью. Документация советует начинать с двух-трёх правил, описывать, что именно считать проблемой и какой путь безопасен, а форматирование оставить CI. При локальном /review этот раздел тоже пригодится: попросите ревьюера сверяться с ним.

Попробуйте сами

10–15 мин на рабочем месте
  1. Запустите /init в своём проекте и перепишите результат по образцу выше: структура, команды, «готово», соглашения, запреты. Уложитесь в 60 строк.
  2. Проверьте загрузку командой codex --sandbox read-only --ask-for-approval never "Summarize the current instructions.".
  3. Выберите одно правило из AGENTS.md, которое можно проверить машиной, и превратите его в правило линтера с понятным сообщением.

Коротко

  • Первые срезы становятся образцом: агент копирует то, что видит в репозитории.
  • AGENTS.md — короткая карта проекта: структура, команды, «готово», соглашения, запреты.
  • Ссылайтесь на спецификацию, а не пересказывайте её.
  • Новое правило появляется после повторяющейся ошибки и разбора с агентом.
  • Всё, что проверяется машиной, переносите в линтер и тесты, с подсказкой в сообщении.
Отметка хранится только в вашем браузере
Хотите связаться с владельцем
компании напрямую?
Дмитрий Тарасов
Дмитрий Тарасов
СЕО

НАПИСАТЬ

Написать в MAX