textmachine/docs/architecture/12-go-style-notes.md

Правила общности движка + Go-ответы по больным местам (12)

Короткий норматив для бэкенд-сессий (24.07.2026). Только неочевидное/больное — общий Go-стиль сессии и так соблюдают, его тут нет. Источники Go-части: Google Go Style Guide (guide/decisions/best-practices) + Effective Go + Go Wiki CodeReviewComments.

§0. Общность движка (директива владельца 24.07 — жёсткая)

1. Движок language/book-agnostic. Go-ЛОГИКА не ветвится по паре языков или книге. Пара-специфичное — ДАННЫМИ: internal/lang + configs/langpacks/<пара>/ (fail-loud loader, байты в pack.Version() → снапшот). Книго-специфичное — данными КНИГИ: сид-глоссарий / brief / book.yaml. Книжный канон в общем пар-слое = утечка (прецедент: 古月 в surnames-compound.txt).
2. Пар-скоупнутые модули (checkers_zh_ru и т.п.) легитимны как код за pair-гейтом, но их ДАННЫЕ (словники, руны, таблицы) подлежат выносу в langpack.
3. Тест-данные пары легитимны: zh/ru-строки в *_test.go/golden упражняют общую логику. Не путать с логикой.
4. Промпты — pair-keyed файлы (prompts: {<пара>: файл}, fail-loud на чужую пару); конвенции пары (меры, стихи, дискурс) живут в теле промпта СВОЕЙ пары — это данные. Дальний план — извлечение в структурированный пакет конвенций пары (10-prompt-architecture, гейтится формой пакета).
5. Ревью-вопрос по умолчанию: «заработает ли это на паре, которой в репо ещё НЕТ, без правки Go?» Если нет — данные наружу.

§1. Go-ответы (только то, о чём реально спорим)

• _test.go рядом с кодом — не бардак, а требование тулчейна: go test собирает тесты только из каталога пакета; отдельных tests/-деревьев в Go не существует.
• ~50 файлов в internal/pipeline — норма, не смелл. Google явно: число/размер файлов — НЕ критерий сплита («maintainers can move code between files without affecting callers»; эталон — stdlib bytes). Единственный легитимный триггер сплита — концептуально отдельная подсистема со своим узким API, которую не импортируют всегда вместе с pipeline. Дробление «ради размера» рождает util-пакеты и течёт деталями в публичные API.
• Никаких пакетов util/common/helpers/types — имя пакета обязано нести домен (Decisions/CodeReviewComments).
• «Least mechanism» (Guide): сперва slice/map/struct, потом stdlib, только потом своё/зависимость; это же — мера сдержанности к дженерикам и абстракциям «на вырост».
• Интерфейс объявляет потребитель, не реализация; не заводить интерфейсы заранее «для моков» (CodeReviewComments) — наш BuildClient/адаптеры уже так устроены, держать линию.