Настанова для агента
Workflow агента
- Завантажити цю сторінку — отримати повну інструкцію з
https://snakeflow.pages.dev/uk/getting-started/skill-agent-guide/2. Дослідити проєкт — просканувати всі релевантні файли (Phase 1) 3. Підсумувати знахідки — повідомити користувача про виявлене в 5–10 реченнях 4. Задати 50 питань — згруповано, з автовизначеними значеннями за замовчуванням (Phase 2) 5. Записати.vscode/settings.json— тільки після збору всіх відповідей (Phase 3)
Phase 1 — Глибоке дослідження проєкту
Перед питаннями просканувати ці файли та директорії:
Package Manager (з lockfile або package.json)
| Файл | Менеджер |
|---|---|
pnpm-lock.yaml | pnpm |
bun.lockb / bun.lock | bun |
yarn.lock | yarn |
package-lock.json | npm |
package.json → поле "packageManager" | перевизначення |
Стек і мова програмування
| Файл | Стек |
|---|---|
package.json | Node.js |
go.mod | Go |
Cargo.toml | Rust |
composer.json | PHP |
Gemfile | Ruby |
pyproject.toml / requirements.txt | Python |
pubspec.yaml | Dart/Flutter |
mix.exs | Elixir |
build.gradle / pom.xml | Java/Kotlin |
Package.swift | Swift |
*.csproj / *.fsproj | .NET |
Монорепо
| Файл / Ознака | Тип |
|---|---|
pnpm-workspace.yaml | pnpm workspaces |
turbo.json | Turborepo |
nx.json | Nx |
lerna.json | Lerna |
rush.json | Rush |
package.json → масив "workspaces" | npm/yarn workspaces |
→ Перелічити всі apps/packages з workspaces, пайплайнів turbo.json, або apps/*/package.json.
Docker Compose
Шукати compose-файли в: root, docker/, infra/, .docker/, deploy/
| Назва файлу |
|---|
docker-compose.yaml |
docker-compose.yml |
compose.yaml |
compose.yml |
ORM / База даних
| Ознака | ORM |
|---|---|
prisma/schema.prisma або @prisma/client в deps | Prisma |
drizzle-orm в deps | Drizzle |
typeorm в deps | TypeORM |
knex в deps | Knex |
settings.py (Django) | Django ORM |
alembic.ini | SQLAlchemy / Alembic |
директорія db/migrate/ | ActiveRecord (Rails) |
go.mod + entgo.io/ent в deps | ent ORM |
Cargo.toml + diesel в deps | Diesel |
aerich в Python deps | Tortoise ORM |
.csproj + Microsoft.EntityFrameworkCore | EF Core |
Скрипти
Читати package.json → scripts, Makefile, Cargo.toml, pyproject.toml.
Визначити: dev, start, build, lint, typecheck, test, format, check, migrate, generate.
Структура проєкту
Перелічити директорії верхнього рівня. Відзначити наявність:
components/абоsrc/components/— UI-компонентиhooks/абоsrc/hooks/— React hooksservices/,controllers/,repositories/,models/,dto/,entities/api/,server/,routes/,handlers/stores/,utils/,lib/,helpers/apps/,packages/— workspaces монорепо
Тестовий фреймворк
| Файли / Залежності | Фреймворк |
|---|---|
*.test.ts, *.spec.ts, jest.config.* | Jest |
vitest.config.* | Vitest |
pytest в deps | pytest |
файли _test.go | Go test |
*_test.rs / Cargo.toml | Rust test |
Інструменти безпеки
| Ознака | Інструмент |
|---|---|
eslint-plugin-security в devDeps | ESLint Security доступний |
.semgrepignore або semgrep в PATH | Semgrep доступний |
trivy в PATH | Trivy доступний |
bandit в PATH | Bandit доступний |
Dockerfile або Dockerfile.* | Hadolint застосовний |
файли .sh / .bash | ShellCheck застосовний |
Стек схеми бази даних
| Ознака | Стек |
|---|---|
prisma / @prisma/client в deps, або будь-який .prisma файл | Prisma |
drizzle-orm в deps | Drizzle ORM |
db/schema.rb + Gemfile з gem 'rails' | Rails / ActiveRecord |
composer.json з laravel/framework або illuminate/database | Laravel |
ключове слово django в requirements.txt / pyproject.toml / Pipfile | Django |
.py файл з імпортом sqlalchemy / declarative_base / DeclarativeBase | SQLAlchemy |
*.csproj що містить EntityFrameworkCore | EF Core |
go.mod з gorm.io/gorm, entgo.io/ent, go-gorm або xorm | Go (GORM / ent / xorm) |
будь-який .sql файл у дереві проєкту | Сирий SQL |
prisma-lint в devDeps | prisma-lint доступний |
squawk або squawk-cli в deps або PATH | Squawk доступний |
atlas в PATH | Atlas доступний |
CI/CD
.github/workflows/*.yml→ GitHub Actions є в проєкті
Сканування дублікатів компонентів
Просканувати .tsx, .jsx, .vue, .svelte файли. Шукати експорти, що збігаються з: Button, Modal, Dialog, Table, Card, Input, Form, Select, Dropdown, List, Tab, Badge, Avatar, Tooltip, Loader/Spinner, Header/Navbar, Sidebar, Chart, Icon, Pagination.
Підрахувати входження. Якщо ≥ 2 схожих назв компонентів — повідомити як потенційне дублювання.
Phase 2 — 50 питань
Презентувати питання групами. Використовувати (визначено: X) для показу автовизначених значень. Не починати запис налаштувань до отримання відповідей на всі групи.
Група A — Ідентичність проєкту (Q1–Q6)
Q1. Яка назва проєкту для налаштувань?
(визначено: назва папки)
Q2. Який абсолютний шлях до кореня проєкту?
(визначено: поточна папка workspace)
Q3. Який пакетний менеджер?
auto | npm | pnpm | yarn | bun | none
(визначено з lockfile)
Q4. Це монорепо? Якщо так — перелічити всі apps/packages, що потребують власного dev-сервера.
(визначено: показати знайдені workspaces)
Q5. Які згенеровані або legacy-директорії виключити з перевірок?
Вбудований список вже покриває: node_modules, dist, build, __pycache__, target, vendor, .venv, .next, .nuxt, coverage та 70+ інших.
Додати лише специфічні для проєкту: generated, proto-gen, legacy, fixtures, storybook-static, .output тощо.
Q6. Які конкретні файли виключити з перевірок?
(приклади: src/generated/graphql.ts, \*\*/_.generated.ts, _.vsix)
Група B — Dev-сервери (Q7–Q12)
Q7. Перелічити всі dev-сервери для налаштування.
Для кожного: label, команда, робоча директорія (відносна, або "" для кореня), порт, чи входить у bulk start (startWithAll, за замовчуванням true).
(визначено: показати знайдені скрипти команд для кожного workspace)
Q8. Чи використовує якийсь сервер патерн root proxy?
(кореневий package.json запускає npm run dev --prefix subfolder)
→ Якщо так — для цього сервера встановити path: "", НЕ підпапку.
Q9. Проєкт використовує Inngest?
Команда за замовчуванням: npx inngest-cli@latest dev, порт: 8288. Яка робоча директорія?
Q10. Є фонові workers або обробники черг?
(приклади: Celery worker, Sidekiq, BullMQ — використовувати port: 0 без моніторингу)
Q11. Є інші тривалі процеси для управління?
(приклади: WebSocket-сервер, gRPC-сервер, cron-планувальник)
Для опційних утиліт лише за потреби (Prisma Studio, Storybook, Mailpit) — запис у servers з "startWithAll": false; запуск з меню серверів у status bar, не через Ctrl+Alt+S.
Q12. Git-налаштування — гілка за замовчуванням і захищені гілки (не можна видалити з сайдбара)?
(за замовчуванням: main; захищені: main, master, develop, staging, production)
Група C — Docker та інфраструктура (Q13–Q17)
Q13. Проєкт використовує Docker Compose?
(визначено: показати знайдений шлях до compose-файлу)
Чи compose-файл у нестандартному місці?
Q14. Які дії з контейнерами потрібні?
Стандартний набір: Up, Down, Restart, Status, Logs, Pull Images, Build Images, Down + Volumes (деструктивна).
Щось прибрати або додати?
Q15. Кілька compose-файлів для різних середовищ (dev/staging/prod)?
Q16. Використовується Podman або docker-compose (v1) замість docker compose (v2)?
Q17. Є кастомні інфраструктурні команди поза Docker Compose?
(приклади: kubectl apply, terraform plan, helm upgrade)
Чому немає групи D / Q18–Q21? Ці місця зарезервовані під GitHub і CI, що дублюють CI & CD та GitHub. Нумерація Q17 → Q22 навмисна, щоб існуючі JSON скілів і автоматизація, які посилаються на Q22+, лишалися стабільними.
Група E — Quality Hub: кастомні перевірки (Q22–Q26)
Q22. Які скрипти проєкту запускати як Quality Hub перевірки?
(визначено: показати всі скрипти з package.json, Makefile, Cargo.toml тощо)
(типові: lint, typecheck, build, format:check, test, check)
Дивись документацію Custom Checks для прикладів.
Q23. Є сирі shell-команди для кастомних перевірок?
(приклади: go vet ./..., go test ./..., python -m pytest, cargo clippy -- -D warnings)
Q24. Для кастомних перевірок — тільки код виходу (0 = pass) чи матчинг паттернів виводу?
За замовчуванням: код виходу. Якщо потрібен матчинг: надати successPattern, failPattern, warnPattern.
Q25. Увімкнути Stryker mutation testing? (вимкнено за замовчуванням — дуже повільний)
Тільки для JS/TS проєктів з гарним покриттям юніт-тестами.
Q26. Рівень звіту Quality Hub для AI-чату?
auto (завжди) | onFail (за замовчуванням — тільки при помилках) | manual | never
Кастомний промпт для чату? (необов’язковий текст на початку звіту)
Група F — Quality Hub: архітектурні перевірки (Q27–Q34)
Q27. Є шарові папки в проєкті? (наприклад, ui/, views/, presenters/, api/, components/)
Межі шарів забезпечує CLI-перевірка dependency-cruiser — задекларуйте заборонені напрямки імпортів у .dependency-cruiser.cjs.
Дивись dependency-cruiser.
Q28. Які паттерни іменування UI-компонентів є в проєкті?
(визначено: показати знайдені дублікати)
Вбудовані паттерни вже відстежують: Button, Modal, Dialog, Table, Card, Input, Form, Select, Dropdown, List, Tab, Badge, Avatar, Tooltip, Loader/Spinner, Notification/Toast/Alert, Header/Navbar, Sidebar/Drawer, Chart, Icon, Pagination, Stepper.
Є специфічні для проєкту паттерни? (наприклад, Panel, Widget, Section, Tile)
Дивись перевірку Component Inventory.
Q29. Мінімальна кількість схожих компонентів для попередження?
(за замовчуванням: 2 для UI-компонентів; 3 для hooks типу useFetch)
Перевизначити порогове значення? (наприклад, “попереджати тільки при 4+ варіантах Button”)
Q30. Є кастомні hook-паттерни що мають попереджати при дублюванні?
Вбудовані: useAuth, useFetch/useQuery/useApi, useForm, useModal, useFilter, useSort, usePagination, useDebounce, useStorage.
Додати специфічні для проєкту? (наприклад, useCart, useCheckout, useAnalytics)
Q31. Правила розміщення файлів — файли з певним паттерном назви мають бути в певній папці?
(Project Structure check → fileRules)
Типові паттерни за стеком:
| Паттерн | Має бути в | Стек |
|---|---|---|
*.service.ts | src/services | NestJS / загальний TS |
*.controller.ts | src/controllers | NestJS / MVC |
*.repository.ts | src/repositories | DDD |
*.store.ts | src/stores | Управління станом |
*.dto.ts | src/dto | NestJS |
*.entity.ts | src/entities | TypeORM / NestJS |
*.model.ts | src/models | загальний |
*.middleware.ts | src/middleware | Express / NestJS |
*.guard.ts | src/guards | NestJS |
*.schema.ts | src/schemas | валідація |
*_handler.go | internal/handlers | Go |
*_service.go | internal/services | Go |
*_repo.go | internal/repo | Go |
Які застосовні? Є кастомні правила?
Q32. Правила вмісту папок — файли всередині папки мають містити певний експорт/оголошення?
(Project Structure check → folderRules)
Типові приклади:
| Папка | Має містити | Опис |
|---|---|---|
src/hooks | export function use | export const use | Hook-файли мають експортувати useXxx |
src/services | export class | export function | export const | Service-файли мають щось експортувати |
src/components | export default | export const | Компоненти мають мати експорти |
src/controllers | export class | @Controller | NestJS контролери |
Які застосовні? Є кастомні правила?
Q33. Пороги зв’язності для цього проєкту?
(fan-out = кількість локальних файлів, які імпортує модуль; великий fan-out = “god file”)
- Попередження при fan-out ≥ N: за замовчуванням
15 - Помилка при fan-out ≥ N: за замовчуванням
30
Скоригувати для розміру проєкту?
Q34. Пороги складності коду?
- Довжина функції: попередження ≥ N рядків (за замовчуванням
40), помилка ≥ N рядків (за замовчуванням80) - Циклічна складність: попередження ≥ N (за замовчуванням
10), помилка ≥ N (за замовчуванням20) - Кількість параметрів: попередження ≥ N (за замовчуванням
4), помилка ≥ N (за замовчуванням7) - TypeScript return types: попередження при N відсутніх (за замовчуванням
10), помилка при N (за замовчуванням50)
Залишити за замовчуванням чи скоригувати?
Група G — Quality Hub: вбудовані перевірки (Q35–Q40)
Всі перевірки увімкнені за замовчуванням. Перелічити тільки ті, що вимкнути.
Дивись довідник Built-in Checks для повного переліку і порогів.
Q35. Вимкнути перевірки розміру / складності коду?
lineCount | fileSize | functionLength | complexity | longLines | importDepth | directoryDepth | dependencyCount
Q36. Вимкнути перевірки якості коду?
todoCount | commentedCode | duplicateFiles | mixedIndent | encoding | secretLeaks | debugLeaks | gitignoreCheck | magicNumbers | parameterCount | barrelFiles
Q37. Вимкнути архітектурні перевірки?
couplingMetrics | componentInventory | heavyImports
Q38. Вимкнути перевірки типізації / документації?
anyCoverage | jsdocCoverage | returnTypes
Q39. Вимкнути перевірки здоров’я проєкту?
envConsistency | lockfileSync | nodeVersionConsistency | readmeCheck | changelogCheck | codeownersCheck
Q40. Вимкнути TypeScript/frontend перевірки?
asyncAwaitMisuse | errorHandling | reactHookRules | a11yCheck
Проєкт має тести? Якщо ні → вимкнути testRatio, emptyTests, lcovCoverage.
Група H — Quality Hub: security та CLI-інструменти (Q41–Q45)
Всі пропускаються gracefully якщо не встановлені. Дивись документацію CLI Tools для інструкцій встановлення.
Q41. Які CLI security-інструменти встановлені і мають бути увімкнені?
| Інструмент | Встановлення | Коли вмикати |
|---|---|---|
| Semgrep | pip install semgrep | Будь-який проєкт (30+ мов) |
| Trivy | winget install AquaSecurity.Trivy | Будь-який проєкт із залежностями |
| ESLint Security | npm i -D eslint eslint-plugin-security | JS/TS проєкти |
| Bandit | pip install bandit | Тільки Python-проєкти |
| Bearer | brew install bearer/tap/bearer (macOS/Linux) | Аналіз витоку чутливих даних |
| Hadolint | winget install hadolint | Проєкти з Dockerfile |
| ShellCheck | winget install koalaman.shellcheck | Проєкти зі скриптами .sh |
| golangci-lint | winget install golangci-lint | Тільки Go-проєкти |
Q42. Пороги серйозності Trivy?
- Помилка при:
CRITICAL|HIGH(за замовчуванням) |MEDIUM - Попередження при:
HIGH|MEDIUM(за замовчуванням) |LOW
Q43. Увімкнути додаткові CLI-перевірки?
jscpd— виявлення copy-paste (JS/TS/будь-яка мова): поріг дублювання %? (за замовчуванням: 5%)knip— виявлення мертвого коду (JS/TS, auto via npx)dependencyCruiser— циклічні імпорти (JS/TS, auto via npx)pkgAudit—npm audit/pip-audit/cargo auditтощоoutdatedDeps— застарілі залежностіlicenseCheck— відповідність ліцензій (auto via npx)
Q44. Увімкнути IaC / API / format лінтери?
checkov— безпека Terraform / Kubernetes / Dockerfile (pip install checkov)spectral— лінтинг OpenAPI / AsyncAPI (npm i -g @stoplight/spectral-cli)yamllint— YAML синтаксис (pip install yamllint)sqlfluff— SQL файли (pip install sqlfluff)markdownlint— Markdown (npm i -g markdownlint-cli2)tscCheck— TypeScript компілятор (npx tsc --noEmit, потребуєtsconfig.json)act— запуск GitHub Actions локально (winget install nektos.act)
Q44b. Увімкнути лінт схеми бази даних?
| Інструмент | Встановлення | Що перевіряє |
|---|---|---|
| Schema Lint (вбудований) | не потрібно — чистий Node.js | Float замість Decimal для грошей, відсутні FK-індекси, іменування, великі моделі (лише не-relation поля), відсутні timestamps, відсутній default для ID, зарезервовані слова, String/UUID-as-FK (суфікси Id/_id/Ref/_ref), JSON без документації, cascade без soft-delete. Авторозпізнавання: Prisma, Drizzle, Django, SQLAlchemy, Rails, Laravel, EF Core, Go (GORM/ent/xorm), сирий SQL |
| prisma-lint | npm i -D prisma-lint | Іменування в Prisma-схемі, порядок полів, обов’язкові індекси |
| Squawk | npm i -g squawk-cli | Безпека міграцій PostgreSQL: небезпечні блокування, missing CONCURRENTLY, backward-несумісні зміни |
| Atlas | winget install ariga.atlas (Windows) / curl -sSf https://atlasgo.sh | sh | 50+ аналізаторів міграцій: деструктивні зміни, блокування, сумісність |
Schema Lint увімкнений за замовчуванням (як всі вбудовані перевірки) і не потребує налаштування — він автоматично визначає стек ORM.
Q45. Увімкнути Stryker mutation testing?
(вимкнено за замовчуванням — дуже повільний; потребує @stryker-mutator/core)
Група I — Quality Hub: покриття (Q48)
Q48. LCOV coverage — чи є coverage/lcov.info або coverage-summary.json згенерований тест-ранером?
(читає існуючий файл — тести не запускає; увімкнути якщо CI генерує coverage-звіти)
Група J — Git, CI/CD та інтеграції (Q49–Q50)
Q49. CI/CD та Git налаштування:
- Шлях до GitHub workflows:
.github/workflowsабо кастомний? - Команда docker compose:
docker compose|docker-compose|podman compose - Гілка за замовчуванням для Git-операцій
- Список захищених гілок (не можна видалити з сайдбара)
- Milestone за замовчуванням для нових GitHub Issues (необов’язково)
Q50. AI та голосові налаштування (необов’язково):
- Gemini API key (для AI генерації заголовків та голосової диктовки)
- Модель Gemini:
gemini-2.5-flash(за замовчуванням) |gemini-2.0-flash|gemini-1.5-pro - Мова диктовки:
auto|uk|en|de|frтощо - Кастомний промпт для Issue → Chat
- Кастомний промпт для PR → Chat
- Кастомний промпт для Quality Hub → Chat
Phase 3 — Запис налаштувань
Записати всі налаштування в .vscode/settings.json. Правила:
- Завжди включати:
project.name,project.dir,project.packageManager,project.servers - Пропускати дефолти: не писати налаштування рівні задокументованим за замовчуванням
- Пропускати порожнє: без порожніх масивів, порожніх рядків для необов’язкових полів,
null - Шлях:
.vscode/settings.jsonу корені проєкту — ЄДИНЕ місце дляdevManager.*
Для повного довідника налаштувань і прикладів — дивись англомовну версію настанови (містить всі приклади JSON).
Посилання на документацію
| Тема | Сторінка |
|---|---|
| Dev Servers | /uk/features/servers/ |
| Docker Compose | /uk/features/containers/ |
| Quality Hub огляд | /uk/quality/ |
| Built-in перевірки (70+) | /uk/quality/builtin-checks/ |
| CLI Tool перевірки | /uk/quality/cli-tools/ |
| Custom Checks | /uk/quality/custom-checks/ |
| Всі налаштування | /uk/reference/configuration/ |
| Встановлення CLI-інструментів | /uk/reference/cli-install/ |