Руководство по AGENTS.md

your-project/
  AGENTS.md          <- конфигурация уровня репозитория
  src/
  tests/
  package.json

# AGENTS.md

- Весь код писать на TypeScript в строгом режиме
- Форматирование через Prettier, статический анализ через ESLint
- Тесты на Vitest, размещать в каталогах `__tests__/`
- Перед завершением задачи выполнять `npm run lint && npm test`
- Не изменять файлы в каталоге `vendor/`
- Ответы API должны следовать стандартному формату-конверту: `{ code, data, message }`

# AGENTS.md

## Стандарты кода

- Использовать строгий режим TypeScript
- Переменные — camelCase, типы — PascalCase
- Не более 50 строк на функцию

## Требования к тестам

- Целевое покрытие модульными тестами: 80%
- Файлы тестов повторяют имя исходника с суффиксом `.test.ts`
- Внешние зависимости мокать; никаких реальных сетевых запросов в тестах

## Запрещено

- Использовать тип `any`
- Напрямую работать с DOM (используйте управление состоянием React)
- Использовать `await` внутри циклов (используйте `Promise.all`)

# Глобальный AGENTS.md

## Общие стандарты

- Комментарии в коде писать по-английски
- Сообщения коммитов по схеме Conventional Commits
- Никогда не зашивать пароли, ключи и токены в исходный код
- Перед генерацией нового кода прочитать существующий связанный код, чтобы сохранить единообразие
- Если влияние изменения непонятно — добавить поясняющий комментарий, а не строить догадки

## Предпочтения по выводу

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

# AGENTS.md

## О проекте
Фулстек-проект интернет-магазина на React + Node.js, написанный на TypeScript.

## Технологический стек

- Фронтенд: React 19 + TailwindCSS + Zustand
- Бэкенд: Node.js + Fastify + Prisma
- База данных: PostgreSQL 16
- Тесты: Vitest + Playwright

## Стандарты кода

- Файлы компонентов — PascalCase: `UserProfile.tsx`
- Вспомогательные функции — camelCase: `formatDate.ts`
- Маршруты API — kebab-case: `/api/user-orders`
- Поля базы данных — snake_case: `created_at`

## Структура проекта

- `src/components/` - компоненты React
- `src/pages/` - компоненты страниц
- `src/api/` - маршруты бэкенд-API
- `src/lib/` - общая библиотека утилит
- `prisma/` - схема базы и миграции

## Команды

- `npm run dev` - запустить dev-сервер
- `npm run build` - production-сборка
- `npm test` - запустить все тесты
- `npm run lint` - статический анализ
- `npx prisma migrate dev` - выполнить миграции базы

your-project/
  AGENTS.md                  <- правила уровня проекта
  src/
    components/
      AGENTS.md              <- правила каталога компонентов
    api/
      AGENTS.md              <- правила каталога API

# Стандарты компонентов

- Все компоненты — функциональные (классовые запрещены)
- У Props должно быть определение interface на TypeScript
- У каждого компонента должен быть displayName
- Стилизация через TailwindCSS; инлайновые стили запрещены
- Сложные компоненты разбивать на подкомпоненты; файл не длиннее 200 строк
- Переиспользуемые компоненты класть в подкаталог `ui/`

# Стандарты API

- Все эндпоинты обязаны валидировать параметры запроса (схемы Zod)
- Единый формат ошибки: `{ code: number, message: string, details?: any }`
- Операции с базой выполнять внутри транзакций
- Чувствительные операции записывать в журнал аудита
- Для пагинации использовать курсорный подход

Глобальный (~/.codex/AGENTS.md)
  | переопределяется уровнем репозитория
Корень репозитория (project/AGENTS.md)
  | переопределяется подкаталогом
Подкаталог (project/src/api/AGENTS.md) <- высший приоритет

# AGENTS.md

## О проекте
Фронтенд-проект на React 19 + TypeScript + TailwindCSS.

## Стандарты кода

