textmachine/CLAUDE.md

TextMachine — контекст для Claude-сессий

Go-бэкенд издательского художественного перевода крупных текстов (ранобэ/вебновеллы, zh/ja/en→ru) через мультиагентный LLM-пайплайн: дешёвый черновик → редактор → детерминированные $0-гейты → судья (Ф2).

Цели и мерило (канон владельца, 02.08 — каждое решение сверяется с этим)

1. Продукт: издательское художественное качество перевода больших текстов — победить translationese; консистентные термины/голоса на всю книгу; чувствительный контент с учётом цензуры провайдеров.
2. Мультиязычность: движок ОДИН и общий; языко-/пара-/книго-специфика легитимна, но живёт в ДАННЫХ и отдельных модулях, встраиваемых архитектурно чисто (langpacks · пар-промпты · сид/бриф), и разрабатывается отдельно от ядра. Ревью-вопрос по умолчанию: «заработает ли пара, которой в репо ещё НЕТ, без правки Go?»
3. Чистая архитектура: бэкенд легко писать и поддерживать; механизм строится только там, где несёт качество/деньги — не ради галочки трекера.
4. Современные подходы и харнесс-превосходство: пайплайн и транспорт на уровне или впереди конкурентных харнесс-решений (калибровка — research/21–22); эмпирика решает — мерить, не верить.
5. Экономика: низкий COGS на дешёвых моделях с адресными дорогими вызовами; деньги видимы с первого вызова (телеметрия · потолки · явное согласие на пере-оплату).
6. Детерминизм: воспроизводимый прогон (снапшоты · банк памяти · golden) — повторение без сюрпризов и тихих перепокупок.

Роли сессий и зоны (НЕ править чужую зону)

Роль	Зона записи	Коммитит сама?	Всё остальное
Бэкенд	backend/	нет — лендит оркестратор	читать можно; расхождения — пингом оркестратору в docs/PROGRESS.md
Полигон (eval)	eval/ + docs/experiments/	только пре-рег фризы	то же
Оркестратор	docs/ (architecture/research/PROGRESS) + корневые онбординг-доки, ревью чужого кода read-only	да	ратифицирует решения, пишет хендофф-промты
Фронт	frontend/	нет — лендит оркестратор	читать можно; пинги, итоги и вопросы — ЗОННЫЙ журнал frontend/docs/frontend-PROGRESS.md (решение владельца 02.08/04.08; в docs/PROGRESS.md фронт НЕ пишет), туда же пишет и оркестратор; продуктовые требования — docs/product-requirements.md, НЕ из памяти
Платформа	platform/ (SaaS control plane: пользователи/квоты/очередь/HTTP; движок дёргает процессами, D39.81)	нет — лендит оркестратор	читать можно; пинги и итоги — ЗОННЫЙ журнал platform/docs/platform-PROGRESS.md (решение владельца 04.08), в docs/PROGRESS.md не пишет

Координация — журнал docs/PROGRESS.md (секции «Бэкенд»/«Полигон»/«Память»/«Голос и состояние»/«Ридер-IDE»; сверху CURRENT-STATE). Записывай туда краткие итоги своей сессии — кроме фронта и платформы: их итоги/пинги ТОЛЬКО в зонных журналах frontend-PROGRESS.md/platform-PROGRESS.md (решение владельца 04.08, D39.100). Закрытые хроники вынесены в слайсы docs/archive/PROGRESS-*.md — НЕ читать при онбординге, только по конкретной ссылке. Параллельные сессии — норма: чужие незакоммиченные файлы в дереве не трогать; сессия считается ЖИВОЙ, пока владелец не сказал обратное.

Источники истины (по убыванию)

