# 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 `** или с явным `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/-`, а `fixtures/`, `reference-old-arm/`, `CLAUDE.md`, `.claude/` — симлинки на основной workspace. Так относительные ссылки `../docs`, `../fixtures` и хуки работают и в ветке. `.wt/` в git не попадает (workspace — не репозиторий). ## Шаблон команды: из нулевого коммита существующего репозитория Шаблон не существует как отдельный репозиторий — это первый коммит действующего проекта. Извлекаем дерево нулевого коммита, не историю: ```bash git clone --no-checkout /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: шаблон команды (из @${ROOT:0:8})" git remote add origin && 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.14.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`.