#Промпты для ИИ-агента

ИИ-агент может написать большую часть интеграции со smartica.ai. Статья ведёт от первого запуска агента до проверенного результата.

Опытным разработчикам достаточно раздела с промптом. Остальное можно пролистать.

#Что вы получите

После статьи у вас:

• рабочая связка «кнопка в карточке приёма → вход врача → возврат протокола».
• тесты, которые проверяют идемпотентность и авторизацию.
• понимание, что проверить руками перед рабочим запуском.

Вы не получите интеграцию, которую можно включить без проверки. ИИ пишет обвязку. ИИ регулярно ошибается в требованиях, которые нельзя вывести из кода. Ниже есть раздел с типичными ошибками. Прочитайте этот раздел до запуска агента.

#Если вы никогда не работали с ИИ-агентом

Пропустите этот раздел, если уже пользуетесь Cursor, Claude Code или похожим инструментом.

#Чем агент отличается от чата

Обычный чат, например веб-версия ChatGPT, не видит ваш проект. Вы копируете туда кусок кода, получаете ответ и вставляете ответ обратно руками.

ИИ-агент работает внутри вашего репозитория. Агент умеет:

• сам искать нужные файлы и читать их.
• редактировать код и создавать новые файлы.
• запускать тесты, линтер и сборку.
• читать вывод ошибок и исправлять то, что агент сломал.
• загружать документацию по ссылке.

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

#Что установить

Для этой задачи инструменты равнозначны. Промпт ниже работает в любом. Если выбираете впервые, берите Cursor. В Cursor видно, какие файлы меняются.

Актуальные инструкции по установке смотрите на сайте выбранного инструмента. Инструкции меняются чаще, чем эта статья.

#Первый запуск, если выбрали Cursor

1. Установите Cursor и откройте в Cursor папку с репозиторием вашей МИС.
2. Откройте панель агента. Обычно панель открывается по Cmd+I на macOS или Ctrl+I на Windows.
3. Убедитесь, что включён агентский режим, а не простой чат. В агентском режиме инструмент сам правит файлы и запускает команды.
4. Вставьте промпт из этой статьи и отправьте промпт.

Дальше агент читает проект и предлагает изменения. Каждое изменение видно как diff, зелёные и красные строки. Ничего не применяется молча.

#Сделайте отдельную ветку

git checkout -b smartica-integration

Агент меняет реальные файлы. На первых запусках агент ошибается. Откатите изменения одной командой:

git checkout .

Никогда не запускайте агента на ветке, где лежит незакоммиченная работа. Сначала закоммитьте работу или спрячьте работу:

git stash

#Что подготовить перед запуском

#1. Параметры подключения от smartica.ai

Без параметров подключения агента не запускайте. Точный адрес SSO и platform выдаёт smartica.ai при подключении. Подобрать адрес и platform нельзя. Если агент не получит адрес и platform, агент придумает правдоподобные значения. Код при этом не заработает. Все запросы возвращают 404.

Как получить адрес и platform, описано в статье Подключение. Пока ждёте ответ, проходите остальные пункты.

#2. Знание своего проекта

Агент находит модели сам. Подскажите:

• как называется модель или таблица приёма.
• как называется модель или таблица врача.
• где хранится текст протокола и поля протокола.
• как в проекте проверяется, что врач имеет доступ к приёму.

С такой подсказкой результат точнее. Если не знаете, оставьте пункт агенту. В промпте есть шаг, на котором агент изучает проект и задаёт вопросы.

#3. Контракт в общих чертах

Прочитайте Обзор. Вам нужно понимать, что запросы идут в обе стороны. Иначе вы не оцените, верно ли агент собрал интеграцию.

#Правила безопасности

Правил три. Нарушение любого правила — инцидент.

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

Не вставляйте данные пациентов. Ни стенограмм, ни фрагментов реальных карт, ни ФИО. Для примеров используйте выдуманные данные.

Не давайте агенту доступ к рабочей базе. Работайте на локальной или тестовой копии. Агент может выполнить команду, которую вы не ожидали.

