AGENTS.md¶

Инструкции для людей и ИИ-агентов, работающих в этом репозитории. Подробная выжимка требований организаторов — в misc/HACKATHON.md, полная запись Q&A — в misc/Умный кредитный кабинет Альфа Хакатон.txt, кейс — в misc/Альфа_Хак_Умный_кредитный_кабинет.pdf.

Контекст проекта¶

Хакатон Альфа-Банка, трек «Умный кредитный кабинет» для предпринимателей (малый и микробизнес). Строим работающий прототип кредитного конвейера: личный кабинет клиента (ИП / юрлицо) + рабочее место сотрудника банка, сквозной сценарий от заявки до выдачи кредита.

Приоритет: работающий, самостоятельно запускаемый, задокументированный end-to-end сценарий > количество фич.

Работа над v2 (читать первым)¶

Кредитный конвейер построен по спецификации v2. Код v1 удалён в T38; рабочая логика находится в apps/api/workflow.py и модулях v2. Исторические миграции сохранены для обновления существующих баз. Как устроено то, что есть, — README.md, ARCHITECTURE.md и docs/ (PROCESS.md, DATA_MODEL.md, SLA.md, SIMPLIFICATIONS.md).

Перед началом работы прочитай:

docs/v2/SPEC.md — что строим и почему (источник правды по кредитной логике);
docs/v2/TASKS.md — задачи, зависимости, владельцы, журнал решений;
docs/v2/CONTRACTS.md — форматы данных между треками;
docs/v2/NOTES.md — заметки, которые предыдущие задачи оставили твоей.

Правила:

Работай в рамках одной задачи из TASKS.md; ветка называется по её ID (t16-limit-pricing), один PR в main.
Меняй только папки своего трека (таблица владения в TASKS.md). Нужна правка в чужой папке — согласуй с владельцем.
apps/api/contracts.py, tests/fixtures/ и config/ — общие: менять только отдельным PR, который одобряют все трое (CONTRACTS.md).
Не пересматривай решения из журнала решений в TASKS.md. Если решение кажется неверным — подними вопрос в команде, а не меняй код.
Обновляй статус своей задачи в TASKS.md в том же PR.
Никаких «оставим на потом», которые остались только в чате. Всё, что задача оставляет другой задаче, записывается в docs/v2/NOTES.md под ID той задачи, в том же коммите. Перед началом работы прочитай свой раздел в NOTES.md и раздел «Any task»; в конце удали заметки, которые твой PR закрыл.
Язык: документация — на русском; TASKS.md, имена файлов, идентификаторы и код — на английском.
misc/conveyor_v2_proposal.pdf — экспорт docs/v2/SPEC.md для экономического блока (pandoc + xelatex); при заметных правках спецификации его стоит перегенерировать.

Жёсткие ограничения (нарушать нельзя)¶

Никаких интеграций с реальными банковскими или внешними системами. Любая внешняя система (АБС, БКИ, ФНС/госсервисы, SMS, ЭП, платежи) — мок/стаб/симулятор внутри проекта.
Только синтетические данные. Генерировать сидами/скриптами в репозитории. Не использовать реальные персональные или финансовые данные.
Только модели с открытыми весами — для LLM, OCR, эмбеддингов, классификаторов, любых ML-компонентов. Запрещены закрытые API (OpenAI GPT, Yandex OCR/Vision и т.п. как модели). Размер LLM — желательно ≤120B параметров.
LLM-интеграция только через OpenAI-compatible API и полностью конфигурируемая через переменные окружения. Рекомендуемые имена:
LLM_BASE_URL
LLM_API_KEY
LLM_MODEL

