AGENTS.md git:20260925.3f736c5A

Immutable. This exact content never changes and is served at /api/v1/blob/42b7fbddfa1a3b7b.

# AGENTS.md

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

## Что это

Русская адаптация скилла [avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing): два скилла (`skills/avoid-ai-writing-russian`, `skills/antiplagiat`) и детектор на Python (пакет `aiw_ru` в `src/`, команда `aiw-ru`). Всё пишется на русском: документация, комментарии, сообщения коммитов. Идентификаторы в коде — на английском.

## Устройство

- `skills/avoid-ai-writing-russian/SKILL.md` — точка входа скилла: договор о правке, режимы, уровни серьёзности, формат ответа, «никогда не добавляй». Держать короче 500 строк.
- `skills/avoid-ai-writing-russian/references/` — каталог примет по темам (`vocabulary.md`, `typography.md`, `sentences.md`, `rhetoric.md`, `chat.md`, `structure.md`) и профили контекста и голоса (`profiles.md`). Оглавление и порядок чтения в SKILL.md: агент открывает файл темы, когда правит находку из неё, а не весь каталог.
- `skills/antiplagiat/SKILL.md` — под-скилл подготовки к «Антиплагиату».
- `src/aiw_ru/text.py` — нормализация (невидимые символы, подмена букв, ё→е) с картой смещений, маскирование защищённых областей, разбиение на блоки и предложения.
- `src/aiw_ru/lexicon.py` — словари примет на мини-языке фраз (`*` — любое окончание).
- `src/aiw_ru/detect.py` — детектор: словари, отпечатки, типографика, структура, стилометрия, оценка.
- `src/aiw_ru/antiplagiat.py` — оценка по фрагментам и калибровка.
- `src/aiw_ru/validate.py` — проверка сохранности правки.
- `src/aiw_ru/types.py` — результаты для JSON (модели pydantic: поля в snake_case, в JSON — camelCase).
- `src/aiw_ru/compat.py` — семантика JavaScript, с которой переносился детектор: регулярные выражения, округление, trim.
- `src/aiw_ru/features.py`, `src/aiw_ru/models.py` — признаки и необязательная модель LightGBM с Hugging Face.
- `src/aiw_ru/cli.py` — команда `aiw-ru` (вывод через rich).
- `scripts/llmtrace.py`, `scripts/train.py`, `scripts/hub.py` — замер детектора на корпусе LLMTrace, обучение LightGBM и выкладка модели с карточкой на Hugging Face. Подробности в CONTRIBUTING.md, разделы «Замеры на корпусах» и «Модель LightGBM».
- `scripts/release.py` и соседние — выпуск версий, проверки версий, коммитов и невидимых символов; `evals/` — поведенческие проверки скиллов.

## Правила

- Любое правило детектора должно быть описано в каталоге `references/`. Обратное не обязательно: правила на суждение живут только в каталоге.
- Новый тип находки получает вес в `WEIGHTS`, подпись в `TYPE_LABELS` и тест.
- Правило не должно срабатывать на `tests/fixtures/corpus/human/`; точность важнее полноты.
- Не писать невидимые символы в исходники буквально: только `\uXXXX` или `chr()`.
- Скилл помогает автору с его собственным текстом и с оформлением заимствований как цитирований. Не добавлять приёмы, которые маскируют чужой текст или обманывают проверку техническими уловками.
- Документация проекта должна проходить самопроверку детектором (хук `selfscan`) без находок P0 и P1.
- Только абсолютные импорты: `from aiw_ru.text import words`. Относительные запрещены правилом ruff TID252.
- Замеры и обучение живут только в `scripts/`, не в `skills/`; их зависимости в группе `train` (дообучение трансформера — в группе `transformer`), инструменты разработки — в группе `dev`. По умолчанию группы не ставятся: `uv run --project ../..` из скилла получает только детектор. Для разработки `uv sync --group dev --group train`. Корпуса, кэши и обученные модели хранятся вне репозитория (`~/.cache/aiw-ru`, модели — на Hugging Face), в git их не класть.
- Модели необязательны: скиллы и детектор работают без них, а ставить модель агент предлагает пользователю и ставит только с его согласия.

## Команды

```bash
uv run --group dev --group train pytest
```

```bash
uv run --group dev --group train ty check
```

```bash
uv run --group dev prek run --all-files
```