Ґрунт — Skill для розробника додатків
Цей skill допомагає будувати повноцінні додатки на базі Ґрунт — metadata-driven framework (Python/FastAPI/Vue 3).
Активація
Skill активується, коли задача стосується:
- Створення або зміни DocType
- Написання контролерів (validate, after_insert тощо)
- Реєстрації хуків (
@on) - REST API або GruntApp SDK (
grunt.get_doc,grunt.new_doc...) - Роботи з базою даних через
grunt.db - Налаштування дозволів (RBAC, ролі)
- Фонових задач (Celery,
@retryable_task) - Frontend на Vue 3 + grunt-ui
- CLI команд (
grunt serve,grunt db migrate...) - Написання тестів (pytest, vitest)
Два головних workflow
1. Новий додаток
Розпочни з new-app.md
2. Існуючий додаток
Розпочни з existing-app.md
Таблиця референсів
Завантажуй лише той файл, який стосується поточної задачі.
| Тема | Референс |
|---|---|
| Новий додаток (scaffold) | new-app.md |
| Існуючий додаток (розширення) | existing-app.md |
| DocType: визначення, типи полів | doctypes.md |
| Контролери: lifecycle hooks | controllers.md |
Хуки: @on декоратор | hooks.md |
| REST API + GruntApp SDK | api.md |
База даних: grunt.db.* | database.md |
| Дозволи: RBAC, ролі | permissions.md |
| Фонові задачі: Celery | background-tasks.md |
| Frontend: Vue 3 + grunt-ui | frontend.md |
| CLI команди | grunt-cli.md |
| Логування: structlog, BackgroundTaskLog, ActivityLog | logging.md |
| Тестування | testing.md |
Філософія: "Everything is a DocType"
У фреймворку Ґрунт DocType — це ядро всього функціоналу. Всі нові можливості мають будуватися довкола DocType:
- Контролери: Бізнес-логіка повинна бути інкапсульована в методах класу DocType (контролері).
- Сторінки та UI: Нові сторінки, дашборди чи складні форми повинні визначатися через відповідні DocTypes (напр.
Workspace,Dashboard,WebForm). - Vue-компоненти: Будь-яка складна фронтенд-логіка має бути максимально налаштовуваною через метадані DocType.
- Розширення: Якщо DocType не може реалізувати задачу — першим кроком спочатку розшир можливості самого DocType (ядра), а не будуй сторонні рішення.
Загальні правила
- Завжди запускай
grunt doctype sync <Name>після будь-яких змін у DocType - Пріоритет DocType: Контролери — максимально в доктайпах. Нова сторінка — також через доктайп.
- Ніколи не пиши raw SQL — тільки SQLAlchemy або
grunt.db.* - Ніколи не пиши міграції вручну — вони генеруються автоматично через sync
- Завжди async/await — Ґрунт є async-first (FastAPI + SQLAlchemy 2.0)
- Завжди type hints в Python і TypeScript
- Логуй через
structlog - Секрети — тільки через
config.py+ env змінні - Бізнес-логіку — в сервісному шарі або методах DocType (контролера)
- Строго дотримуйся стандарту PEP8 для будь-якого коду на Python.
- Використовуй максимально нові версії всіх пакетів і фреймворків, включно з найсвіжішими стабільними версіями Python та Node.js.
Структура відповіді API
// Успіх
{"success": true, "data": {...}, "meta": {"total": 100, "page": 1, "per_page": 20}}
// Помилка
{"success": false, "error": {"code": "VALIDATION_ERROR", "message": "...", "details": []}}Готовність до модернізації
- Пропонуй стратегію модернізації коду для підтримки оновлення інфраструктури (пакетів, Python, Node.js) до новітніх версій.
- Якщо бачиш, що можна покращити апі, клі, будь-який компонент, документацію, тести - запропонуй покращення. Якщо користувач погодиться - зроби це.
- Якщо бачиш, що можна покращити skill - запропонуй покращення. Якщо користувач погодиться - зроби це. Зверни увагу - зміни треба вносити в grunt-agent-skills.