Claude Code / Codex
Промпты-инструкции и сборник шаблонов

Прочитай файл-инструкцию, который ты (этот агент) загружаешь (CLAUDE.md / AGENTS.md и т. д.),
укажи слабые места, которые ИИ-агенты склонны игнорировать, а затем перепиши его
в эффективную форму.

На что обратить внимание:
- Преврати расплывчатые формулировки в повелительные (всегда делай X / никогда не делай Y)
- Добавь определение готовности и шаги проверки (запуск lint / test)
- Сделай запреты конкретными вплоть до цели (имена директорий, имена команд)
- Если он слишком длинный, сократи его до сути, которую ты хочешь обеспечить

Сначала перечисли слабые места списком, затем выведи полную переписанную
версию и примени её к этому файлу-инструкции.

Определив фактические команды build / test / lint этого репозитория,
добавь раздел «Определение готовности» в файл-инструкцию, который ты загружаешь
(CLAUDE.md / AGENTS.md и т. д.).

Требования:
- Сделай его контрольным списком в форме «не сообщай «готово», пока не выполнено всё перечисленное»
- Явно укажи реальные команды lint и test
- Включи: не оставляй TODO или отладочные логи в изменённых файлах и перечитывай собственный diff

Не нарушай существующее содержимое; только добавь раздел.

Автоматически определи язык и фреймворк этого репозитория и добавь
соответствующие правила лучших практик в файл-инструкцию, который ты загружаешь
(CLAUDE.md / AGENTS.md и т. д.).

Примеры:
- Next.js: граница Server/Client (по умолчанию Server, держи use client минимальным)
- Laravel: валидация через Form Requests, соглашения по миграциям
- Python: аннотации типов, никогда не перезаписывай и не фабрикуй сырые данные

Добавь однострочную заметку об основании для определения (по каким файлам ты судил)
перед дополнением. Не дублируй то, что уже записано.

Добавь следующие «абсолютные правила» в файл-инструкцию, который ты загружаешь
(CLAUDE.md / AGENTS.md и т. д.), адаптировав их под устройство этого репозитория.

- Никогда не коммить секреты, .env или учётные данные
- Никогда не делай push / force-push, если не сказано
- Проверяй ввод на границе / никогда не ослабляй аутентификацию или авторизацию по своей инициативе
- Никогда не запускай разрушительные команды (DROP / TRUNCATE / migrate:fresh и т. д.) на продакшен-БД
- Каждый раз, меняя поведение, всегда добавляй или обновляй тесты

Если похожие правила уже существуют, не дублируй их; добавь только то, чего не хватает.

Преобразуй содержимое этого `CLAUDE.md` в формат `AGENTS.md` для
OpenAI Codex и запиши его.

- Сохрани смысл, но придай ему структуру, удобную для чтения Codex
  (заголовки, маркированные списки)
- Сохрани команды, абсолютные правила и определение готовности как есть
- Выведи это как `AGENTS.md` в корне

Преобразуй содержимое этого `CLAUDE.md` в формат Project Rules от Cursor
(файлы `.mdc` в каталоге `.cursor/rules/`).

- Раздели правила на осмысленные единицы
- Отдели правила, которые должны применяться всегда, от правил, которые применяются
  только к определённым типам файлов
- Задай подходящие условия применения (globs и т. д.) в начале каждого файла

Изучи структуру этого монорепо и создай файлы-инструкции, которые ты
(этот агент) загружаешь (Claude Code использует CLAUDE.md, Codex использует AGENTS.md и т. д.),
разделив их следующим образом.

- В корне: правила, общие для всего репозитория
  (соглашения по коммитам, защита секретов, общее определение готовности)
- В каталоге каждого пакета/приложения: только правила и команды, специфичные для этого стека

Избегай дублирования и добавь однострочную заметку в каждый пакет: «следуй
общим правилам в корне». В конце сообщи списком, что ты разместил в какой директории.