Если ваша компания запрещает отправлять исходный код во внешние сервисы, уточните политику до начала работы. Агент отправляет содержимое файлов на серверы модели.

#Документация в машиночитаемом виде

Наши статьи доступны в формате, удобном для агентов:

• индекс всей базы знаний: https://smartica.ai/llms.txt.
• любая статья как сырой Markdown. Добавьте .md к адресу, например https://smartica.ai/help/integrations/glossary.md.

Давайте агенту версии .md. HTML-обёртка зашумляет контекст. Промпт ниже уже просит статьи в Markdown.

#Готовый скилл вместо промпта

Промпт ниже одноразовый. Промпт копируют, применяют и забывают. Если вы возвращаетесь к интеграции, поставьте скилл.

Скилл — файл с инструкциями в вашем репозитории. Агент подхватывает скилл сам, когда кто-то работает с кодом интеграции. Сегодня скилл читаете вы. Через год скилл читает коллега, который эту статью не открывал. Агент соблюдает инварианты контракта и без чтения этой статьи.

Установка — одна команда в корне репозитория.

Каталог .agents/skills — общий стандарт. Каталог читают Cursor и Codex. Начните с этого каталога.

mkdir -p .agents/skills/smartica-mis-integration && \
curl -fsSL -o .agents/skills/smartica-mis-integration/SKILL.md \
  https://smartica.ai/skills/smartica-mis-integration/SKILL.md

Claude Code этот каталог пока не читает. Для Claude Code нужна отдельная копия:

mkdir -p .claude/skills/smartica-mis-integration && \
curl -fsSL -o .claude/skills/smartica-mis-integration/SKILL.md \
  https://smartica.ai/skills/smartica-mis-integration/SKILL.md

#Какой инструмент какой каталог читает

Единого каталога на все три инструмента сейчас нет. Сделайте так:

• если в команде только Cursor или Codex, достаточно .agents/skills.
• если кто-то работает в Claude Code, выполните обе команды. Файл лежит в двух местах.

Частая ошибка: скилл для Codex кладут в .codex/skills. Этот путь встречается в сторонних инструкциях. Codex этот путь не читает. Скилл не загружается. Ошибки нет. Codex ищет .agents/skills во всех каталогах от текущего до корня репозитория. Проверить, что скилл виден, можно командой /skills. В Cursor откройте Customize → Skills.

Файл везде один и тот же, SKILL.md. SKILL.md — открытый стандарт. Различаются только каталоги. Если пользуетесь другим инструментом, посмотрите в документации инструмента, где инструмент ищет скиллы.

Закоммитьте файл в репозиторий. Тогда файл появится у всей команды. При обновлении скилла выполните те же команды заново.

Посмотреть содержимое можно по прямой ссылке: smartica-mis-integration/SKILL.md. В файле инварианты контракта, лимиты, список типичных ошибок и указание остановиться и спросить, если параметры подключения не выданы.

Скилл намеренно короткий. Скилл не дублирует контракт, а ссылается на статьи в машиночитаемом виде. При расхождении верна документация.

Скилл и промпт не конфликтуют. Сначала поставьте скилл, затем запустите промпт. Агент работает точнее, потому что часть требований уже в контексте.

#Заполните плейсхолдеры

В промпте есть значения в <угловых скобках>. Замените все значения в угловых скобках. Иначе агент угадывает.

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

#Главный промпт

Скопируйте блок кнопкой в правом верхнем углу. Замените плейсхолдеры и отправьте текст агенту.

Ты работаешь в репозитории медицинской информационной системы:
- название: <MIS_NAME>
- стек и версии: <STACK_AND_VERSIONS>
- точный SSO endpoint smartica.ai: <SSO_ENDPOINT_FROM_SMARTICA>
- зарегистрированный platform: <PLATFORM_FROM_SMARTICA>
- модель/таблица приёма: <ENCOUNTER_MODEL_OR_TABLE>
- модель/таблица врача: <DOCTOR_MODEL_OR_TABLE>

Нужно реализовать интеграцию МИС со smartica.ai.

