backend-integration-guide@1.0.0
This commit is contained in:
145
backend-integration-guide/SKILL.md
Normal file
145
backend-integration-guide/SKILL.md
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: backend-integration-guide
|
||||
description: 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.
|
||||
license: MIT
|
||||
metadata:
|
||||
author: Valentin Silyutin
|
||||
version: "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.
|
||||
Reference in New Issue
Block a user