- Использовать функциональные компоненты и Hooks; классовые запрещены
- Управление состоянием — Zustand; Redux не вводить
- Стилизация через TailwindCSS; CSS-файлы не создавать
- Для модулей из src использовать псевдоним пути `@/`
- Props компонента описывать интерфейсом с именем `{ComponentName}Props`

## Именование файлов

- Компоненты: PascalCase (`UserAvatar.tsx`)
- Хуки: camelCase с префиксом use (`useAuth.ts`)
- Утилиты: camelCase (`formatDate.ts`)
- Константы: camelCase (`apiEndpoints.ts`)

## Правила для компонентов

- Экспортировать и тип Props, и сам компонент
- Чисто презентационные компоненты оборачивать в `React.memo`
- Обработчики событий называть `handle{EventName}`
- Не создавать новые объекты и функции внутри render

## Тесты

- Стек: Vitest + React Testing Library
- Файлы тестов класть в каталоги `__tests__/`
- Тестировать поведение пользователя, а не детали реализации
- Команда запуска: `npm test`

## Управление зависимостями

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

# AGENTS.md

## О проекте
Бэкенд-сервис на Python 3.12 + FastAPI + SQLAlchemy.

## Стандарты кода

- Аннотации типов: у всех параметров и возвращаемых значений
- Асинхронность в первую очередь: все IO-операции через async/await
- Docstring: у всех публичных функций в стиле Google
- Порядок импортов: стандартная библиотека -> сторонние -> локальные модули (управляется isort)

## Структура проекта

- `app/api/` - маршруты API (router на каждую функциональность)
- `app/models/` - модели данных SQLAlchemy
- `app/schemas/` - модели запросов и ответов Pydantic
- `app/services/` - слой бизнес-логики
- `app/core/` - конфигурация, безопасность, внедрение зависимостей
- `tests/` - тесты, повторяющие структуру каталога app
- `alembic/` - миграции базы данных

## Соглашения по коду

- Именование функций маршрутов: `get_users`, `create_order` (глагол_существительное)
- Методы сервисного слоя соответствуют функциям маршрутов
- Поля моделей данных — snake_case
- Все операции с базой идут через сервисный слой; маршруты не трогают ORM напрямую
- Чувствительные данные (пароли, токены) не должны попадать в логи и ответы

## Обработка ошибок

- Бизнес-исключения — собственные классы Exception
- Единый обработчик исключений возвращает стандартный формат: `{"code": int, "message": str}`
- Операции с базой оборачивать в try/except и ловить IntegrityError и подобные
- Никогда не использовать голый except

## Тесты

- Стек: pytest + pytest-asyncio + httpx
- Тестовую базу и клиент вести через fixtures
- Команда запуска: `pytest -v --cov=app`
- Минимальное целевое покрытие: 80%

## Управление окружением

- Конфигурация в .env, загружается через pydantic-settings
- Различия между окружениями решаются переопределением переменных окружения
- Не зашивать строки подключения к базе и секреты в код

# AGENTS.md

## О проекте
Фулстек веб-приложение: фронтенд на Next.js 15 + API Routes + PostgreSQL.
Структура monorepo под управлением Turborepo.

## Структура каталогов

- `apps/web/` - фронтенд на Next.js
- `apps/api/` - отдельный сервис API (Node.js + Fastify)
- `packages/ui/` - общая библиотека UI-компонентов
- `packages/types/` - общие типы TypeScript
- `packages/utils/` - общие вспомогательные функции
- `packages/db/` - схема базы данных (Drizzle ORM)

## Общие стандарты

- Язык: TypeScript в строгом режиме
- Форматирование: Prettier (настроен в корне)
- Lint: ESLint (настроен в корне)
- Перед коммитом выполнять: `turbo lint test`

## Стандарты фронтенда (apps/web/)

- Использовать App Router, а не Pages Router
- Server Components в первую очередь; Client Components только при необходимости
- Получение данных через Server Actions или Route Handlers
- Стилизация через TailwindCSS
- Изображения через компонент next/image

## Стандарты API (apps/api/)

