- 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>
11 KiB
code-knowledge-graph Specification
Purpose
Граф знаний репозитория: агент по нему отвечает на вопросы о структуре и связях кода, а в отчёт из него берётся схема слоёв. Граф ничего не меняет в работе проекта и в том, как подгружаются правила слоёв.
Requirements
Requirement: Состав графа
Граф SHALL строиться без LLM по коду src/ и по документам, которые
описывают код: AGENTS.md, CLAUDE.md, .claude/rules/,
openspec/specs/, contracts/README.md, KNOWN_ISSUES.md, а также по
pyproject.toml. Файлы, которые инструмент графа не разбирает
(.json, .yaml/.yml, Dockerfile, Makefile, шаблоны конфигов),
в граф не попадают. Это известное ограничение, а не ошибка состава.
В граф MUST NOT попадать:
- публичные проверки, скрипты и заготовки skeleton:
tests/,scripts/,examples/,Dockerfile.example,lab.json,requirements-dev.txt,contracts/examples.json,contracts/infrastructure.json; - инструментарий агента:
.claude/commands/,.claude/skills/,.claude/settings.local.json; - изменения OpenSpec, текущие и архивные:
openspec/changes/; REPORT.md,evidence/и документы курса:README.md,COURSE.md,CONTRIBUTING.md,MAINTAINERS.md,.github/;- всё, что исключено в
.gitignore, в том числе.env,config.toml,.venv.
Список исключений SHALL храниться в файле репозитория, а не в памяти агента.
Раздел документа SHALL быть связан с символом кода, если символ упомянут
в тексте раздела. Полнота таких связей MUST NOT считаться
гарантированной: раздел без упоминания символа с кодом не связан. Точная
карта «правило слоя → файлы кода» — поле paths: в правилах
.claude/rules/ и таблица в AGENTS.md, а не граф.
Scenario: Запрос находит код и документы
- WHEN агент спрашивает граф о сервисе чатов по именам символов
(
ChatService,ChatNotFound) - THEN в ответе есть узел из
src/core/services/, раздел правила из.claude/rules/и раздел спеки изopenspec/specs/
Scenario: Исключённое отсутствует
- WHEN в графе ищутся узлы из
tests/,scripts/,.claude/commands/,.claude/skills/иopenspec/changes/ - THEN таких узлов нет
Scenario: Конфигурация связана с настройками
- WHEN агент спрашивает граф, где используется порт приложения
- THEN в ответе есть модуль настроек из
src/config/и раздел правила или спеки о запуске
Scenario: Секреты не попадают в граф
- WHEN в корне лежат
.envиconfig.toml - THEN в артефактах графа нет ни их содержимого, ни узлов для них
Requirement: Артефакты графа локальные
Каталог с артефактами графа SHALL быть исключён из git и из контекста сборки образа. Граф MUST NOT попадать в коммиты, PR и образ; в отчёт из него переносится только схема (требование «Схема кода в отчёте»).
Scenario: git не видит граф
- WHEN граф собран, и выполняется
git status --ignored - THEN каталог графа виден только среди игнорируемых, а среди новых и изменённых файлов его нет
Scenario: Образ без графа
- WHEN после сборки графа собирается образ сервиса
- THEN каталог графа не передаётся в контекст сборки, и состав образа не меняется
Requirement: Установка без побочных эффектов
Установка инструмента графа SHALL затрагивать только файлы этого репозитория, перечисленные в change, и изолированное окружение самого инструмента. Установка MUST NOT:
- менять глобальные инструкции и настройки Claude Code пользователя;
- добавлять хуки Claude Code, скиллы и инструкции агенту от инструмента в настройки проекта или пользователя;
- добавлять git-хуки, merge driver и другие правки git-конфигурации;
- менять окружение и lock-файл зависимостей проекта;
- менять результат
make lint,make checkи сборки образа.
Scenario: Глобальные настройки не тронуты
- WHEN до и после установки сравниваются глобальные файл инструкций и файл настроек Claude Code пользователя
- THEN содержимое совпадает
Scenario: Нет хуков
- WHEN после установки просматриваются настройки Claude Code проекта, каталог git-хуков и git-конфигурация репозитория
- THEN новых хуков, merge driver и записей о графе в них нет
Scenario: Проект собирается как раньше
- WHEN после установки выполняются
make lintиmake check - THEN
make lintне меняет файлов,make checkпроходит, lock-файл зависимостей без изменений
Requirement: Граф не заменяет чтение файла перед правкой
Инструкции агента SHALL разделять роли: граф — для вопросов о структуре и связях («где используется», «кто вызывает», «какое правило описывает модуль»), а перед правкой файл MUST читаться целиком, как без графа, чтобы подгрузилось правило слоя.
Scenario: Правило слоя подгружается при правке
- WHEN в новой сессии агента просят изменить файл в
src/core/services/ - THEN агент читает этот файл перед правкой, и правило сервисного слоя попадает в его контекст
Scenario: Вопрос о связях
- WHEN агента спрашивают, какие модули зависят от хранилища в памяти
- THEN агент может ответить по графу, не открывая файлы по одному
Requirement: Обновление графа вручную
Граф SHALL собираться и обновляться только по явной команде, без обращений к LLM, за секунды, в том числе в чистом clone. Коммиты, переключение веток и изменения файлов MUST NOT запускать пересборку.
Scenario: Коммит не пересобирает граф
- WHEN в репозитории делается коммит
- THEN артефакты графа не меняются
Scenario: Новый модуль после обновления
- WHEN в
src/добавлен модуль, и выполнена команда обновления - THEN модуль есть в графе, а команда не обращалась к LLM
Scenario: Сборка в чистом clone
- WHEN в clone без каталога графа выполняется команда обновления
- THEN граф собирается целиком
Requirement: Схема кода в отчёте
Раздел «Архитектура и решения» в REPORT.md SHALL содержать схему
слоёв кода (api → service → repo → хранилище) и поток вызовов одной
операции — отправки сообщения — в виде блока Mermaid, который GitHub
показывает как диаграмму. Каждая связь на схеме MUST существовать в
коде. Описание процессов и хранилища в отчёте SHALL остаться: схема кода
его дополняет, а не заменяет. В отчёте SHALL быть указано, как схема
получена и какую роль в этом сыграл инструмент графа.
Scenario: Схема видна в PR
- WHEN проверяющий открывает
REPORT.mdна GitHub - THEN схема отображается диаграммой, а не текстом
Scenario: Схема соответствует коду
- WHEN каждая стрелка схемы сверяется с кодом
- THEN для каждой есть реальный импорт или вызов между указанными модулями
Scenario: Использование ИИ указано
- WHEN проверяющий читает, какая помощь ИИ использовалась
- THEN там названы инструмент графа и то, для чего он применялся
Requirement: Перенос в следующую лабу
Список исключений графа SHALL переноситься в следующую лабу вместе с инструкциями агента. Артефакты графа MUST NOT переноситься: в новом репозитории граф собирается заново.
Scenario: Новая лаба
- WHEN решение переносится в skeleton следующей лабы по
AGENTS.md - THEN список исключений перенесён, а граф собирается заново после переноса