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>
This commit is contained in:
2026-10-31 03:09:12 +03:00
co-authored by Claude Opus 5.5
parent 276dbdad8a
commit 04f859282d
479 changed files with 106103 additions and 24 deletions
+191
View File
@@ -0,0 +1,191 @@
# 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** список исключений перенесён, а граф собирается заново после
переноса