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