# Проект: <name>

## Что это
Однопараграфный обзор приложения. Что оно делает, кто им пользуется, и технологический
стек (язык, фреймворк, БД, среда выполнения).

## Команды
- Dev-сервер: `npm run dev`
- Сборка:     `npm run build`
- Тесты:      `npm test`
- Lint:       `npm run lint`

## Соглашения
- Язык - TypeScript (strict). Не используй `any`.
- Соответствуй стилю файла, который ты сейчас редактируешь. Перед завершением всегда проходи Lint.
- Держи изменения минимальными; не трогай несвязанные строки (никакого несвязанного переформатирования).

## Абсолютные правила (строго обязательно)
- Прежде чем сообщить «готово», всегда запускай тесты и Lint выше и добивайся их прохождения.
- Никогда, ни в коем случае не коммить секреты, .env или артефакты сборки.
- Предпочитай редактирование существующих файлов созданию новых.
- Когда требования расплывчаты, задай ровно один уточняющий вопрос перед большим изменением.

## Запретная зона (если не сказано иное)
- Конфигурация CI, версии зависимостей, настройка инфраструктуры.

# <name>

- Стек: <напр. Next.js + TypeScript + PostgreSQL>
- Всегда запускай перед завершением: `npm run lint` и `npm test` (оба должны пройти)
- Соответствуй существующему стилю. Не переформатируй несвязанные строки.
- Не коммить секреты или .env. Не делай push, пока не сказано.
- Когда расплывчато, не угадывай; задай ровно один вопрос.

# Next.js (App Router) + TypeScript

## Стек
Next.js (App Router), TypeScript strict, Tailwind CSS, <your-ORM>

## Команды
- Dev:    `npm run dev`
- Сборка: `npm run build`   # должна проходить без ошибок типов
- Lint:   `npm run lint`
- Тесты:  `npm test`

## Правила архитектуры
- По умолчанию Server Components. Добавляй "use client" только когда нужны
  состояние, эффекты или браузерные API. Держи Client Components маленькими и на листьях.
- Получай данные в Server Components или Route Handlers.
  Не получай начальные данные в useEffect.
- Размещай компоненты рядом с их сегментом маршрута. Общий UI идёт в `components/`.
- Всегда проверяй внешний ввод по схеме на границе (напр. Zod).

## Соглашения
- Никакого `any`. Давай публичным функциям явные типы возвращаемого значения.
- Используй существующие дизайн-токены / классы Tailwind. Не добавляй цвета по своей инициативе.
- Держи `page.tsx` тонким; выноси логику в функции и компоненты.

## Определение готовности
`npm run build`, `npm run lint` и `npm test` проходят с кодом выхода 0.
Никакого `any`, никаких неиспользуемых экспортов, никаких забытых console.log.

# React (Vite) + TypeScript

## Команды
- Dev:    `npm run dev`
- Сборка: `npm run build`
- Lint:   `npm run lint`
- Тесты:  `npm test` (Vitest + Testing Library)

## Правила
- Только функциональные компоненты и Hooks. Не используй классовые компоненты.
- Держи состояние минимальным, в порядке «локальное -> Context -> библиотека состояния».
  Не поднимай состояние в глобальное без необходимости.
- Заключай побочные эффекты в useEffect и правильно записывай массив зависимостей.
- Отделяй UI от логики. Группируй получение данных в выделенные хуки (useXxx).
- Доступность: давай интерактивным элементам подходящие роли и управление с клавиатуры.

## Соглашения
- Никакого `any`. Определяй props через типы.
- Соответствуй стилю существующих компонентов и стилей.

## Определение готовности
`npm run build`, `npm run lint` и `npm test` проходят с кодом выхода 0.

# Node.js API (Express / Hono) + TypeScript

## Команды
- Dev:    `npm run dev`
- Сборка: `npm run build`
- Тесты:  `npm test`
- Lint:   `npm run lint`

