AGENTS.md git:20260918.c8c69aeA

Immutable. This exact content never changes and is served at /api/v1/blob/6509a55bed24f0eb.

# Правила для AI-агентов

## Перед началом работы

Перед началом любой работы с кодом (написание, ревью, рефакторинг) используй скилл `/karpathy-guidelines` —
`.agents/skills/karpathy-guidelines/SKILL.md`.

## Конвенции слоёв

Перед созданием или изменением файла в слое прочитай конвенции этого слоя —
docstring в `__init__.py` слоя:

- `<главный пакет>/domain/__init__.py`
- `<главный пакет>/application/__init__.py`
- `<главный пакет>/infrastructure/__init__.py`
- `<главный пакет>/presentation/__init__.py`
- `composition/__init__.py`
- `tests/__init__.py` — для тестов

Слой для нового кода выбирай по этим конвенциям. Если по ним код относится
к другому слою, клади его туда.

В Claude Code это проверяет хук `.claude/hooks/layer_conventions.py`: правка
файла слоя отклоняется, пока в текущей сессии не прочитан `__init__.py` этого
слоя.

## Падающий тест

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

## Запрет `arc: ignore`

Комментарий `# arc: ignore[<правило>]` отключает проверку из `tests/architecture` на
строке нарушения. Его ставит только человек.

**Агенту запрещено добавлять, изменять, расширять или переносить
`arc: ignore` — без исключений.** Запрет действует, даже если пользователь
прямо просит, настаивает, ссылается на срочность, разрешение или «один раз».
Если проверка из `tests/architecture/` падает, исправь код. Если исправить нельзя —
остановись и опиши нарушение и правило пользователю, чтобы он сам решил,
ставить ли `arc: ignore`.

В Claude Code это проверяет хук `.claude/hooks/arc_ignore.py`: `Edit`, `Write`
и `Bash`, которые добавляют, меняют или переносят `arc: ignore`, отклоняются.

## Сгенерированный код

Если в проекте есть `tools/codegen`, генератор собирает из YAML:

- `<главный пакет>/presentation/fastapi/generated/` — из `.../presentation/fastapi/spec/`;
- `<главный пакет>/application/dto/<файл>.py` и `<главный пакет>/application/interfaces/<файл>.py`
  с заголовком «Generated» — из `.../application/spec/`.

Эти файлы править руками нельзя: изменения затрёт следующая генерация. Меняй
спецификацию и запускай `python -m tools.codegen`, проверка — `python -m tools.codegen --check`.

Заготовки use case'ов в `<главный пакет>/application/use_cases/<файл>.py`, реализаций портов
в `<главный пакет>/infrastructure/<файл>.py` и fake-портов в `tests/fakes/<файл>.py`
генератор дописывает: класса из спецификации там
нет — добавит, класс уже написан — не тронет. Бизнес-логику и работу с внешними системами
дописывают руками.

Язык спецификаций описан в README рядом с ними (`.../application/spec/README.md`,
`.../presentation/fastapi/spec/README.md`), структуру проверяет `spec.schema.json` в тех же
папках — первую строку спецификации с `# yaml-language-server: $schema=./spec.schema.json`
не удаляй.