docs(config): add Config Edits rule to AGENTS.md, expand configure-opencode (#181 )

* docs(agents): add Config Edits rule linking configure-opencode skill

* docs(configure-opencode): expand scope rule to AGENTS, skills, agents, commands

* docs(handoff): scaffold handoff and ADR-078 for config-edits rule

* docs(handoff): set PR number 181 in handoff and ADR-078

---------

Co-authored-by: opencode-agent <agent@opencode.local>

2026-07-31 22:01:56 +03:00

3.6 KiB

Raw Blame History

ADR-078: Config Edits rule — workspace clone only, never ~/.config/opencode/

Статус

Accepted (2026-07-31)

Контекст

В Docker-сетапе opencode ~/.config/opencode/ — bind-mount из хост-сорса /root/dockers/opencode-config/.opencode/, а глобальный AGENTS.md — отдельный read-only mount из корня репо. Агенты, редактирующие файлы в ~/.config/opencode/ напрямую, физически меняют файлы на хост-сорсе в обход git. Потом другой агент коммитит из workspace clone /root/workspace/opencode-config/ и пушит → на хосте git pull → конфликт, потому что хост-сорс уже имеет uncommitted изменения.

Скилл configure-opencode фиксировал контракт «куда писать» только для opencode.json (в .opencode/opencode.json в workspace clone). Контракт НЕ покрывал AGENTS.md, skills/, agents/, commands/ — и не было явного запрета редактировать ~/.config/opencode/ напрямую. Это приводило к рассинхрону и конфликтам git pull.

Решение

В AGENTS.md (корень репо) добавлен блок ## Config Edits: короткое правило — все правки конфига opencode (opencode.json, AGENTS.md, skills/, agents/, commands/) идут ТОЛЬКО в workspace clone /root/workspace/opencode-config/, НИКОГДА в ~/.config/opencode/ (bind-mount → bypass git → git pull конфликты на хосте). Ссылка на skill configure-opencode для полной sync-процедуры. Намеренно кратко (1 абзац) — дублирование со skill избегается.
В configure-opencode/SKILL.md добавлен раздел ## 1.1. Scope правила «куда писать»: расширяет scope правила с «только opencode.json» на все артефакты конфига (AGENTS.md, skills/, agents/, commands/). Содержит пояснение bind-mount архитектуры (rw .opencode/ + ro AGENTS.md), описание почему правки в ~/.config/opencode/ bypass git, и каноническую sync-процедуру: правка в workspace clone → commit + git push → host git pull → docker compose restart opencode.

Альтернативы

Расширить AGENTS.md блок до полной sync-процедуры — отклонено: дублирование со skill configure-opencode, риск рассинхрона при правках. Краткое правило + ссылка на skill = единственный источник правды.
Запретить запись в ~/.config/opencode/ через permission.bash deny-правило — отклонено: opencode permission контролирует bash-команды, а не file-write tools (write/edit); deny не покрыл бы основной вектор. Контракт в AGENTS.md + skill надёжнее для агентского поведения.
Сделать ~/.config/opencode/ полностью ro-mount — отклонено: некоторые файлы (логи, кеш) пишутся opencode runtime; ro сломал бы их. Контракт на уровне инструкций агента выбран как достаточно.

3.6 KiB Raw Blame History Unescape Escape