## Правила
- Проверяй по схеме весь ввод (body, query, params, headers) на границе.
- Не проглатывай ошибки. Возвращай их типизированными через центральный обработчик ошибок.
- Читай секреты из переменных окружения. Не хардкодь их в коде.
- Разделяй доступ к БД на слои (route -> service -> repository).
- Возвращай единообразную форму JSON (унифицируй формы успеха и неудачи).

## Абсолютные правила
- Не пропускай и не ослабляй логику аутентификации / авторизации по своей инициативе.
- Всегда проверяй авторизацию при добавлении публично доступного эндпоинта.
- Не логируй персональные данные, токены или пароли.

## Определение готовности
`npm test` (успешный путь + случаи ошибок) и `npm run lint` проходят.

# Laravel + PHP

## Команды
- Запуск:    `php artisan serve`
- Миграция:  `php artisan migrate`
- Тесты:     `php artisan test`
- Форматирование: `./vendor/bin/pint`   # запускать перед завершением

## Соглашения (следуй стилю Laravel)
- Используй связи Eloquent. Избегай сырого SQL без чёткой причины.
- Проверяй ввод в классах Form Request. Не делай это внутри контроллеров.
- Держи контроллеры тонкими. Выноси бизнес-логику в Services / Actions.
- Каждое изменение схемы получает новую миграцию. Не редактируй уже выполненные.
- Используй именованные маршруты и привязку моделей к маршрутам.

## Абсолютные правила
- Никогда, ни в коем случае не коммить `.env` или настоящие учётные данные.
- Не запускай разрушительные команды вроде `migrate:fresh` на продакшен-БД.
- Каждый раз, меняя поведение, всегда добавляй или обновляй тесты (`php artisan test`).

## Определение готовности
И `php artisan test`, и `./vendor/bin/pint --test` проходят.

# Python / анализ данных

## Окружение
- Используй venv проекта `.venv`. Не устанавливай глобально.
- Установка: `pip install -r requirements.txt`
- Запуск: `python -m src.main`
- Тесты: `pytest`
- Форматирование: `ruff check .` и `ruff format .`

## Соглашения
- Добавляй аннотации типов к каждой сигнатуре функции. Запускай `mypy src`, если настроено.
- Не размещай логику в ноутбуках. Переиспользуемый код идёт в `src/`.
- Фиксируй seed для всего, что использует случайность, чтобы результаты были воспроизводимы.

## Абсолютные правила для данных (самое важное)
- Не заполняй молча и не фабрикуй пропущенные значения. Если есть пропущенные
  значения, сообщи о них и уточни, как их обрабатывать.
- Не перезаписывай файлы сырых данных. Записывай вывод в `data/processed/`.
- Документируй все допущения (фильтры, исключённые строки, единицы) в комментариях к коду.

## Определение готовности
`pytest` проходит, `ruff check .` чист, и результаты воспроизводятся из чистого состояния.

# Go

## Команды
- Сборка: `go build ./...`
- Тесты:  `go test ./...`
- Форматирование: `gofmt -w .` и `go vet ./...`

## Соглашения
- Не проглатывай ошибки. Всегда обрабатывай их через `if err != nil` и возвращай
  с контекстом (`fmt.Errorf("...: %w", err)`).
- Держи вложенность мелкой с помощью ранних return.
- Используй конкурентность только когда нужно. Следи за утечками goroutine и гонками
  (добивайся прохождения `go test -race`).
- Комментируй экспортированные символы. Предпочитай стандартную библиотеку.

## Абсолютные правила
- Не добавляй ненужные абстракции или интерфейсы (создавай их при необходимости).
- Перед добавлением зависимости сначала проверь, достаточно ли стандартной библиотеки.

## Определение готовности
`go build ./...`, `go vet ./...` и `go test -race ./...` все проходят.

# Rust

## Команды
- Сборка: `cargo build`
- Тесты:  `cargo test`
- Lint:   `cargo clippy -- -D warnings`
- Форматирование: `cargo fmt`

