--- name: n-llm-patch description: >- Підготовка самодостатнього текстового промпта для іншого Claude/Cursor-агента — read-only аналіз CWD без жодних змін у поточному репо version: '1.0' --- # Підготовка LLM-патчу (текстова комунікація між агентами) Скіл готує **самодостатній текстовий промпт** ("патч") для іншої LLM-сесії (Claude / Cursor agent у цільовому проєкті). Користувач копіює готовий блок з відповіді чату й вставляє його в розмову з іншим агентом — той виконує запитані зміни вже у своєму середовищі. ## Принципи - **Read-only:** скіл нічого не пише в поточне репо. Лише читає CWD. - **Тимчасові артефакти — лише в `/tmp`** (наприклад, `tree`-вивід чи проміжні чернетки промпту); ніколи не у CWD. - **Цільова LLM:** Claude / Cursor agent — припускаємо, що читач знається на XML-тегах, file refs (`path/to/file.ts:42`), markdown. - **Один блок виводу:** результат — це **один** markdown-блок у відповіді чату, готовий до копіювання. - **Лаконічність — головне:** промпт містить **інтент + покажчики**, а не цитати + готовий код. Цільова LLM має повний доступ до свого CWD через `Read`/`Grep`/`Glob` і прочитає актуальний стан сама — наш патч не повинен дублювати те, до чого вона додумається з 2-3 файлів. ## Що **не** включати у промпт (cut list) Цільова LLM сама прочитає файли — не дублюй їх. Викидай: - **Великі цитати коду** з файлів, які LLM знайде за file ref. Замість блоку з 30 рядками функції — один рядок: `див. rules/foo/bar.mjs:120-150 (collect)`. Цитуй **тільки**: вже видалений код (тобто LLM його не знайде), або фрагмент з зовнішнього джерела (логи, stderr, помилка з CI). - **Готові імплементації** ("ось як має виглядати новий `defaultRunner`") з повним кодом. Опиши інтент і обмеження — LLM напише код сама й краще під поточний стиль файлу. Виняток: один-два рядки, які важко описати словами (наприклад, точна назва прапора CLI). - **Покрокові підказки рівня "крок 1: import X, крок 2: split into a) і b)…"** з псевдо-кодом. Це передчасна архітектура — описуй **бажану поведінку** (input → output, edge cases), а декомпозицію довір LLM. - **Повний вміст `package.json`, конфігів, helpers** — досить імені поля та значення, що змінюється: `engines.node: ">=22" → ">=25"`. Якщо значення специфічне (peer ranges, exports map) — цитуй **тільки цей фрагмент**. - **Огляд альтернатив, які ти відкинув,** із розгорнутими аргументами. Один рядок: "розглянутий варіант X відкинуто — Y" або взагалі прибрати, якщо LLM сама дійде того самого висновку. - **Списки існуючих helpers ("вже є addCoverage у rules/test/coverage")** — досить рядка-покажчика; LLM зайде `Grep`'ом і прочитає сигнатуру сама. - **Дублювання правил репо** (`CLAUDE.md`, `.cursor/rules/*.mdc`) — досить згадки "дотриматись n-test.mdc"; LLM прочитає файл сама. - **Готовий `tree -L 2`-дамп** — досить рядка "монорепо з workspaces cf/_, run/_, gt (bun)"; повна структура майже завжди шум. - **Самоочевидні acceptance-checks** ("тести зелені", "лінтер чистий") — пиши тільки специфічні до завдання ("на репо `ai`: `bun run coverage` не падає з `JS coverage exit 1`"). ## Що **обов'язково** включити - **Інтент** — 1-3 речення, що саме треба і чому (1 речення на причину). - **Симптом / репро,** якщо це bugfix: справжній stderr, точна команда, exit code. Це **не** виводиться з коду — без нього LLM не знає, що саме ламається. - **File refs** на ключові точки правки: `path:line` або `path:line-range`, з одним рядком пояснення кожна. - **Реальні обмеження,** які не виводяться з коду: версії в репо-споживачі, inflight-міграції, breaking-change політика, зовнішні залежності. - **Change-file flow,** якщо завдання змінює файли у пакетному workspace (код, правила, скіли, конфіги, тести — не лише `docs/`): промпт має вимагати `npx @7n/n ch [--bump ] [--section ] [--message "<опис>"]` і `npx @7n/rules lint changelog`. **Ніколи** не інструктуй ручне редагування `CHANGELOG.md` чи bump `version` — це робить release flow / CI (деталь — `.cursor/rules/n-changelog.mdc`, не дублюй її текст). Якщо потрібна реліз-нота — це change-файл `/.changes/-.md` з `bump:` і `section:`, який створює `@7n/n ch`, а не редагування файлу вручну. - **Як перевірити** — конкретні команди й специфічні до завдання сигнали успіху. ## Виклик ``` /n-llm-patch <вільний опис завдання> ``` Аргумент має містити: **що треба зробити**, опційно — **назву пакета / підмодуля** для контексту. Якщо аргумент порожній — попроси користувача сформулювати завдання, не вгадуй. Приклад: ``` /n-llm-patch підготуй для проекту @nitra/eslint-config щоб він врахував останню версію node ``` ## Workflow 1. **Розпарсити аргумент** — виокремити суть завдання та (якщо є) назву пакета / шлях. Аргумент = намір користувача, передається у промпт як розділ "Завдання". 2. **Зібрати read-only контекст з CWD — мінімум, потрібний для опису інтенту й покажчиків:** - `package.json` — лише поля, релевантні до завдання (напр., для "node" — `engines`, `name`, `version`; для "eslint" — `peerDependencies`, `exports`). Не читай поля, які потім не з'являться у промпті. - Структура репо — швидкий огляд (`ls` верхнього рівня), щоб згадати **тип** ("монорепо bun з 7 workspaces" — рядком, не дампом). - **Релевантні файли** — відкривай саме ті, що потрібні щоб знайти `file:line` покажчики на точки правки. Не читай "про запас". - `CLAUDE.md` / `.cursor/rules/*.mdc` — лише **перевір наявність** і назви файлів-правил, які стосуються завдання (LLM прочитає сама). 3. **Визначити "точку патчу"** — 1-5 `path:line` покажчиків на місця, які найімовірніше треба правити, з одним рядком пояснення на кожен. 4. **Сформувати промпт за шаблоном нижче.** Цитуй код **тільки** коли він зовнішній (stderr, лог CI) або уже видалений. Існуючий код у CWD не цитуй — давай `path:line` ref. 5. **Прорахуй cut list:** перед видачею пройдись по секції "Що **не** включати" вище і видали все, що цільова LLM може отримати з 2-3 `Read`/`Grep`-викликів у своєму CWD. 6. **Вивести один markdown-блок у чат** — без додаткових коментарів поза блоком, окрім однорядкового підпису "готово до копіювання". ## Шаблон вихідного промпта Тільки секції, які несуть навантаження. Порожніх не залишай. Зразок: ````markdown ```markdown # Завдання <1-3 речення: що треба і яка причина (баг / новий стек / requirement). Якщо bugfix — вкажи симптом одним рядком.> # Симптом / репро <тільки для bugfix: точна команда + ключовий рядок stderr/exit code. Пропусти секцію, якщо не bugfix.> # Точки правки - `path/to/file.mjs:120` — <одне речення: що тут не так / що зробити> - `path/to/other.mjs:34-50` — <…> # Що треба зробити <бажана поведінка input → output, edge cases, без псевдо-коду й покрокових імплементаційних підказок. 3-8 буллетів.> # Обмеження <тільки реальні, не виводяться з коду: версії у репо-споживачі, breaking-change політика, inflight-міграції. Пропусти секцію, якщо їх нема.> # Як перевірити - `<команда>` — <специфічний до завдання сигнал успіху> ``` ```` ### Контр-приклад (так робити не треба) - Секція `# Контекст проєкту` з name/version/stack/docs — LLM прочитає `package.json` сама за 1 виклик. - `## Структура (skim)` з `tree -L 2` дампом — шум. - `## package.json` з повним JSON — досить рядка про конкретне поле у `Що треба зробити` або `Обмеження`. - `## <функція>` з 30 рядками існуючого коду — давай `path:line` ref у `Точки правки`. - Покрокові підказки з кодом ("крок 1: import X, крок 2: split…") — опиши поведінку, код напише LLM. ## Правила - **Мова промпту:** українська за замовчуванням; якщо аргумент англійською — можна англійською. Технічні терміни — англійською. - **Обсяг:** прагни до **30-100 рядків**. Якщо вийшло більше — пройдись по cut list і викинь усе, до чого LLM додумається з кількох `Read`/`Grep`. Більше 150 рядків — майже завжди ознака, що ти цитуєш код, який LLM прочитає сама. - **Без галюцинацій:** не вигадуй полів `package.json`, версій, шляхів, номерів рядків — лише те, що реально прочитав з CWD. Якщо чогось бракує — явно так і напиши ("`engines.node` відсутнє"). - **Без імперативного тону до користувача:** промпт адресований **іншому агенту**, не людині. Використовуй "зроби", "онови", "додай". - **Без секцій-пустушок:** якщо немає `Обмежень` чи `Симптому` — пропусти секцію цілком. - **Без ручного changelog/version у промпті:** не формулюй у виводі інструкції на кшталт "додати запис у `CHANGELOG.md`", "bump `version` вручну" чи "оновити `package.json#version`". Зміни у workspace фіксуються винятково через change-file flow (`npx @7n/n ch` → `npx @7n/rules lint changelog`); `version`/`CHANGELOG.md` формує CI. - **Не вмикай у промпт:** секрети, `.env`, `node_modules`, бінарні файли, довгі логи, дампи `tree`, повні JSON конфігів, цитати існуючих helpers/функцій з CWD. - **Усе в одному блоці:** результат — це **один** ` ```markdown ` блок; ніяких додаткових міркувань поза ним (крім фінального підпису "готово до копіювання"). ## Що скіл **не** робить - Не завантажує tarball з npm registry, не клонує git-репозиторії. - Не редагує жоден файл у поточному проєкті (і поза ним). - Не виконує сам "патч" — лише готує промпт для іншого агента. - Не оптимізує під Gemini / GPT — лише Claude / Cursor agent. ## Приклад виклику й результату Виклик: ``` /n-llm-patch у @nitra/eslint-config підняти engines.node до >=25 ``` Очікуваний вивід: ````markdown ```markdown # Завдання Підняти `engines.node` у `@nitra/eslint-config` з `>=22` до `>=25`, переконатися що peer `eslint ^9` сумісний з Node 25. # Точки правки - `package.json:18` — `engines.node` # Що треба зробити - Підняти `engines.node` до `>=25`; якщо peer `eslint ^9` несумісний — підняти range. - Зафіксувати зміну change-файлом (НЕ редагувати `CHANGELOG.md` чи `version` вручну): `npx @7n/n ch --bump minor --section Changed --message "engines.node >=25"`. # Обмеження - Дотриматись `.cursor/rules/n-js.mdc` і `.cursor/rules/n-changelog.mdc` (зміни у workspace = change-файл, не ручний CHANGELOG/version bump). - Якщо `eslint ^9` офіційно не підтримує Node 25 — підняти peer range. # Як перевірити - `bun run test` — зелений - `node -p "require('./package.json').engines.node"` → `>=25` - `npx @7n/rules lint changelog` → exit `0` ``` ```` ``` готово до копіювання — встав у чат з агентом у цільовому проєкті ```