Files
mtusi2026lab3/openspec/changes/archive/2026-09-30-graphify/proposal.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

5.9 KiB
Raw Blame History

Proposal

Why

Агент узнаёт устройство проекта из AGENTS.md, правил слоёв и чтения файлов по одному. Сейчас этого хватает: 51 файл в src/. К лабам 5–7 добавятся БД, S3, брокер, worker и телеметрия. На вопросы вида «кто вызывает X», «что затронет правка Y» и «какое правило или спека описывает этот модуль» агент начнёт отвечать дорого и с пропусками. Для отчёта и защиты не хватает схемы устройства кода: раздел «Архитектура» в REPORT.md описывает процессы и хранилище словами, а слои api → service → repo → infra нигде не нарисованы.

graphify строит по репозиторию граф: код разбирается по AST через tree-sitter, markdown — по структуре разделов, без LLM и токенов. Граф решает обе задачи. Ставить его нужно так, чтобы он ничего не ломал в текущем порядке работы. Главное — правила из .claude/rules/ подгружаются только после Read файла, и граф не должен подменять этот Read.

What Changes

  • Установка. Только CLI graphify через uv tool install с закреплённой версией. Скилл /graphify, graphify install, хуки Claude Code, git-хуки, merge driver и graphify watch не используются (design.md, решения 1 и 3a).
  • Состав графа. Код src/, pyproject.toml и документы, которые описывают код: AGENTS.md, CLAUDE.md, .claude/rules/, openspec/specs/, contracts/README.md, KNOWN_ISSUES.md. Разделы документов связаны с символами кода, упомянутыми в их тексте. Через .graphifyignore исключаются проверки и заготовки skeleton, инструментарий агента, изменения OpenSpec, отчёт, доказательства и документы курса.
  • Артефакты графа не публикуются. graphify-out/ целиком в .gitignore и .dockerignore. Граф собирается и обновляется вручную одной командой graphify update . после заметной работы.
  • Порядок работы агента. В AGENTS.md появляется правило: граф — для вопросов о структуре и связях, а перед правкой файл по-прежнему читается через Read, чтобы подгрузилось правило слоя.
  • Схема для отчёта. В раздел «Архитектура и решения» REPORT.md добавляется Mermaid-схема слоёв кода и одного потока вызовов (отправка сообщения), сверенная с кодом. Runtime-схема остаётся отдельно. Строка «помощь ИИ» в REPORT.md упоминает graphify.
  • Проверка, что ничего не сломано. Глобальные настройки Claude Code, git-хуки, uv.lock, make lint, make check и сборка образа до и после установки дают одинаковый результат. На живом агенте проверяется, что правило слоя по-прежнему подгружается.
  • Не входит: скилл /graphify и семантический разбор документов через LLM, MCP-сервер graphify, автообновление графа, публикация graph.json / graph.html, экспорт в Obsidian и wiki.

Capabilities

New Capabilities

  • code-knowledge-graph: граф знаний проекта для агента и для отчёта — что в него входит, где лежат артефакты, как он обновляется, каких побочных эффектов у установки быть не должно и как граф сочетается с подгрузкой правил слоёв.

Modified Capabilities

Нет. Поведение сервиса не меняется, а существующие спеки описывают только API, хранение, конфигурацию, логи и контейнер.

Impact

  • Новые файлы: .graphifyignore, локальный graphify-out/ вне git.
  • Изменяемые файлы:
    • .gitignore, .dockerignore — строка graphify-out;
    • AGENTS.md — правило использования графа, команды установки и обновления, .graphifyignore в списке переносимого в следующую лабу;
    • REPORT.md — Mermaid-схема в «Архитектуре», graphify в строке про ИИ.
  • Код приложения, контракт, тесты, Dockerfile и Makefile не меняются.
  • Окружение: uv (уже есть), graphify CLI в изолированном окружении uv tool. Токены на сборку и обновление графа не тратятся.
  • Зависимость от порядка: после container-runtime. Он уже в архиве и тоже правил .dockerignore и REPORT.md, поэтому этот change дописывает свои строки поверх его версии.