Files
mtusi2026lab4/openspec/changes/archive/2026-09-30-graphify/proposal.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- carry the lab 3 solution over from mtusi2026lab3-safronov
  (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests,
  bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts,
  Dockerfile, compose, pyproject and uv lock
- merge Makefile, .gitignore and .dockerignore (the lab 3 versions only
  add lines to the skeleton, which is the same in lab 4) and
  .env.example (lab 4 skeleton names listed in the header)
- rename the compose project to mtusi-lab4 and the image to :lab4 so
  the stand does not reuse the lab 3 containers and volumes
- update AGENTS.md for lab 4: current lab, origin commit, contract and
  test files of the new skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 17:32:33 +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 дописывает свои строки поверх его версии.