Никаких захардкоженных провайдеров, ключей или моделей. Эксперты подставят свои значения. 5. ИИ — опциональная надстройка. Основной сценарий обязан работать без LLM (если LLM недоступна — деградация, а не падение). Детерминированная бизнес-логика — норма. 6. Запуск без авторов. Всё (кроме самой LLM) поднимается через Docker / docker compose одной-двумя командами по README на любой ОС. Никаких ручных шагов, которых нет в инструкции. 7. Ресурсы: стек в простое должен укладываться примерно в 12 ГБ RAM; не рассчитывать на GPU. Клиент — веб в браузере обычного ноутбука.

Функциональный скоуп¶

Обязательно (сквозной сценарий не должен обрываться):

Клиент — уже действующий клиент банка. Регистрации нет. Авторизация — простая/демо-профили допустимы.
Подача заявки → проверка данных → скоринг / принятие решения → подбор и предложение продукта → подписание (упрощённое: код подтверждения/простая ЭП в интерфейсе) → выдача (мок зачисления на счёт) → клиент видит результат.
Сторона банка: сотрудник видит заявки, статусы, данные, результат проверок и скоринга, может принимать/корректировать решения там, где процесс не автоматизирован.
Кредитные продукты — свои, условные, но с реалистичными условиями (с учётом текущей ключевой ставки ЦБ и рыночных ставок).
Объяснимость: для каждого решения/рекомендации система сохраняет причины (какие правила/факторы сработали). Одинаковые входы → одинаковый, объяснимый результат.

Вне скоупа (не делать без явного запроса): сопровождение кредита после выдачи, регистрация юрлица, физлица без бизнеса, реальные проводки.

Опционально (бонусы, только после рабочего базового сценария): загрузка и распознавание документов, прогноз кассового разрыва, AI-ассистент, обученная ML-модель скоринга (базово — скоринговая карта с заданными вручную весами и чистым интерфейсом для замены), адаптивная мобильная вёрстка. Набор предложений (вместо контрпредложения) в v2 входит в базовый сценарий — см. docs/v2/SPEC.md, раздел 10.

Правила работы с кодом¶

Сначала доводить базовый сценарий до рабочего состояния, потом добавлять фичи.
Каждый мок/упрощение помечать в коде (например, комментарий // MOCK: / # SIMPLIFICATION:) и вносить в реестр упрощений docs/SIMPLIFICATIONS.md с объяснением, что было бы в реальности.
Внешние интеграции — за интерфейсом/адаптером, чтобы мок можно было заменить реальной реализацией.
Скоринг/правила принятия решений — в отдельном модуле с конфигурируемыми порогами и логированием причин.
Секреты и конфигурация — только через .env (в репозитории — .env.example со всеми переменными).
Сиды синтетических данных должны покрывать разные исходы: одобрение, отказ, запрос данных, набор предложений вместо запрошенного, ручное рассмотрение; ИП и юрлица (демо-персоны — apps/world/PERSONAS.md).
Не добавлять зависимости от закрытых облачных сервисов.

Документация (обязательна, оценивается)¶

При изменении функциональности обновлять соответствующую документацию:

README.md — что это, как запустить с нуля (Docker), как подключить LLM (LLM_*), демо-учётки и сценарий проверки по шагам.
Аналитика: модель кредитного процесса (этапы, статусы, роли), требования, модель данных, API/обмен данными, обоснование решений (почему этап есть, упрощён или отсутствует).
Реестр упрощений и моков.
Используемые модели: ссылки на Hugging Face для LLM; OCR и прочие модели — в репозитории или с инструкцией получения.
Опционально, но ценно: SLA/критичность по этапам и как они обеспечиваются; продуктовые артефакты (CJM, JTBD).

Definition of Done для изменения¶

[ ] docker compose up на чистой машине поднимает решение по README без дополнительных шагов.
[ ] Сквозной сценарий клиент → банк → выдача проходит без ошибок, в том числе при недоступной LLM.
[ ] Нет обращений к реальным внешним системам и закрытым моделям.
[ ] LLM-настройки берутся только из LLM_BASE_URL / LLM_API_KEY / LLM_MODEL.
[ ] Новые моки/упрощения помечены и внесены в документацию.
[ ] Документация обновлена.