slaid098/opencode-config
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions
opencode-config/docs/decisions/053-pr-120-agents-extract-skill-en.md
Sergey c9533050b8
refactor(agents): extract bug-discovery skill, AGENTS.md to English, EN descriptions (#120) 
Co-authored-by: opencode-agent <agent@opencode.local>
2026-07-29 05:14:28 +03:00

3.9 KiB
Raw Permalink Blame History

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.