Сначала:
1. Открой https://smartica.ai/llms.txt — это канонический индекс документации.
2. Из секции «Интеграция с МИС» загрузи нужные статьи как Markdown
   (URL оканчиваются на .md). Не парси HTML-страницы /help, если доступен .md.
3. Обязательно прочитай:
   - https://smartica.ai/help/integrations/overview.md
   - https://smartica.ai/help/integrations/glossary.md
   - https://smartica.ai/help/integrations/test-environment.md
   - https://smartica.ai/help/integrations/launch.md
   - https://smartica.ai/help/integrations/launch-pull.md
   - https://smartica.ai/help/integrations/launch-and-sso.md
   - https://smartica.ai/help/integrations/import.md
   - https://smartica.ai/help/integrations/mis-api-get-encounter.md
   - https://smartica.ai/help/integrations/mis-api-export-encounter.md
   - https://smartica.ai/help/integrations/field-types.md
   - https://smartica.ai/help/integrations/value-sets.md
   - https://smartica.ai/help/integrations/authentication-and-errors.md
   - https://smartica.ai/help/integrations/limits.md
4. Изучи структуру проекта, существующие conventions, auth, валидацию,
   обработку ошибок и тесты.
5. Найди текущий способ проверки доступа врача к приёму.
6. Составь короткий план и перечисли недостающие обязательные данные.
7. Если неизвестны точный endpoint, схема хранения протокола или auth
   входящих запросов, остановись и задай вопросы. Не выдумывай контракт.

Реализуй:

1. Серверный запуск smartica.ai
- Добавь кнопку/действие «smartica.ai» в карточку приёма.
- Браузер передаёт бэкенду только ID текущего приёма.
- Бэкенд проверяет авторизацию врача и доступ к приёму.
- Бэкенд получает email и ФИО врача из доверенных данных МИС.
- Бэкенд вызывает точный SSO endpoint методом POST:
  Authorization: Bearer <значение переменной SMARTICA_SSO_KEY>
  Content-Type: application/json
  Accept: application/json
- JSON: user_email, user_full_name, encounter_id.
- encounter_id всегда передавай строкой.
- user_full_name передавай всегда, даже для существующего врача.
- Верни браузеру redirect на launch_url или безопасно открой его в новой вкладке.
- Не собирай launch_url самостоятельно и не сохраняй параметр t.

2. GET /api/for-smartica/encounters/{encounter_id}
- Защити endpoint проверкой заголовка Authorization: Bearer по HTTPS.
- Ожидаемый токен читай из SMARTICA_INBOUND_TOKEN.
- Сравнивай токен за постоянное время (timing-safe), а не оператором ==.
- Найди приём и проверь его доступность для интеграции.
- Верни 200 JSON:
  encounter_id, user_email, template,
  fields: [{ id, label }].
- fields[].id должны быть уникальными и стабильными.
- fields[].label — заголовок для заполнения smartica.ai. Обычно это подпись
  поля на бланке. Если подпись понятна только вместе с разделом выше,
  опишите поле целиком. Пример: «Объективный статус. Норма», а не «Норма».
- Для ошибок возвращай подходящий non-2xx и безопасный JSON message.

3. PUT /api/for-smartica/encounters/{encounter_id}
- Используй только PUT и ту же проверку Bearer-токена.
- Валидируй encounter_id, fields и transcript.
- Проверь совпадение ID в URL и JSON.
- В одной транзакции обнови переданные fields по id.
- Не очищай поля, отсутствующие в массиве.
- Пустой массив fields — валидный запрос: сохрани стенограмму.
- Замени сохранённую стенограмму полной версией transcript.
- Сохраняй многострочный текст и UTF-8 без потерь.
- Сделай обработку идемпотентной по encounter_id:
  повторный payload не создаёт новую карточку, протокол или вложение.
- Верни 200 JSON:
  { "encounter_id": "...", "status": "saved" }.
- Не возвращай 204, HTML или пустое тело.

