55 lines
No EOL
3.9 KiB
Markdown
55 lines
No EOL
3.9 KiB
Markdown
# ADR-053: Extract bug-discovery skill, AGENTS.md to English
|
||
|
||
## Статус
|
||
Accepted (2026-07-29)
|
||
|
||
## Контекст
|
||
|
||
AGENTS.md (project-local, bind-mounted глобально) накопил процедурные детали,
|
||
ухудшающие читаемость:
|
||
|
||
- **Bug Discovery Protocol** — 8-строчный протокол (проверка дубликатов, шаги
|
||
создания issue, формат title/body, отчёт). Процедура, не правило — тянет в
|
||
скилл.
|
||
- **Tools секция** — содержала мягкую enforcement-фразу "НЕ fallback на raw
|
||
bash, НЕ обход через `gh api`". Но реальный enforcement — deny-list в
|
||
`permission.bash` файла `opencode.json`. Мягкие инструкции не работают (агент
|
||
всё равно попытается fallback если нет жёсткого block).
|
||
- **Skill descriptions** — смесь RU/EN. Descriptions используются для semantic
|
||
skill selection (matching). RU-only descriptions (`run-pipeline`,
|
||
`code-standards`, `memory` и др.) ухудшают matching против EN intent.
|
||
- **`add-skill` инструкция** — не уточняла язык description, оставляя
|
||
произвол — новые скиллы плодили RU descriptions.
|
||
|
||
## Решение
|
||
|
||
1. **Извлечь Bug Discovery Protocol в скилл `bug-discovery`** — 6-шаговый
|
||
протокол в `.opencode/skills/bug-discovery/SKILL.md`. В AGENTS.md оставить
|
||
1 строку: "If a bug is found outside current task scope — load skill
|
||
`bug-discovery`."
|
||
2. **Перевести AGENTS.md на английский** — все 8 секций. Язык остаётся
|
||
"Always respond to the user in Russian" (взаимодействие с юзером), но
|
||
правила/directives на EN для consistency с global AGENTS.md (тоже EN).
|
||
3. **Упростить Tools** — убрать мягкую enforcement-фразу. Оставить:
|
||
"Use tools instead of bash. On failure — STOP + report. Deny-list in
|
||
`permission.bash` of `opencode.json`." Real enforcement = deny-list.
|
||
4. **EN descriptions для 10 скиллов** — перевести frontmatter `description` на
|
||
английский (форматы `Use when ... Also when user says "..."` с RU-триггерами).
|
||
Тела скиллов НЕ трогать (могут оставаться на русском).
|
||
5. **Обновить `add-skill`** — инструкция и шаблон явно требуют EN description
|
||
для новых скиллов. RU фразы разрешены только в `Also when user says "..."`.
|
||
|
||
## Альтернативы
|
||
|
||
- **Оставить Bug Discovery Protocol в AGENTS.md, не извлекать** — отвергнуто:
|
||
AGENTS.md перегружен процедурами. Скиллы — правильное место для процедур
|
||
(загружаются по триггеру, не загромождают always-loaded directive).
|
||
- **Принудительная миграция ВСЕХ скиллов на EN descriptions** — отвергнуто: 5
|
||
скиллов (`branch`, `repo-init`, `repo-readme`, `configure-opencode`,
|
||
`add-skill`) уже имели EN descriptions. Принудительный обход всех —
|
||
лишний churn. Мигрированы 10 с RU-only. Будущие — через обновлённый
|
||
`add-skill` instruction.
|
||
- **Оставить мягкую enforcement в Tools ("НЕ fallback")** — отвергнуто: не
|
||
работает. Deny-list — реальный enforcement (raw `git commit`, `gh issue
|
||
create *`, `gh pr merge *` заблокированы). Дублирование мягкой инструкции
|
||
создаёт ложное ощущение enforcement. |