## Соглашения
- Не используй небрежно `unwrap()` / `expect()` в продакшен-коде.
  Правильно обрабатывай `Result` / `Option` через `?` или match.
- `unsafe` в принципе запрещён. Если действительно необходим, укажи причину в комментарии.
- Следуй компилятору по заимствованиям и временам жизни. Переосмысли дизайн, прежде чем
  спасаться через `clone()`.
- Делай типы ошибок осмысленными с помощью `thiserror` / `anyhow` и т. д.

## Определение готовности
`cargo build` и `cargo test` проходят, и
`cargo clippy -- -D warnings` сообщает ноль предупреждений.

# Ruby on Rails

## Команды
- Запуск:    `bin/rails server`
- Миграция:  `bin/rails db:migrate`
- Тесты:     `bin/rails test` (или `bundle exec rspec`)
- Форматирование: `bundle exec rubocop -A`

## Соглашения (следуй стилю Rails)
- Уважай «соглашение важнее конфигурации»; не изобретай собственную структуру.
- Избегай толстых контроллеров / моделей. Выноси логику в Services / Concerns.
- Ограничивай ввод с помощью strong parameters.
- Избегай N+1 (используй `includes`).
- Изменения схемы получают новую миграцию. Не редактируй уже выполненные.

## Абсолютные правила
- Никогда, ни в коем случае не коммить `.env` или учётные данные.
- Не запускай разрушительные команды на продакшен-БД.
- Когда меняешь поведение, добавляй или обновляй тесты.

## Определение готовности
Тесты и `bundle exec rubocop` проходят.

# SQL / миграции базы данных

## Абсолютные правила (защита данных прежде всего)
- Не запускай разрушительные операции над продакшен-данными по своей инициативе
  (DROP / TRUNCATE / безусловный DELETE или UPDATE).
- Миграции должны предоставлять процедуру отката, а не только прямое направление.
- Не редактируй уже выполненные миграции. Всегда добавляй новые.
- Удаляй или переименовывай столбцы поэтапно («добавить -> мигрировать -> вывести из обращения»); не делай это одним махом.

## Соглашения по запросам
- Избегай `SELECT *`; указывай нужные столбцы.
- Убедись, что условия WHERE / JOIN могут использовать индекс.
- Разбивай крупные обновления на пакеты, чтобы держать время блокировки коротким.
- Для разрушительных проверочных запросов сначала подтверди число затронутых строк через `SELECT` перед запуском.

## Определение готовности
И применение, и откат успешны в окружении, эквивалентном staging, и ты
подтвердил отсутствие непреднамеренных изменений существующих данных.

# Подход разработки через тестирование

Меняя поведение, каждый раз следуй этому циклу:
1. Сначала напиши «падающий тест», выражающий желаемое поведение.
2. Запусти тест и подтверди, что он падает по правильной причине.
3. Напиши минимум кода, нужный, чтобы тест прошёл.
4. Запусти весь набор тестов и подтверди, что всё зелёное.
5. Рефактори, сохраняя зелёное.

## Абсолютные правила
- Не удаляй и не пропускай тесты, чтобы набор прошёл.
- Не ослабляй проверки, чтобы добиться зелёного.
- Если тест действительно неверен, объясни почему, прежде чем менять его.
- Новый код без тестов не «готов».

## Определение готовности
Весь набор проходит, покрытие не упало, и откат
реализации заставляет новый тест падать (т. е. это осмысленный тест).

# Подход к отладке

Действуй в этом порядке. Не исправляй угадыванием:
1. Установи шаги воспроизведения (как вызвать баг).
2. Запиши ожидаемое поведение и фактическое поведение, по одному предложению каждое.
3. Сформулируй гипотезу. Проверь её логами или минимальным воспроизведением перед исправлением.
4. Как только определил причину, примени минимальное исправление.
5. После исправления подтверди, что баг исчез по шагам воспроизведения, и что существующие тесты проходят.
6. Если возможно, добавь регрессионный тест, который ловит этот баг.

