Files
mtusi2026lab3/openspec/changes/archive/2026-09-30-graphify/design.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- 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>
2026-10-08 19:42:36 +03:00

15 KiB
Raw Blame History

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.json git игнорирует через ~/.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. Откат целиком:

  1. uv tool uninstall graphifyy.
  2. Удалить .graphifyignore и graphify-out/.
  3. Убрать строки graphify-out из .gitignore и .dockerignore, пункт о графе и команды graphify из AGENTS.md, схему и упоминание из REPORT.md.

Код сервиса не затрагивается, поэтому откат не требует пересборки образа и повторных проверок API.