public/skills
3
0
Fork 0
Code Pull Requests Actions Activity
Files
master
skills/backend-integration-guide/SKILL.md

8.3 KiB
Raw Permalink Blame History

name, description, license, metadata
name description license metadata
backend-integration-guide Generate a concise backend integration guide from a git commit, range, or branch (defaults to the latest commit when none is given). Use when the user asks for integration instructions for backend/CMS developers. Outputs a Russian plain-text guide in chat. MIT
author version
Valentin Silyutin 1.0.0

Backend Integration Guide Generation Instructions

Analyze the changes of a git commit (or range/branch; with no input, the latest commit) and produce a short Russian guide for the backend/CMS developer, describing what changed in the markup and data that matters to them.

Output Rules

  • Language: the whole guide is written in Russian. Only code, paths, selectors, commands and API identifiers stay as-is.
  • Plain text, no markup: print the guide as plain text without any Markdown formatting — no # headings, no **bold**, no backtick fences. Section titles are plain lines, list items start with - , JSON is shown with indentation. The output is pasted into a Planfix visual editor that does not parse Markdown or HTML.
  • Plain human Russian: write simple, natural sentences. Describe the action in words, not with arrows or jargon. Say «в блок .catalog-list добавить класс .catalog-list_category», not «.catalog-list → .catalog-list_category». Avoid канцелярит («точки монтирования», «статичная разметка»): use «компоненты», «разметка фильтра» и т. п.
  • Do not list nested content. If a block is added or removed as a whole, its inner elements and nested blocks are obvious — do not enumerate them.
  • Destination: print the guide in the chat only. Do not create or modify any files.
  • Concise: one line per meaningful change. Do not retell the diff.
  • Report changes only: never write about what stayed the same — unchanged pages, sections, assets or fields are simply not mentioned.
  • Never invent: only mention classes, fields, requests, assets and variables that actually appear in the analyzed changes. If something is absent, do not mention it.

1. Determine the Range

Resolve the input into a BASE and TARGET revision:

  • No argument: BASE=HEAD^, TARGET=HEAD (the latest commit).
  • Single hash <hash>: BASE=<hash>^, TARGET=<hash>.
  • Range <from>..<to>: BASE=<from>, TARGET=<to>.
  • Branch <branch> (including origin/<branch>): BASE=$(git merge-base HEAD <branch>), TARGET=<branch>.

Get the task number and title from the commit subject (format #<номер задачи> <описание>):

git log -1 --format=%s <TARGET>

2. What Changed

Only src/** and html/** carry integration-relevant changes. Ignore:

  • www/** — the build output, not tracked in git; never treat it as the markup source (that is html/**).
  • *_index.scss, *_index.js, src/scripts/mocks/handlers/_index.js.
  • The preview sitemap page listing links to all preview pages ("Карта сайта"), if the project has one; it is not part of the CMS integration. Do not confuse it with a regular index page.
  • Formatting-only changes with no semantic difference.

Detect each category independently:

HTML markup — source of truth is html/**, NOT src/templates/**

The folder html/ contains the built HTML used precisely to see markup changes. src/templates/** (Nunjucks) may change while the resulting HTML stays the same.

Use whitespace-insensitive diff to drop indentation noise:

git diff -w --ignore-blank-lines BASE TARGET -- html/
  • If html/** has real changes → list them per page under «Изменения по HTML».
  • Otherwise → omit the markup section entirely.

When describing a changed HTML page (any html/**/*.html, including fragments such as header/, footer/, layout/):

  • new / changed / removed blocks and elements — by BEM class, as a plain sentence;
  • new states (modifiers), new target pages;
  • ignore plain URL values (href, data-infinite, data-request, etc.): the backend uses its own addresses, so do not report them.

Initial page state — src/json/** and template globals

Data that must already be on the page at load time — a global object emitted by a template and read by JS (window.*, STATE_*, etc.).

src/json/** files are fixtures: at build time they only become Nunjucks variables used to generate HTML. If such data is used only to render HTML in Nunjucks, do not report it.

Report data only when it reaches the JS/Vue layer, because that is the backend contract:

  • a global object emitted by a template and read by JS (window.*, STATE_*, etc.);
  • a direct import of JSON into the code.

Search for such globals directly in the templates (e.g. STATE_FILTER in _catalog.njk), even when src/json/** did not change.

Show the expected structure as a raw JSON example, not as a prose field list.

AJAX requests — src/scripts/**

Only report a change here when the data exchange contract with the backend changed. Determine that contract from whatever the project uses, and show its structure as a raw JSON example:

  • a shared request helper (src/scripts/utils/request.js or a similarly named module) — reference it and list its response formats;

  • mocks (src/scripts/mocks/**) — use them as the request/response contract, but note that they are dev-only (never loaded in production, see src/scripts/main.js) and do not require a JS rebuild;

  • an explicit fetch/axios call.

  • Do not describe internal JS logic, refactors, stores, components or composables — the backend only needs to know whether JS changed (see «Пересобрать JS» in the build list).

  • Do not report URLs, HTTP methods or header values — the backend sets them. At most, mention that the update is an AJAX request and that extra headers can be passed if such an option exists.

Assets — src/images/**, src/fonts/**, src/videos/**

  • new icons in src/images/required/icons/** (SVG sprite);
  • new design images in src/images/required/**, content images in src/images/examples/**, fonts and videos — list the new files;
  • lazy-loading requirements (loading="lazy", .lazyload + data-background).

3. Build List

Derive the build list from which source folders changed. Emit only relevant items, as a plain list (no todo checkboxes):

  • src/styles/** *.scss changed → Пересобрать CSS
  • src/scripts/** *.js/*.vue changed excluding src/scripts/mocks/** → Пересобрать JS
  • src/images/required/icons/** changed → Пересобрать иконки

The backend rebuilds assets with yarn build and copies the result to their side.

4. Output Template

Plain-text layout, no Markdown. No title line; the guide starts with the first section.

Сборка
- Пересобрать CSS
- Пересобрать JS
- Пересобрать иконки

Изменения по HTML
catalog.html
- <что изменилось: блоки, классы, структура>

Данные при загрузке страницы
<JSON-пример структуры>

AJAX-запросы
<JSON-пример контракта ответа, если он изменился>

Ассеты
- <новые иконки / изображения / шрифты / видео>
  • Emit a section only if it has content; sections without changes are omitted entirely (including «Ассеты», when there are no new files).
  • If no integration is needed at all (only internal refactor works with no markup/data change), output a single line: Интеграция не требуется — <короткая причина>.

5. Workflow

  1. Parse the input (hash / range / branch; if nothing is given — the latest commit, BASE=HEAD^, TARGET=HEAD) and resolve BASE and TARGET.
  2. Read the commit subject for the task number and title.
  3. If project conventions are unclear (request helper path, the sitemap page, subfolders in html/), consult AGENTS.md / README.md — every project has them.
  4. Run the whitespace-insensitive diff for html/** and the diff for src/**.
  5. Categorize the changes into: HTML, initial page state, AJAX requests contract, assets, build steps.
  6. Print the Russian plain-text guide in chat using the template above.