4. Конфигурация и безопасность
- Базовый адрес smartica.ai вынеси в конфигурацию, не хардкодь домен из примеров:
  разработка идёт на тестовой площадке, боевой адрес подставляется при запуске.
- Секреты только в env/config; добавь placeholders в .env.example.
- Не помещай ключи, токены, launch_url или SSO token
  во frontend, логи и тексты ошибок.
- Не логируй медицинские данные целиком.
- Не ослабляй TLS и существующую авторизацию.
- Не меняй несвязанный код и зависимости без необходимости.

5. Тесты
- Успешная выдача контекста через GET.
- 401 для неверного или отсутствующего токена.
- 404 для неизвестного encounter_id.
- Успешный PUT с полями и transcript.
- Повторный одинаковый PUT не создаёт дубликат.
- Отсутствующие в PUT поля не очищаются.
- Пустой массив fields сохраняет стенограмму.
- Несовпадающие ID в URL и JSON отклоняются.
- SSO вызывается только сервером и передаёт user_full_name.
- Секреты отсутствуют в клиентском bundle и ответах.

После реализации:
1. Запусти formatter, линтер, целевые тесты и сборку frontend, если он менялся.
2. Исправь введённые тобой ошибки.
3. Покажи список изменённых файлов.
4. Кратко опиши принятые решения и команды проверки.
5. Отдельно перечисли всё, что требует параметров или подтверждения smartica.ai.

#Лучше разбить на несколько запусков

Один большой промпт работает. Минус в том, что ранняя ошибка проходит через всю работу. Потом вы разбираете сотни строк diff.

Надёжнее идти шагами и коммитить после каждого шага. Тогда откат возвращает на один шаг, не на всю работу.

#Шаг 1. Разведка без изменений

Сначала попросите агента ничего не менять и только изучить проект. Ответ показывает, понял ли агент задачу.

Пока ничего не меняй в коде.

Прочитай https://smartica.ai/llms.txt и статьи раздела «Интеграция с МИС»
как Markdown (URL с суффиксом .md).

Затем изучи этот репозиторий и ответь:
1. Где хранятся приёмы и как называется их идентификатор.
2. Где хранятся врачи, их email и ФИО.
3. Где хранится текст протокола и его поля.
4. Как в проекте проверяется доступ врача к приёму.
5. Как устроена авторизация входящих API-запросов.
6. По какому шаблону в проекте пишутся тесты.
7. Куда правильно добавить новый защищённый API-endpoint.

В конце составь план реализации интеграции и перечисли всё,
чего тебе не хватает для начала работы.

Прочитайте ответ. Если агент неверно понял структуру проекта, поправьте агента сейчас, до первой строки кода.

#Шаг 2. Только приём результата

Начните с PUT. PUT — единственный обязательный endpoint.

Реализуй только PUT /api/for-smartica/encounters/{encounter_id}
по контракту из
https://smartica.ai/help/integrations/mis-api-export-encounter.md
и https://smartica.ai/help/integrations/field-types.md

Требования:
- Проверка заголовка Authorization: Bearer, ожидаемый токен
  из SMARTICA_INBOUND_TOKEN, сравнение timing-safe.
- Проверь совпадение ID в URL и в теле, иначе 422.
- Обнови переданные fields по id в одной транзакции.
- Поля, отсутствующие в массиве, не очищай.
- Поля из skipped не записывай и не очищай. skipped[].text не пиши в поле,
  его можно показать врачу подсказкой.
- Сохраняй value тем типом, которым оно пришло. Это строка, число, true, false или массив.
- Не приводи все value к строке.
- Пустой массив fields — валидный запрос, стенограмму всё равно сохрани.
- Замени стенограмму полной версией из transcript.
- Сделай обработку идемпотентной по encounter_id.
- Верни 200 и JSON { "encounter_id": "...", "status": "saved" }.
- Не возвращай 204, пустое тело или HTML.

Напиши тесты, включая повторную отправку одинакового payload
и проверку того, что отсутствующие поля не затираются.

Больше ничего не трогай.

Прогоните тесты. Закоммитьте.

#Шаг 3. Кнопка и вход врача

