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