1. docs/architecture/05-decisions-log.md — ратифицированный контракт; при конфликте с любым другим доком побеждает он; сверху файла — карта актуальности (что чем superseded), свежая голова — С ХВОСТА файла. Правило чтения (онбординг-диета 25.07): карта + живая голова (эра D39.x); корпус D1–D38 = справочник — по ссылкам/grep по D-номеру, целиком НЕ читать.
2. docs/experiments/00-provider-quirks.md — wire-квирки провайдеров (читать ПЕРЕД правкой адаптеров/вызовами провайдеров).
3. docs/architecture/09-target-architecture.md (7 слоёв; статус стройки — шапка-таблица) · 12-go-style-notes.md (норматив общности §0) · 10-prompt-architecture.md (промпт-тема) · 14-api-contract/ — ратифицированный контракт API v0 фронт↔платформа (OpenAPI 3.1 + компаньон, D39.99). 3а. docs/product-requirements.md — реестр «что продукт обязан уметь» (производный от ЖИВОГО брифа владельца START_PROMT.MD V0–V5 + находок H6–H18; статусы сверены кодом, актуализирует оркестратор при лендингах). Новые V-идеи владельца разбираются сюда, не остаются невидимыми.
4. docs/architecture/01-decisions.md (Р1–Р10), 02-mvp-plan.md, 04-unhappy-paths.md, 06-memory-risk-registry.md — тела исторические, читать через ⚠-баннеры 25.07.
5. docs/research/* — фактура; часть под ⚠ superseded/построено-баннерами — читай баннер прежде содержимого.
6. docs/archive/ — история: закрытые промты (prompts/) · отчёты паков с ревью-шапками (reports/) · исполненные арх-доки (architecture/: 07 стратревью · 08 синк-ледджер · 11 план пака-11).

Гардрейлы (жёсткие)

• НИКОГДА не читать .env (backend/.env, eval/.env) — там ключи. .env.example можно.
• PUML не рендерить в svg/png — владелец смотрит PlantUML-расширением VS Code.
• Коммиты: английский, одно предложение ≤30 слов, без Co-Authored-By. .claude/settings.local.json НЕ коммитить (ломает пермишены).
• Провайдерские ловушки: DeepSeek — НИКОГДА не отключать thinking (эхо-мина; гейт echoMineViolation это принуждает); grok-4.3 reasoning off — только ЯВНЫЙ reasoning_effort:"none" (дефолт low; wire-квирк в силе, но из РЕДАКТОРСКИХ ролей reasoning-off снят — no-op, D30.1); слаги моделей не менять без live-фактчека /models; ⚠ «слаг живой» ≠ «модель та же» — DeepSeek 31.07 сменил веса под слагом (D39.61), при аномалиях сверять поведение и вендор-лог обновлений. Пробы/запросы падают или ведут себя странно (флейки, 404 живой модели, новый finish_reason, игнор параметров) → идём в официальную доку вендора (deprecations/changelog/status) и гуглим, НЕ гадаем — интерпретацию аномалии без вендор-сверки в доки/промты не абсорбировать (решение владельца 10.07; правило двух направлений — 00-provider-quirks.md шапка).
• Дисциплина: не верь заголовкам — грунтуй выводы file:line/цитатой; спорное верифицируй адверсариально (author≠reviewer); эмпирика на PD-классике из претрейна считается предварительной до вебновелл-среза.
• Общность движка (владелец 24.07): Go-логика НЕ ветвится по паре/книге; пара-данные → internal/lang+configs/langpacks/, книго-каноны → сид/brief (данные); книжный термин в общем пар-слое = утечка. Тест-данные пары легитимны. Норматив (только больные места): docs/architecture/12-go-style-notes.md. Ревью-вопрос по умолчанию: «заработает ли на паре, которой в репо ещё НЕТ, без правки Go?»
• При компакции/сжатии контекста ВСЕГДА сохранять: список изменённых файлов · незакрытые находки ревью и их диспозиции · обязательства и открытые вопросы сессии · команды тестов (D39.121).
• Тесты и гейты не подгонять под зелень: править или удалять тест/голден/гейт, чтобы он прошёл, — НЕДОПУСТИМО; несогласие с тестом — вопрос оркестратору пингом, не правка (D39.121).
• Мандат самопроверки в промтах сессий (обязателен, решение владельца 12.07): промты полигон-сессий — и вообще любых пишущих код / запросы к моделям — ДОЛЖНЫ явно требовать ревью ИСПОЛНЕНИЕМ: своего кода + сформированных запросов к моделям + полученных результатов. Полигон регулярно ошибается/багует, и это искажает эксперименты (D37: заявленные «0 ошибок» = 36 ошибок+биллинг, «13 катастроф» = ~5–6 при оверфлаге судьи; exp13 +10% бюджета). Бэкенд-промты — явный бэкенд-ревью после кода (обычно отрабатывает по опыту, но требовать явно). Пост-хок адверсариальная верификация оркестратора при лендинге — второй рубеж, НЕ замена самопроверки.
• Git-координация мультисессий:
  • Коммитит только оркестратор. Сессии зон — бэкенд, полигон, фронт, платформа — не коммитят: своё дерево готовят и передают на лендинг (исключение прежнее: пре-рег фризы полигона). Чужую зону не трогает НИКТО.
  • Форма коммита — ТОЛЬКО с явным списком путей: git commit -- <путь> <путь>. Причина механическая и это корень обоих инцидентов 02.08: голый git commit уносит ВЕСЬ индекс, включая чужие застейдженные файлы, и чужая работа уезжает под твоим сообщением. Pathspec-форма индекс не трогает.
  • НИКОГДА git add -A / git add . / git commit -a — только явные пути.
  • Перед каждым коммитом: git status (опознать ЧУЖОЕ) и git diff --cached --name-only. Увидел в индексе путь вне своей зоны — не коммить его и не «прибирать»: снимай не чужое из индекса, а свою задачу — коммить pathspec-формой.
  • Не оставляй свои файлы застейдженными между операциями: пока они в индексе, их может унести чужой коммит (этим оркестратор №10 сам подставился дважды). Стейдж и коммит — одной командой.
  • НИКАКИХ reset --hard, перезаписей истории (amend/rebase несвежих коммитов) и checkout поверх грязного дерева, пока возможны незакоммиченные правки параллельных сессий; history-rewrite — только по согласованию через оркестратора при чистом дереве (урок 09.07: rewrite оркестратора стёр незакоммиченные правки полигона).
  • Чужое уже уехало в твой коммит? Историю НЕ переписывать — сообщить владельцу/оркестратору; содержимое при этом цело, теряется только атрибуция.
  • Никогда не коммитить: START_PROMT.MD (файл владельца) · .claude/settings.local.json · книгу и производные (живут в ~/books, вне git).

Онбординг новой сессии (порядок чтения)

⚠ Всю документацию и код проекта пишут нейросети — они могут ошибаться; учитывай при чтении.

1. Этот файл → docs/README.md (карта) → CURRENT-STATE в docs/PROGRESS.md. Непонятный жаргон/сокращения — docs/glossary.md.
2. docs/architecture/05-decisions-log.md: карта актуальности (шапка) + живая голова (D39.x). Целиком НЕ читать — корпус D1–D38 по ссылкам/grep по мере надобности.
3. По роли: Бэкенд — backend/README.md + 03-implementation-notes.md (через баннер) + 12-go-style-notes.md; Полигон — eval/README.md + experiments/00 + 09-pilot-protocol.md; Фронт/продукт — docs/product-requirements.md + research/16 (через ревью-шапку) + контракт architecture/14-api-contract/; Платформа — platform/README.md + зонный журнал + research/23 + контракт 14; всем — шапка-таблица 09-target-architecture.md (статус слоёв).