- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
Design
Context
Мотивация — proposal.md, требования — specs/code-knowledge-graph/spec.md.
Состояние до change:
- graphify на машине не установлен. uv 0.12 есть (
/opt/homebrew/bin/uv). - Хуков нет нигде: в
.git/hooks/только*.sample, вgit config --localнет merge driver, у проекта есть только.claude/settings.local.json,.claude/settings.jsonнет. .gitignoreи.dockerignoreне знаютgraphify-out.- ruff читает
.gitignore(respect-gitignoreпо умолчанию), аmake lintформатирует всё дерево, включая.claude/. - Правила из
.claude/rules/подгружаются только после Read файла изpaths:(AGENTS.md, «Где лежат инструкции», и глобальные инструкции пользователя).
У graphify 0.9.72 два способа строить граф (проверено при реализации,
исходник install.py, detect.py, запуски на этом репозитории):
CLI graphify update . |
скилл /graphify |
|
|---|---|---|
| код | AST через tree-sitter | AST через tree-sitter |
| markdown | структура: разделы — узлы, связь references раздела с символами кода из его текста |
семантика: субагенты сессии Claude Code извлекают концепты и обоснования |
.json, .yaml |
не разбирает | разбирает семантически |
| LLM и токены | нет, ~1 с | субагенты; ~200 тыс. токенов на полную сборку этого репозитория, ~60 тыс. на правку AGENTS.md |
| установка | uv tool install |
плюс скилл в .claude/skills/ |
Режимы не складываются: graphify update . заменяет семантические узлы
документов структурными.
Goals / Non-Goals
Goals:
- Установка, которую можно проверить на отсутствие побочных эффектов сравнением «до/после», а не на честном слове.
- Одна точка правды о том, когда агент спрашивает граф, а когда читает
файл, —
AGENTS.md. - Схема в
REPORT.md, которую проверяющий видит в PR без сторонних инструментов.
Non-Goals:
- Цель в
Makefileдля графа: команда одна и не требует параметров. - MCP-сервер graphify: пример из README слушает порт 8080, это порт
приложения и
make test. - Обновление графа в CI или на коммит.
Decisions
1. Только CLI через uv tool с закреплённой версией
uv tool install --python 3.12 'graphifyy==0.9.72' ставит CLI в
изолированное окружение ~/.local/share/uv/tools/: .venv и uv.lock
проекта не меняются. --python 3.12 обязателен: без него uv берёт
free-threaded 3.14t, под который у tree-sitter-rust нет wheels, и
установка падает на сборке из исходников. Версия записана в AGENTS.md.
Скилл, install и хуки не используются. Что делает
graphify install --project для Claude Code (_project_install →
install() + claude_install()):
| Что | Куда |
|---|---|
| скилл | .claude/skills/graphify/ |
| блок регистрации скилла | новый .claude/CLAUDE.md |
секция ## graphify: «first run graphify query», «after modifying code, run graphify update .» |
корневой CLAUDE.md проекта |
PreToolUse-хуки на Bash|Grep и Read|Glob |
новый .claude/settings.json |
Флага «без хука» нет. Хук и секция противоречат требованиям «Установка без побочных эффектов» и «Граф не заменяет чтение файла перед правкой».
Альтернативы:
graphify installбез флагов — отклонено: меняет глобальныеCLAUDE.mdиsettings.json, то есть все проекты пользователя, и ставит хук.- Скилл копированием без
install(_copy_skill_file) — был реализован и отклонён, см. решение 3a. pip installв.venvпроекта — отклонено: инструмент попал бы в зависимости сервиса и вuv.lock.- Без версии — отклонено: следующая версия может поменять поведение CLI.
2. Проверка побочных эффектов снимком «до/после»
Перед установкой в scratchpad сессии (вне репозитория) сохраняются:
- копии
~/.claude/CLAUDE.md,~/.claude/settings.json,.claude/settings.local.jsonиsha256всех трёх; - список
~/.claude/skills/,.claude/,.git/hooks/; git config --local --list;sha256 uv.lock;git status --short --ignored;- копии файлов, которые правит change: рабочее дерево на момент снимка
содержало незакоммиченные правки
container-runtime, иgit diffне отделил бы их.
После установки снимок повторяется и сравнивается. Разрешённые отличия:
graphify-out/ среди игнорируемых, .graphifyignore и правки файлов
из раздела Impact в proposal.md. Любое другое отличие — остановиться и
показать пользователю.
3. Состав графа: .graphifyignore поверх .gitignore
Граф строится по корню. .gitignore уже убирает .env, config.toml,
.venv, кэши. .graphifyignore добавляет исключения из требования
«Состав графа». Выяснилось при реализации:
- Синтаксис gitignore: паттерн без
/совпадает на любой глубине, иREADME.mdвыкинул быcontracts/README.md. Все паттерны привязаны к корню ведущим/. - graphify читает только
.gitignoreвнутри репозитория, но не глобальныйcore.excludesfile..claude/settings.local.jsongit игнорирует через~/.config/git/ignore, поэтому он исключён явно. requirements-dev.txt— файл skeleton, исключён вместе с остальными.- CLI не разбирает
.json,.yaml/.yml,Dockerfile,Makefileи шаблоны конфигов (CODE_EXTENSIONS/DOC_EXTENSIONSвdetect.pyи структурный разбор только markdown).contracts/openapi.json,docker-compose.ymlиopenspec/config.yamlв граф не попадают. По ним агент ищетgrep. Требование сужено с согласия пользователя.
Итог (сборка с нуля): 616 узлов, 985 связей; источники — src/,
pyproject.toml, .claude/rules/, AGENTS.md, CLAUDE.md,
KNOWN_ISSUES.md, contracts/README.md, openspec/specs/; ни одного
пути из списка MUST NOT.
3a. Почему отказались от скилла и семантического разбора
Первая реализация: скилл скопирован в .claude/skills/graphify/ без
install, граф собран /graphify ., документы разобраны двумя
субагентами (~203 тыс. токенов). Результат:
- между кодом и правилами/спеками одна связь, и та ложная
(
logger.py —imports→ logging.md): субагенты не знают ID узлов AST и описывают символы кода своими концептами; graphify update .(им обновляли граф после правок кода) заменил все семантические узлы документов структурными — разбор агентами из графа пропал;- структурный разбор CLI, наоборот, дал 33 связи «документ → код»
(25 от правил, 5 от спек, 3 от
AGENTS.md), например раздел «Слой service» →ChatNotFound, «Requirement: Создание чата» →Chat.
То есть связи правил и спек с кодом — главная польза документов в графе
— даёт бесплатный CLI, а платный семантический разбор их не даёт и
стирается при первом update. Пользователь выбрал только CLI. Скилл
удалён из репозитория, вместе с ним ушли риски его автоподгрузки
(широкий description), самостоятельного uv tool install --upgrade
и «Answer using only what the graph contains».
Запросы: query ищет узлы по подстроке метки. Запрос именами символов
("ChatService ChatNotFound chat") находит код, раздел правила
service-layer.md и спеку chats по реальным связям. Запрос пересказом
(«chat service member access») эвристика сужает до нескольких узлов
кода. Совет записан в AGENTS.md.
4. Когда граф, когда Read: правило в AGENTS.md
В «Где лежат инструкции» — четвёртый уровень, граф. По смыслу: граф
для вопросов о структуре и связях (query, path, explain,
affected), он подсказка и может отставать от кода; перед правкой —
Read файла, иначе правило слоя не подгрузится; связи документов с кодом
частичные, полная карта — paths: и таблица правил; в запрос — имена
символов; что граф не видит; только graphify update ., без скилла,
extract, install, хуков и watch.
Альтернатива — PreToolUse-хук graphify. Отклонено: хук подталкивает к графу перед поиском и вытесняет Read, а вместе с ним подгрузку правил.
5. Сборка и обновление графа
Одна команда graphify update . в корне и для первой сборки, и для
обновлений: без LLM, ~1 с, работает в чистом clone (проверено на копии
git ls-files в scratchpad: 616 узлов, те же 33 связи). Вручную, после
заметной работы. Без watch и git-хуков.
Побочные эффекты update (0.9.72), все внутри игнорируемого
graphify-out/: копия прошлого графа в graphify-out/<дата>/, имена
кластеров по центральному узлу.
6. Схема в REPORT.md: Mermaid, сверенный с кодом
Поток — отправка сообщения: он проходит все слои и показывает вызов одного сервиса из другого.
graphify export callflow-html даёт Mermaid, но не подходит: секции на
сотни узлов, тёмная тема, HTML-метки, заголовки секций не о проекте.
Схема нарисована вручную. Из графа (AST) взяты узлы и часть связей:
MessageService → ChatService, get_message_service →
MessageService, repo → MemoryStore. Вызовы через зависимости
FastAPI (messages.send_message(...)) и через псевдоним модуля
(message_repo.insert_message(...)) AST не видит — они добавлены по
коду. Все 13 стрелок сверены с кодом через Read, 11 узлов.
Схема стоит в «Архитектуре и решениях» после «Процессы и хранилище», подзаголовком «Слои кода». В строке «помощь ИИ» — graphify (граф без LLM) и то, что схему нарисовал Claude Code и сверил с кодом.
7. Git и Docker
.gitignore:graphify-out/в секции артефактов..dockerignore:graphify-outрядом со своими исключениями (.claude,openspec). Паттерн без**/действует только в корне контекста, а граф лежит в корне (docker.md)..graphifyignoreкоммитится.
Risks / Trade-offs
- [Агент доверится устаревшему графу] → в
AGENTS.mdграф назван подсказкой, а правка всегда идёт после Read текущего файла. - [Связи «документ → код» только по упоминаниям] → раздел без символа в
обратных кавычках с кодом не связан; полная карта —
paths:правил. - [Запрос пересказом находит мало] → совет в
AGENTS.md: имена символов. - [Файлы
.json/.yaml,Dockerfile,Makefileвне графа] →grep. - [На лабе 1 польза для навигации невелика: 51 файл; отчёт graphify сам пишет, что корпус помещается в контекст] → принято осознанно: настройка переезжает в следующие лабы, где кода больше.
- [Mermaid-схема разойдётся с кодом в следующих лабах] →
REPORT.mdне переносится (AGENTS.md), схема строится заново. - [Смена версии graphify поменяет поведение CLI] → версия закреплена.
Migration Plan
Установка — задачи в tasks.md. Откат целиком:
uv tool uninstall graphifyy.- Удалить
.graphifyignoreиgraphify-out/. - Убрать строки
graphify-outиз.gitignoreи.dockerignore, пункт о графе и команды graphify изAGENTS.md, схему и упоминание изREPORT.md.
Код сервиса не затрагивается, поэтому откат не требует пересборки образа и повторных проверок API.