Реализуй серверный запуск smartica.ai по контракту из
https://smartica.ai/help/integrations/launch-and-sso.md

- Кнопка «smartica.ai» в карточке приёма.
- Браузер передаёт бэкенду только ID приёма.
- Бэкенд проверяет доступ врача к этому приёму.
- Email и ФИО врача берутся из сессии МИС, а не из тела запроса.
- POST на <SSO_ENDPOINT_FROM_SMARTICA> с Bearer из SMARTICA_SSO_KEY.
- Тело: user_email, user_full_name, encounter_id строкой.
- Ответ: редирект на launch_url без изменений.
- Ключ не должен попадать во frontend, логи и тексты ошибок.

Обработай ошибки 401, 403, 422, 429 и 5xx так, как описано в статье:
показывай понятное сообщение и не повторяй запрос автоматически
на 401 и 403.

Напиши тесты. Больше ничего не трогай.

#Шаг 4. Отдача контекста

Этот шаг можно пропустить. Если вы передаёте название бланка и поля в SSO-запросе, GET не нужен. Решите до запуска, нужен ли GET. Смотрите статью Ссылка для входа врача.

Реализуй GET /api/for-smartica/encounters/{encounter_id} по контракту из
https://smartica.ai/help/integrations/mis-api-get-encounter.md

- Та же проверка Bearer-токена, что в PUT.
- Верни 200 JSON: encounter_id, user_email, template, fields[{id,label}].
- encounter_id строкой, совпадает с URL.
- user_email — врач, ведущий этот приём.
- fields[].id уникальны и стабильны.
- fields[].label — заголовок для заполнения smartica.ai. Если подпись
  понятна только вместе с разделом выше, опишите поле целиком.
- Ошибки: подходящий non-2xx и безопасный JSON message
  без стектрейсов и SQL.

Напиши тесты на успешный ответ, 401 и 404. Больше ничего не трогай.

#Как разговаривать с агентом

Для тех, кто запускает агента впервые.

#Отвечайте на вопросы агента

В промпте есть указание остановиться и спросить, если данных не хватает. Если агент спрашивает «где хранится текст протокола?», ответьте конкретно. Не отвечайте «разберись сам». Каждый точный ответ убирает группу будущих ошибок.

#Не принимайте изменения не глядя

В Cursor каждое изменение показывается как diff. Пролистайте diff. Вы не обязаны понимать каждую строку. Замечайте подозрительное: правки в файлах не по задаче, удаление существующего кода, новые зависимости.

#Полезные фразы

#Если агент пошёл не туда

Не пытайтесь исправить всё в диалоге. Так редко выходит. Сделайте так:

1. Откатите изменения командой git checkout .
2. Поймите, чего не хватало в постановке.
3. Сузьте задачу. Попросите сделать только одну вещь.
4. Запустите заново с уточнённым промптом.

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

#Если агент «зациклился»

Признак такой. Агент раз за разом правит одно и то же место. Тесты падают. Объяснения повторяются. Остановите агента и попросите:

Остановись и не меняй код.

Опиши: какую ошибку ты видишь, какие три гипотезы у тебя есть
и как проверить каждую. Не предлагай исправление, пока не
подтвердишь гипотезу фактами из кода или из вывода теста.

#Типичные ошибки ИИ в этой интеграции

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

Если агент неправильно понял требование, агент пишет тест на неверное поведение. Тест при этом проходит. Зелёные тесты не означают, что контракт соблюдён.

#Проверка результата

#Автоматически

Проверь свою реализацию по чеклисту и честно отметь, что не выполнено.
Не исправляй ничего, пока я не подтвержу.

1. Секреты читаются из окружения, в коде их нет.
2. Ключ клиники отсутствует в клиентском бандле.
3. Email и ФИО врача берутся из сессии МИС.
4. Доступ врача к приёму реально проверяется.
5. encounter_id передаётся строкой.
6. launch_url не собирается вручную и не логируется.
7. PUT идемпотентен по encounter_id.
8. Отсутствующие в PUT поля не очищаются.
9. Пустой массив fields сохраняет стенограмму.
10. Успешные ответы — 200 с JSON, не 204 и не HTML.
11. Тексты ошибок не содержат стектрейсов, SQL и секретов.
12. Стенограммы не попадают в логи целиком.