## Абсолютные правила
- Не меняй несколько мест сразу, пока причина неизвестна.
- Не останавливайся на «пока работает». Объясни, почему это исправлено.
- Не смешивай несвязанный рефакторинг с отладкой.

# Подход к рефакторингу

## Основной принцип
Не меняй внешне наблюдаемое поведение. Не меняй вывод или побочные
эффекты для любого ввода вообще.

## Шаги
1. Сначала подтверди, что для целевой области есть тесты и они зелёные.
   Если нет, сначала напиши характеризационные тесты, фиксирующие текущее поведение.
2. Меняй маленькими, единичными шагами, запуская тесты после каждого шага.
3. Держи один коммит = один вид улучшения.

## Абсолютные правила
- Не смешивай добавление функций или исправление багов с рефакторингом (делай их отдельной работой).
- Если тест стал красным, остановись прямо там. Не продолжай.
- Не меняй сигнатуры публичного API по своей инициативе (при необходимости сначала уточни).

## Определение готовности
Все тесты остаются зелёными, и код стал читабельнее с меньшим дублированием.

# Как написать проектный документ

Перед реализацией сначала изложи прозой следующее (не пиши код):

## 1. Цель
Задача, которую нужно решить, и условия, при которых её можно считать достигнутой (критерии успеха).

## 2. Текущее состояние и ограничения
Существующее устройство, зависимости и ограничения, которые надо соблюсти (производительность, совместимость, срок).

## 3. Предложение по дизайну
- Выбранный подход и подходы, которые ты рассмотрел и отверг (и почему).
- Поток данных, ключевые интерфейсы и файлы, которые нужно изменить.

## 4. Риски и открытые вопросы
Что может сломаться, допущения, которые надо подтвердить, и пункты, требующие решения.

## 5. План
Разбей реализацию на маленькие шаги, упорядоченные в проверяемые единицы.

## Правила
- Не начинай реализацию, пока этот дизайн не одобрен.
- Перечисляй неизвестное в «открытых вопросах»; не заполняй их собственными допущениями.

# Как делать большие изменения

## Основной принцип
Избегай одного гигантского изменения. Разбей его так, чтобы каждый шаг был независимо
проверяемым, тестируемым и (в идеале) развёртываемым.

## Шаги
1. Разложи изменения, ведущие к финальной форме, на последовательность маленьких,
   независимых шагов и представь её.
2. Для каждого шага запиши «что / почему / область влияния» в 1-2 строках.
3. После каждого шага запусти весь набор тестов и подтверди зелёное перед переходом дальше.
4. Продвигайся, сохраняя обратную совместимость (добавить -> мигрировать -> вывести старый путь из обращения).

## Абсолютные правила
- Не переписывай широкую область сразу и не «протестируй всё вместе потом».
- Если шаг становится слишком большим, разбей его дальше.
- Держи каждый шаг на детализации, которую можно откатить.

## Определение готовности
Тесты зелёные после завершения всех шагов, и каждый промежуточный коммит тоже не сломан.

# Инструкции по код-ревью

Проверь изменения, сгруппируй их по серьёзности и докладывай в этом порядке:
1. CRITICAL - дыры в безопасности, потеря данных, сбои, сломанная аутентификация
2. HIGH     - логические баги, состояния гонки, отсутствующая обработка ошибок
3. MEDIUM   - проблемы производительности, отсутствующие тесты, запутанные имена
4. LOW      - мелкие стилевые придирки (только если нет более высоких проблем)

## Как докладывать
- Для каждой находки: файл:строка / что не так / почему это важно / конкретное исправление.
- Цитируй только наименьший релевантный фрагмент. Не вставляй файл целиком.
- Если изменение верно, скажи это явно. Не фабрикуй проблемы.