- RESTful-дизайн, URL в kebab-case
- Валидация запросов через Zod
- Формат ответа: `{ success: boolean, data?: T, error?: string }`
- Аутентификация по JWT, проверяется в middleware
- Правила ограничения частоты — в декораторах маршрутов

## Стандарты базы данных (packages/db/)

- Использовать Drizzle ORM; схема в каталоге `schema/`
- Команда миграции: `pnpm db:migrate`
- Именование: имена таблиц во множественном числе (`users`), поля snake_case
- У всех таблиц должны быть `created_at` и `updated_at`
- Мягкое удаление через поле `deleted_at`

## Стандарты общих пакетов

- Пакеты ссылаются друг на друга через workspace
- Общие определения типов — в `packages/types/`
- Пакеты не должны импортировать из apps

your-project/
  AGENTS.md          <- читает Codex
  CLAUDE.md          <- читает Claude Code
  src/
  ...

# AGENTS.md

> В этом проекте используются и Codex, и Claude Code. Основные стандарты ниже.
> Пользователям Claude Code — см. CLAUDE.md.

## Основные стандарты
(общее содержимое)

git add AGENTS.md
git commit -m "feat: add AGENTS.md for Codex configuration"

<!-- Описание PR -->
## Суть изменений
Обновления AGENTS.md:

- Добавлен стандарт пагинации API (курсорный)
- Явно запрещены прямые вызовы fetch в компонентах
- Добавлены требования к формату логов

## Эффективные инструкции (Codex надёжно им следует)

- Явное требование к формату: имена файлов компонентов в PascalCase
- Явный запрет: не использовать тип any
- Команда запуска: после завершения задачи выполнить npm test
- Правило размещения файлов: файлы тестов класть в каталоги __tests__
- Ограничение зависимостей: не добавлять новые npm-пакеты, использовать существующие

## Малоэффективные инструкции (лучше избегать)

- Слишком расплывчато: пиши хороший код
- Субъективно: следуй лучшим практикам
- Вне зоны действия: подумай об удобстве для пользователя (AI не запускает UI)
- Противоречиво: приоритет производительности + приоритет читаемости (нужен явный приоритет)

## Правила по типам файлов

### Файлы *.test.ts

- Не больше 10 тестов в одном блоке describe
- Тестовые данные создавать фабричными функциями, не зашивать
- У асинхронных тестов должен быть таймаут

### Файлы *.api.ts

- Обязательно валидировать параметры запроса
- Обязательно предусмотреть обработку ошибок
- У возвращаемых значений должны быть аннотации типов

### Файлы migrations/*.sql

- Не редактировать напрямую; генерировать через инструмент миграций ORM

cp CLAUDE.md AGENTS.md

## Стиль кода

В этом проекте мы следуем руководству по стилю TypeScript от Google. Все имена
переменных пишутся в camelCase, имена классов — в PascalCase. Обратите внимание,
что значения перечислений пишутся в SCREAMING_SNAKE_CASE. Импорты должны идти
в таком порядке: сначала встроенные модули Node.js, затем сторонние пакеты и
в конце локальные модули. Группы разделяются пустой строкой.

## Стиль кода

- Следовать руководству по стилю TypeScript от Google
- Переменные: camelCase
- Классы: PascalCase
- Значения перечислений: SCREAMING_SNAKE_CASE
- Порядок импортов: встроенные модули -> сторонние пакеты -> локальные модули (между группами пустая строка)

## Настройки, специфичные для Codex

- После всех изменений файлов выполнить `npm run lint && npm test` для проверки
- Если тесты падают — исправить и перезапустить автоматически
- Не изменять файлы .env и .env.local

# Предполагаем, что AGENTS.md требует TypeScript
codex "Создай функцию hello world"

# Если AGENTS.md действует, Codex создаст файл .ts, а не .js

# CLAUDE.md

@AGENTS.md

## Дополнения только для Claude Code

- Переключаться между Sonnet 4.6 / Opus 4.8 через `/model` по типу задачи
- Перед крупными изменениями запускать `/plan`
- Между несвязанными задачами использовать `/clear`, в длинных сессиях — `/compact` на логических рубежах