arm-ka-docs/context/00-workspace-layout.md

00. Рабочая область агента: несколько репозиториев

Система состоит из нескольких сервисов в разных git-репозиториях. Агент работает из общей родительской директории (workspace), в которой репозитории лежат рядом. Claude Code читает CLAUDE.md workspace-уровня и вложенные CLAUDE.md репозиториев, когда трогает файлы в них.

Раскладка

~/work/arm-ka/                         ← workspace: НЕ git. Отсюда запускается `claude`
├── CLAUDE.md                          ← общий контекст (этот пакет) + карта репозиториев
├── docs/            → git: arm-ka-docs           контекст, модель, контракты, экспорт ТЗ, макет
├── fixtures/        → git: arm-ka-fixtures       реальные данные (ОСВ, PDF, OCR-пары, эталон); отдельный репо,
│                                                   чтобы не тащить 50 МБ в сервисы и управлять доступом
├── arm-core/        → git: arm-core              ядро: FastAPI + React (монорепо по шаблону команды)
├── tabular-parser/  → git: arm-tabular-parser    сервис разбора XLS/XLSX/XLSB (ОСВ, ББ, ОФР)
├── scan-gateway/    → git: arm-scan-gateway      адаптер ИС Сканирование (PDF/PNG/JPG)
└── .claude/                           ← настройки workspace: хуки, разрешения (не в git или в arm-ka-docs/.claude-workspace)

Контракт между сервисами — docs/contracts/*.schema.json в arm-ka-docs. Изменение контракта = PR в docs и в каждый затронутый сервис, с одной schema_version.

Как агент работает с несколькими репозиториями

• Один change — один репозиторий. OpenSpec (openspec/) живёт в каждом сервисе. Сквозное изменение (контракт + два сервиса) оформляется как change в arm-ka-docs с ссылками на дочерние changes в сервисах.
• Ветки и коммиты — всегда git -C <repo> или с явным cd. Хук guard-main должен определять репозиторий по пути изменяемого файла (git -C "$(dirname "$FILE")" rev-parse --abbrev-ref HEAD), а не по cwd workspace.
• codegraph — по одному индексу на репозиторий; workspace-уровня карта кода не нужна.
• Относительные ссылки на контекст — из любого репозитория: ../docs/context/..., ../fixtures/.... Проверки (make check, make check-full) берут фикстуры из ../fixtures или ARM_KA_FIXTURES, docs — из ../docs или ARM_KA_DOCS; при отсутствии — пропуск с предупреждением. CI в Gitea нет; пайплайн платформы банка — вне репозиториев.
• Вложенные CLAUDE.md в каждом репозитории короткие: что это за сервис, его собственные соглашения, ссылка на ../CLAUDE.md и ../docs/. Шаблоны — docs/repo-templates/.
• Один claude-сеанс может править несколько репозиториев, но PR — по одному на репозиторий; в описании PR указывать связанные PR в других репозиториях.
• Worktree вместо веток в основном checkout. Хуки запрещают запись в main; работа идёт в worktree. Для среза, затрагивающего несколько репозиториев, worktree собираются в зеркальный workspace .wt/<срез>/ рядом с основным: docs/, arm-core/, tabular-parser/, scan-gateway/ — worktree веток feat/<issue>-<slug>, а fixtures/, reference-old-arm/, CLAUDE.md, .claude/ — симлинки на основной workspace. Так относительные ссылки ../docs, ../fixtures и хуки работают и в ветке. .wt/ в git не попадает (workspace — не репозиторий).

Шаблон команды: из нулевого коммита существующего репозитория

Шаблон не существует как отдельный репозиторий — это первый коммит действующего проекта. Извлекаем дерево нулевого коммита, не историю:

git clone --no-checkout <url-существующего-репо> /tmp/src
ROOTS=$(git -C /tmp/src rev-list --max-parents=0 HEAD); echo "$ROOTS"   # если несколько — выбрать нужный
git -C /tmp/src show --stat --format='%H %ad %s' $ROOT | head -40          # убедиться, что это шаблон
mkdir arm-core && git -C /tmp/src archive $ROOT | tar -x -C arm-core
cd arm-core && git init -b main
grep -rIl -E "(SECRET|PASSWORD|TOKEN)=" . --exclude-dir=.git | head        # проверить, что в шаблоне нет секретов
git add -A && git commit -m "chore: шаблон команды (из <repo>@${ROOT:0:8})"
git remote add origin <url-arm-core> && git push -u origin main

Для tabular-parser и scan-gateway — тот же шаблон, но без frontend/: после tar -x удалить фронт-часть и соответствующие таргеты в Makefile/CI; агент в Срезе 0 фиксирует, что именно вырезано, в CLAUDE.md сервиса.

Аналитика ещё не причёсана — как с этим работать

Страницы ТЗ в docs/source/tz/ — черновик в движении, не договор. Поэтому слои контекста разделены по стабильности:

Слой	Где	Статус	Правило для агента
Модель данных	docs/model/data-model-v5.19.dbml	стабильный, версионируется	единственный источник имён и структур
Правила домена	docs/context/05-domain-rules.md	курируемый — пишет человек/агент по итогам ревью	единственный вход алгоритмов в код; из ТЗ напрямую не кодируем
Открытые вопросы	docs/context/07-open-questions.md	живой реестр	каждое допущение в коде — ASSUMPTION(OQ-nn)
Экспорт ТЗ	docs/source/tz/	снимок на дату из docs/source/tz/_export.md	читать для контекста; расхождение с §05 → вопрос, не код
Конспект ТЗ	docs/source/tz/_digest.md	генерируется	что где лежит и что устарело

Процедура обновления, когда аналитик меняет Confluence (делает пользователь или агент по команде):

1. Новый экспорт в docs/source/tz/ целиком (не поштучно); в _export.md — дата и список изменённых страниц (diff --stat по git покажет сам).
2. Агент: git diff по docs/source/tz/ → для каждой изменённой страницы — что изменилось по существу (алгоритм, поле, порог, статус) → предложение правок в 05-domain-rules.md и 07-open-questions.md отдельным PR в arm-ka-docs.
3. Если правка затрагивает модель — сначала DBML (новая версия + changelog), потом §05, потом код.
4. Код, уже написанный по старому правилу, не переписывается молча: OpenSpec change с ссылкой на страницу ТЗ и дату.

Агент никогда не «улучшает» ТЗ сам и не правит docs/source/**.

Макет UI как референс

HTML-макет dkb_24.09.26 велик и целиком в контекст не помещается — и не должен. Используется трёхслойно:

1. docs/context/10-user-journey.md — пользовательский путь, извлечённый из макета в текст: экраны, переходы, действия, какие таблицы DBML за ними стоят. Это обязательная часть контекста агента для любого UI/API-среза.
2. docs/mockup/INDEX.md — индекс файлов макета: файл → экран → ключевые элементы → ANL-замечания. Генерируется scripts/mockup_index.py, правится руками. Агент ищет по индексу, а не grep'ает HTML.
3. docs/mockup/dkb_24.09.26/*.html — сами файлы. Правило: при работе над экраном открывать один HTML этого экрана (и его CSS при необходимости), не больше. Для React-компонентов макет — референс поведения и состава элементов, не источник вёрстки для копирования.

Если макет и ТЗ расходятся (ANL-034, ANL-035, ANL-036 …) — приоритет у 05-domain-rules.md/DBML, расхождение фиксируется в 07-open-questions.md.