70ba5e9db8
- model/entities-v5.14.md: таблица «Что изменилось в v5.14», related_group_member (ГСК и ГСЗ одновременно), audit_event - context/04: файлы и partial unique (legal_entity_id, kind) v5.14, OQ-31/32 закрыты - ссылки на v5.14: 00, 03, 05, KICKOFF-PROMPT, dev/checks.md, openspec/config.yaml, repo-templates/arm-core.CLAUDE.md - 09: Срез 1 по факту (вариант Б), перенос UI справочника; 10: статус экранов справочника и /admin - 08: выгрузка ЕЦП; 06: §6.1 фикстура directories/ecp-export-russkiy-biskvit.xlsx - 05 §13: сверка с ImportCode (добавлен GSZ_CREATED, перечень 16 кодов), порядок проверок, уточнения реализации, лимиты файла, ошибки файла, след в аудите и S3 - tasks.md: 2.1–2.3, 3.1 выполнены Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2
101 lines
10 KiB
Markdown
101 lines
10 KiB
Markdown
# 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 — не репозиторий).
|
||
|
||
## Шаблон команды: из нулевого коммита существующего репозитория
|
||
|
||
Шаблон не существует как отдельный репозиторий — это первый коммит действующего проекта. Извлекаем дерево нулевого
|
||
коммита, не историю:
|
||
|
||
```bash
|
||
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.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`.
|