Files
mtusi2026lab4/openspec/specs/code-knowledge-graph/spec.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- 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>
2026-10-20 17:32:33 +03:00

192 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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** список исключений перенесён, а граф собирается заново после
переноса