Files
mtusi2026lab5/openspec/specs/code-knowledge-graph/spec.md
T
ricoromaandClaude Opus 5.5 04f859282d chore: port lab 4 solution into the lab 5 skeleton
Source: mtusi2026lab4-safronov, solution/bvt2301-safronov, 2546deb.
Contracts, public tests and evidence of lab 4 are not carried over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 03:09:12 +03:00

11 KiB
Raw Blame History

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 список исключений перенесён, а граф собирается заново после переноса