Для каждого пункта укажи файл и строку, где это обеспечено.
Если пункт не выполнен — так и напиши.

Требование указывать файл и строку не снимайте. Без файла и строки агент отвечает «всё выполнено» по всем пунктам.

#Руками

Автоматической проверки недостаточно. Пройдите этот список сами:

• Секреты читаются из окружения, а не зашиты в коде
• SSO вызывается с сервера, ключа нет в клиентском бандле
• Email и ФИО врача берутся из сессии, а не из тела запроса браузера
• Проверка доступа врача к приёму действительно выполняется
• Повторный PUT не создаёт дубликат. Проверьте курлом, не тестом агента
• PUT с частичным набором полей не затирает остальные
• PUT с пустым fields сохраняет стенограмму
• Миграции корректны и обратимы
• В логи не попадают стенограммы и ссылки для входа
• Не появились лишние зависимости
• Изменения не задели несвязанный код

Проверку идемпотентности делайте именно курлом:

curl --fail-with-body --silent --show-error \
  --request PUT \
  --user 'LOGIN:PASSWORD' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
    "encounter_id": "12345",
    "fields": [{ "id": "complaints", "value": "Тестовые жалобы" }],
    "transcript": "Тестовая стенограмма..."
  }' \
  'https://mis.example.ru/api/for-smartica/encounters/12345'

Выполните дважды и убедитесь, что в МИС остался один приём.

#Живой прогон

ИИ не заменяет приёмочный прогон из статьи Подключение. Проведите тестовый приём. Нажмите кнопку, запишите короткий разговор, дождитесь результата и откройте карту.

#Дополнительные промпты

#Ревью чужой или своей реализации

Проведи ревью интеграции со smartica.ai в этом репозитории.

Сверься с контрактом:
- https://smartica.ai/help/integrations/mis-api-export-encounter.md
- https://smartica.ai/help/integrations/field-types.md
- https://smartica.ai/help/integrations/value-sets.md
- https://smartica.ai/help/integrations/launch-and-sso.md
- https://smartica.ai/help/integrations/authentication-and-errors.md
- https://smartica.ai/help/integrations/limits.md

Ищи в первую очередь:
- секреты в клиентском коде, логах и текстах ошибок;
- неидемпотентный PUT;
- очистку полей, отсутствующих в payload;
- encounter_id, переданный числом;
- ручную сборку launch_url;
- ответы 204, пустые тела и HTML;
- email врача, принятый от браузера без проверки.

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

#Разбор ошибки от smartica.ai

При запросе к smartica.ai приходит такая ошибка:

<ВСТАВЬТЕ КОД ОТВЕТА И ТЕЛО, БЕЗ СЕКРЕТОВ>

Найди причину. Сверься с
https://smartica.ai/help/integrations/troubleshooting.md
и с нашим кодом.

Сначала объясни причину, потом предложи исправление.
Не меняй код, пока я не подтвержу.

#Дописать тесты

Проверь, что тесты интеграции покрывают все эти случаи,
и допиши недостающие:

- успешный GET контекста;
- 401 при неверных credentials;
- 404 для неизвестного encounter_id;
- успешный PUT с полями и стенограммой;
- повторный одинаковый PUT не создаёт дубликат;
- PUT с пустым массивом fields сохраняет стенограмму;
- PUT с частичным набором полей не затирает остальные;
- несовпадение ID в URL и теле даёт 422;
- SSO вызывается только с сервера и передаёт user_full_name.

Не меняй продакшн-код: только тесты. Если тест выявит
реальный баг — сообщи о нём, но не исправляй сам.

#Если ИИ-агента нет

Интеграция небольшая. Идите по статье Первый приём. Там пошаговая инструкция и пример кода для любого стека.

#Связанные статьи

• Обзор
• Первый приём
• Подключение
• Лимиты
• Если запросы не проходят