AGENTS.md · diff
git:20260916.002f3f3 to git:20260918.c8c69ae
11 added, 2 removed. Audit A to A.
# Правила для 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` генератор дописывает: класса из спецификации там
+ Заготовки 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`
не удаляй.