86 lines
6.2 KiB
Markdown
86 lines
6.2 KiB
Markdown
# AGENTS.md — StrixScripts
|
||
|
||
Инструкции за AI coding агенти (Claude Code, GitHub Copilot, Cursor и др.),
|
||
работещи в този repo. Ако инструментът ти чете `CLAUDE.md` вместо този
|
||
файл — `CLAUDE.md` е кратък pointer към този документ; съдържанието не се
|
||
дублира умишлено, за да не се разсинхронизира.
|
||
|
||
## Какво е проектът
|
||
|
||
Колекция от самостоятелни bash скриптове, организирани по функционални
|
||
папки. Всеки скрипт решава една конкретна задача и има собствена `.md`
|
||
документация до себе си.
|
||
|
||
## Задължителна структура при всеки нов скрипт
|
||
|
||
Когато създаваш нов скрипт, следните стъпки са ЗАДЪЛЖИТЕЛНИ, не опционални
|
||
— пропускането на която и да е от тях е непълна задача, не "готово с TODO":
|
||
|
||
1. **Скриптът и неговият `.md` файл имат еднакво basename**, в една и
|
||
съща папка: `deploy/restart-nginx.sh` → `deploy/restart-nginx.md`.
|
||
Виж `templates/script-template.md` за структурата, която `.md` файлът
|
||
трябва да следва.
|
||
|
||
2. **Скриптът source-ва `lib/common.sh`** и извиква
|
||
`common::show_help_if_requested "$@"` веднага след дефиниране на
|
||
`SCRIPT_HELP` heredoc-а, преди какъвто и да е друг argument parsing.
|
||
Виж `templates/script-template.sh` за точния pattern и
|
||
`examples/hello-world.sh` за работещ пример.
|
||
|
||
3. **`--help` (и `-h`) работи и показва пълна информация** — какво прави
|
||
скриптът, какви опции приема, поне един пример за извикване. Това е
|
||
съдържанието на `SCRIPT_HELP`, не отделна имплементация — не пиши
|
||
ръчен `if [[ "$1" == "--help" ]]` в скрипта, common.sh вече го прави.
|
||
|
||
4. **В `README.md` (корена на проекта) се добавя ред в секцията на
|
||
съответната категория папка** — кратко описание (едно изречение) +
|
||
relative link към `.md` файла на скрипта. Пълното описание живее само
|
||
в скрипт-специфичния `.md`, README не го дублира.
|
||
|
||
5. **Скриптът минава `shellcheck` без warnings** (виж `.shellcheckrc` в
|
||
корена). Ако warning-ът е false positive, добави `# shellcheck disable=SCxxxx`
|
||
с коментар защо точно на реда, не глобално в файла.
|
||
|
||
6. **`set -euo pipefail`** в началото на всеки скрипт, веднага след shebang
|
||
реда и коментарния блок. Без изключения — ако скрипт умишлено трябва да
|
||
продължи след грешка в конкретна команда, обгради само тази команда с
|
||
`|| true` или явна проверка, не маха global `set -e`.
|
||
|
||
## Конвенции за именуване и стил
|
||
|
||
- **Файлови имена:** kebab-case, описателни глагол+обект (`backup-nextcloud.sh`,
|
||
не `backup.sh` или `script1.sh`).
|
||
- **Категория папки:** функционална група (напр. `backup/`, `network/`,
|
||
`deploy/`) — създавай нова папка само когато скриптовете вътре наистина
|
||
споделят функционален домейн, не по проект или по дата.
|
||
- **Всички коментари в кода — само на английски**, независимо от езика на
|
||
разговора с агента. `.md` документацията и `README.md` могат да остават
|
||
на български — те са за човека, не за компилатора/shellcheck.
|
||
- **Грешки:** винаги през `common::die "message"`, никога суров
|
||
`echo ... >&2; exit 1` — за консистентен формат на грешките между
|
||
скриптове.
|
||
- **Статус/progress съобщения:** през `common::log`, който пише на stderr,
|
||
за да остане stdout чист за реален output, който може да бъде pipe-нат
|
||
или captured от друг скрипт/потребител.
|
||
|
||
## `lib/common.sh` — НЕ дублирай логика от него
|
||
|
||
Ако скрипт се нуждае от поведение, което `common.sh` не предоставя (напр.
|
||
retry logic, temp file cleanup trap, конкретен validation helper) —
|
||
разшири `common.sh`, не пиши локална версия вътре в отделния скрипт. Целта
|
||
е всеки скрипт да остава кратък и всички споделят едно и също поведение
|
||
за грешки/help/logging.
|
||
|
||
## `examples/` и `templates/` — само референция
|
||
|
||
`examples/hello-world.sh` е работещ демонстрационен скрипт, показващ
|
||
пълната конвенция накратко. `templates/` съдържа празни шаблони за копиране.
|
||
Нито едната папка не съдържа реални production скриптове — не ги викай от
|
||
други скриптове или automation, и не добавяй реални utility скриптове там.
|
||
|
||
## Статус
|
||
|
||
Проектът е в начален етап — само structural скелет (`lib/common.sh`,
|
||
`templates/`, `examples/hello-world.sh`) съществува. Реални функционални
|
||
категории папки и скриптове предстои да бъдат създадени.
|