# Проработанные примеры Три домена, одна форма. Каждый пример показывает, что агент обязан выдать до ответа — карточку задачи и карточку домена, — а затем сжатый ответ с метками и строкой ворот. Ссылки на модули ведут в `PROMPT.ru.md`. ## Пример A — легаси-панель на PHP **Запрос (сокращённо).** «В панели нет даты окончания оплаты у хостингов. Добавь.» ```text КАРТОЧКА ЗАДАЧИ Тема: самостоятельная панель на PHP для аккаунта регистратора Результат: дата окончания в таблице услуг и в ответе эндпоинта списка Адресат: два оператора, работающие в панели ежедневно Успех значит: колонка показывает дату для 100% строк, где она есть в базе Ограничения: PHP 8.x, без новых зависимостей, прежние тесты остаются зелёными Неизвестно: лежит ли «окончание» в таблице услуг или вычисляется Вне рамок: редизайн таблицы, сортировка, экспорт КАРТОЧКА ДОМЕНА Практик: backend-инженер, ведущий внутреннюю админ-панель Словарь: миграция, эндпоинт, presenter, scope, идемпотентная синхронизация Набор навыков: чтение схемы; поток запроса; рендеринг шаблона; гигиена тестов Проверить: настоящее имя колонки; её допустимость NULL; кешируется ли эндпоинт Источники истины: миграции, схема живой таблицы, исходник эндпоинта Типичный провал: SQL по запомненным именам колонок Готово, когда: эндпоинт отдаёт «expires_at», таблица его рисует, прежние тесты зелёные Анти-паттерны: SELECT *; форматирование даты в шаблоне; миграция без пути отката ``` Ответ, сжато: ```text ## Ответ Добавить «expires_at» в эндпоинт услуг и вывести ISO-датой в колонку. [факт] в `accounts` есть `paid_till` (DATE, nullable) — migrations/2026_03_accounts.sql:14 [факт] эндпоинт списка выбирает явный список колонок — src/Http/Accounts.php:61 [вывод] `paid_till` — это и есть «окончание», других дат в таблице нет [предположение] строки с NULL показывать как «—»; если неверно — меняется только вид, не запрос ## Свидетельства - имя колонки и допустимость NULL — migrations/2026_03_accounts.sql:14 - явный список колонок — src/Http/Accounts.php:61 - тест, покрывающий эндпоинт — tests/AccountsTest.php:88 ## Предположения - NULL значит «срок не задан» — последствие: у старых строк в колонке «—» ## Открытые вопросы - кешируется ли панель по сессии; если да, дата может отставать на один запрос ## Следующий шаг php tools/lint.php && php backend/tests/run.php # ожидается: 0 провалов ворота 12/12 ``` ## Пример B — служба Windows с конфигуратором WinForms **Запрос (сокращённо).** «Добавь кнопку аудита безопасности на странице MikroTik.» ```text КАРТОЧКА ЗАДАЧИ Тема: служба Windows плюс конфигуратор WinForms для сетевых устройств Результат: кнопка, запрашивающая аудит по IPC и показывающая отчёт Адресат: сетевые администраторы, работающие в конфигураторе Успех значит: отчёт отрисован, служба здорова, контрактный тест IPC обновлён Ограничения: идентификаторы команд IPC только дописываются; формат на проводе не ломаем Неизвестно: существует ли подходящая команда IPC Вне рамок: исправление находок, расписание, форматы экспорта КАРТОЧКА ДОМЕНА Практик: старший .NET-инженер, владеющий службой и её интерфейсом Словарь: реестр команд IPC, таймаут длинной операции, DTO, экспорт грида, учётка службы Набор навыков: дисциплина контракта IPC; асинхронность в UI; гигиена тестов; семантика логов Проверить: следующий свободный id команды; есть ли реестр таймаутов; требуется ли привязка грида к помощнику экспорта Источники истины: перечисление IPC, диспетчер, тест, считающий асинхронные обработчики Типичный провал: коллизия id или длинная команда без таймаута Готово, когда: id уникален и задокументирован, таймаут зарегистрирован, тест экспорта проходит, служба перезапускается чисто Анти-паттерны: вызов службы из UI-потока; считать строку лога доказательством здоровья ``` Ответ, сжато: ```text ## Ответ Добавить команду IPC 95 «GetSecurityAudit» (только дописывание), зарегистрировать её как длинную операцию и провести кнопку через существующую обёртку асинхронных обработчиков. [факт] максимальный занятый id — 94 — Service/Ipc/IpcCommand.cs:31 [факт] длинные операции перечислены в реестре с тестом — Service/Ipc/IpcConstants.cs:12 [факт] все асинхронные обработчики UI идут через SafeAsyncHandler — Configurator/Pages/MikroTikPage.cs:204 [вывод] аудит может занимать до 45 с, значит это длинная операция [предположение] команды аудита ещё нет; если есть — переиспользовать её вместо 95 ## Свидетельства - потолок id команд — Service/Ipc/IpcCommand.cs:31 - реестр таймаутов — Service/Ipc/IpcConstants.cs:12 - политика асинхронных обработчиков — Configurator/Pages/MikroTikPage.cs:204 ## Предположения - аудит — новая возможность — последствие: ещё одна команда в документации и тестах ## Открытые вопросы - отличается ли учётка службы от учётки конфигуратора; возможно, хватит read-only ## Следующий шаг dotnet test RdpAudit.sln -c Release --no-build -p:Platform=x64 # ожидается: всё зелёное ворота 12/12 ``` ## Пример C — документация как продукт **Запрос (сокращённо).** «Наша вики нечитаема; сделай из неё настоящую документацию.» ```text КАРТОЧКА ЗАДАЧИ Тема: документационная поверхность одного GitHub-репозитория Результат: вики с навигацией, разрешающимися ссылками и журналом, который разбирается Адресат: операторы, которые уже нашли репозиторий Успех значит: каждая страница достижима из навигации, каждая ссылка разрешается, сирот нет Ограничения: плоское пространство вики; без относительных картинок; английский основной, русский перевод Неизвестно: существует ли вики-репозиторий на сервере Вне рамок: маркетинговый сайт, SEO, статьи в блог КАРТОЧКА ДОМЕНА Практик: инженер документации для инструментов разработчика Словарь: якорь, плоское пространство, сайдбар, футер, ссылка сравнения, каноническая страница Набор навыков: правила рендеринга markdown; вычисление якорей; семантика журнала; разрешение ссылок Проверить: ограничения платформы на изображения; алгоритм якорей; адресуется ли страница вики без расширения Источники истины: документация GitHub, отрисованное оглавление, стандарт журнала изменений Типичный провал: зелёная проверка ссылок, ни разу не разрешившая якорь Готово, когда: сборка и проверка чистые, сухой прогон публикации просмотрен, навигация покрывает все страницы, оба языковых набора на месте Анти-паттерны: оглавление руками; удаление чужих страниц «для порядка» ``` Ответ, сжато: ```text ## Ответ Восемь канонических страниц плюс восемь переводов, порядок задаёт манифест; внутренние ссылки теряют «.md»; футер несёт только абсолютные ссылки. [факт] страница вики адресуется без расширения — замерено на живом сайдбаре [факт] относительная картинка не работает: вики — отдельный репозиторий — документация GitHub [факт] платформа принимает PNG/JPG/GIF до 1 МБ для соцпревью — документация GitHub [вывод] существующие 12 страниц недостижимы, потому что сайдбар перечисляет 6 [предположение] вики-репозитория ещё нет; если есть — публиковать сразу, шаг первой страницы не нужен ## Свидетельства - механика вики — документация GitHub, «About wikis» - правила якорей и случай с тире — документация плюс живое оглавление - ограничения изображений — «Customizing your repository's social media preview» ## Предположения - первая публикация требует одной страницы, сохранённой в интерфейсе — последствие: один шаг руками ## Открытые вопросы - нужна ли индексация командой; для этого нужен GitHub Pages, а не вики ## Следующий шаг python /tools/ghagent.py wiki build && ... wiki verify # ожидается: 0 ошибок ворота 12/12 ``` ## Что общего у трёх примеров | Элемент | Зачем он | |---|---| | Объявленная тема одной фразой | предотвращает дрейф домена (M2) | | Три-пять фактов «проверить» | отличает специалиста от уверенного дилетанта | | Одно условие приёмки, проверяемое ревьюером | делает «готово» опровержимым | | Одно помеченное предположение с последствием | честность без паралича | | Одно следующее действие с ожидаемым результатом | делает ответ выполнимым | | Строка ворот | делает ответ аудируемым (M8) | Ни один из трёх примеров не потребовал правки промпта. Это и есть заявка набора: новый домен стоит одну карточку, одну запись в примерах и одну строку приёмки (M10).