## Чего не делать
- Не закапывай настоящие баги под кучей придирок LOW.
- Не переписывай файлы целиком. Предлагай наименьший diff.
- Если нет реального вреда, не отмечай строки за пределами области diff.

## Вывод
Заверши однострочным вердиктом: APPROVE / REQUEST CHANGES / BLOCK, с причиной.

# Правила Git / PR

## Коммиты
- Используй Conventional Commits: `type(scope): summary`
  type: feat, fix, refactor, test, docs, chore.
- Один коммит = одно логическое изменение. Держи его маленьким и проверяемым.
- В теле пиши «почему», а не «что».

## Абсолютные правила
- Не делай `git push`, если не сказано.
- Не делай force-push, rebase или amend на общих ветках / main.
- Не коммить секреты, .env, учётные данные или большие бинарники.
- Добавляй файлы по имени. Не загребай всё подряд через `git add -A`.

## Pull requests
- Заголовок в пределах 70 символов. Тело - это «Сводка» + «План тестирования (контрольный список)».
- Отмечай любые ломающие изменения.
- Не делай merge. Создай PR и сообщи URL.

# Инструкции по ревью безопасности

Проверь изменения по порядку по следующим аспектам и доложи о любых
найденных проблемах с оценкой серьёзности:
- Отсутствующая валидация ввода (инъекции: SQL / команды / XSS / SSRF)
- Пробелы в аутентификации/авторизации (отсутствующие проверки прав, повышение привилегий)
- Раскрытие секретов (захардкоженные ключи/токены, вывод в логи)
- Небезопасные значения по умолчанию (избыточная открытость, слабый CORS, непроверенные редиректы)
- Известные уязвимости в зависимостях, небезопасное использование криптографии / ГСЧ

## Как докладывать
- Для каждой находки: место / сценарий атаки (как это можно эксплуатировать) / конкретное исправление.
- Отмечай подозрения, в которых не уверен, как «требует подтверждения» (не пропускай их молча).
- Если проблемы нет, заяви «проблем нет» вместе с проверенными аспектами.

## Чего не делать
- Не генерируй настоящий код атаки или шаги эксплуатации (показывай только исправления).

# Правила работы с Docker / инфраструктурой

## Абсолютные правила (предотвращение разрушения прежде всего)
- Не запускай разрушительные команды против продакшен- или общих окружений по своей инициативе
  (`docker system prune`, удаление томов, `down -v` и т. д.).
- Привязывай образы к фиксированным тегам. Не полагайся на `latest`.
- Передавай секреты через переменные окружения / управление секретами.
  Не запекай их в Dockerfile или образ.
- Держи открытые порты и привилегии (privileged и т. д.) на необходимом минимуме.

## Соглашения
- Держи Dockerfile маленькими с многоэтапными сборками, помня о кэшировании слоёв.
- Запускай от непривилегированного пользователя.
- После изменений собери и запусти локально, чтобы проверить, перед отчётом.

## Определение готовности
`docker build` проходит, контейнер запускается, и health check / базовую
работу можно подтвердить.

# Правила для зависимостей

## Абсолютные правила
- Перед добавлением зависимости проверь, достаточно ли стандартной библиотеки или существующей
  зависимости.
- При добавлении новой зависимости добавь однострочную заметку о её назначении, альтернативах
  и статусе сопровождения.
- Не повышай мажорные версии по своей инициативе (только когда сказано).
- Не пересоздавай lock-файлы (package-lock.json и т. д.) по своей инициативе.
- Избегай пакетов сомнительного происхождения или с крайне малым числом звёзд либо плохим сопровождением.

## Шаги
1. Укажи причину добавления или обновления.
2. После добавления подтверди, что сборка и тесты проходят.
3. Подтверди, что лицензия не конфликтует с твоим вариантом использования.

## Определение готовности
Сборка и тесты проходят после изменения зависимостей, и ты можешь объяснить diff в lock-файле.