Перед добавлением функции найдите место её подключения и изучите похожие реализации. Сценарий помогает разработчику проследить вызывающий код и выбрать точки интеграции для согласованной задачи. Результат исследования используйте при подготовке изменения и регрессионных тестов. До запуска согласуйте пользовательский результат, область работы и критерии приёмки.
Как сценарий находит точки интеграции
Сценарий помогает найти в существующем коде место для новой функции. Сначала он проверяет, есть ли готовый ответ на такой запрос. Для остальных запросов он ищет точки расширения в проекте и CPG — графе свойств кода.
Поиск использует категорию изменения, ключевые слова запроса и имена функций. Анализ графа вызовов находит возможные точки интеграции и связанные функции. При поиске по графу сценарий передаёт эти результаты в LLM как контекст; ответ подсказывает, где изучить исходный код перед планированием изменения.
Например, перед добавлением нового формата экспорта сформулируйте запрос: «Найди обработчик экспорта, регистрацию форматов и вызывающий код. Покажи, где подключить новый формат и какие тесты затронет изменение». Укажите в file_paths существующие файлы обработчика и тестов, а в source_refs — контракт нового формата. Это пример постановки задачи; подставьте названия и пути своего проекта.
Читайте результат вместе с исходниками: найдите предложенную функцию, проследите её вызывающий код и сопоставьте интерфейс с критерием приёмки. После выбора точки интеграции переходите к циклу реализации от теста.
Обязательный контекст задачи
В принятой задаче зафиксируйте область работы, владельца, критерии приёмки и свидетельства. До изменения кода укажите:
- пользовательский результат и исключения;
- проверяемые
acceptance_criteria; - текущую ревизию и ограниченный набор
file_paths; - относящиеся к задаче
source_refs, тесты и интерфейсные контракты; - необходимые ревью и проверки перед выпуском;
- порядок отката или восстановления для рискованного поведения.
Если этих данных нет, продолжайте планирование и исследование без изменения промышленного кода.
Типизированный запрос на исследование
Подготовьте локальное окружение по руководству CLI и настройте проект, граф и LLM-провайдер по руководству по программному вызову. Запускайте Python из корня репозитория CodeGraph в этом окружении. Подготовьте CPG для нужной ревизии по разделу «Подготовка проекта».
Пример ниже — шаблон запроса для существующей задачи. Замените codegraph, default и <task-id> на её точную область. В <criterion> укажите согласованный критерий приёмки, а в <implementation-path> и <test-path> — существующие пути относительно корня проекта. Замените ссылку source_refs на доступный контракт задачи. Эти значения не создают задачу и не дают разрешения на изменение кода.
Создайте запрос с помощью RoleBoundScenarioInvocationRequest и вызовите функцию invoke_role_bound_scenario_request:
from src.digital_employees.runtime.scenarios import (
RoleBoundScenarioInvocationRequest,
invoke_role_bound_scenario_request,
)
request = RoleBoundScenarioInvocationRequest(
query="Найди точки интеграции и регрессионные риски для согласованного среза функции.",
employee_id="codegraph_developer",
scenario_id="scenario_04",
event_type="implementation_start",
context={
"project_key": "codegraph",
"namespace": "default",
"task_id": "<task-id>",
"acceptance_criteria": ["<criterion>"],
"file_paths": ["<implementation-path>", "<test-path>"],
"source_refs": ["openspec/changes/<change-id>/specs/<capability>/spec.md"],
},
)
result = invoke_role_bound_scenario_request(request)
if result.get("error"):
raise RuntimeError(result["error"])
print(result["scenario_id"])
print(result.get("answer") or "")
Для вызова нужны непустые значения project_key, namespace и task_id. Если одного из них нет, функция выбрасывает RuntimeError с сообщением role_bound_scenario_contract_missing. Вызов возвращает контекст исследования и метаданные ролевого вызова. Он не изменяет файлы; для правок используйте отдельный процесс реализации.
Ожидайте scenario_04 и ответ по выбранной функции. Проверьте metadata.role_bound_scenario_invocation, ссылки на исходники и их соответствие текущей ревизии. Если вызов вернул ошибку или не ответил на запрос, сохраните сообщение и устраните причину до приёмки. Подготовьте CPG для текущей ревизии, прежде чем полагаться на ответ.
Для отрицательной проверки передайте context={}: вызов должен выбросить RuntimeError с role_bound_scenario_contract_missing до исследования. Восстановите точную область задачи перед повторным запуском.
Цикл реализации от теста
- Проверьте ревизию задачи и изучите минимально необходимые исходники, тесты и вызывающий код.
- Свяжите ожидаемое поведение с одним или несколькими критериями приёмки.
- Добавьте точечный тест, воспроизводящий отсутствующее поведение или дефект, и получите RED по ожидаемой причине.
- Внесите минимальное изменение кода или конфигурации, которое даёт GREEN.
- Запустите точечный тест, соседние регрессионные тесты, а также lint и проверку типов для затронутой поверхности.
- Проверьте изменённые символы, вызывающий код, контракты хранения и API, границы авторизации и влияние на публичную документацию.
- Зафиксируйте для каждого критерия привязанные к ревизии команды, результаты и ссылки на свидетельства.
Не расширяйте патч только потому, что граф показал соседний технический долг. Запишите несвязанные находки отдельно.
Что должно вернуть полезное исследование
Результат должен различать:
- подтверждённые точки интеграции и ранжированные кандидаты;
- текущие вызывающие функции и связи между компонентами;
- похожие реализации, которые можно проверить для повторного использования;
- файлы в области задачи и файлы, которые лишь могут быть затронуты;
- вопросы, на которые пока нет ответа, ограничения актуальности и недостающие полномочия;
- оставшиеся точечные тесты и ревью.
Центральность или похожесть в графе помогают найти код для проверки, но не подтверждают архитектурное решение. Перед реализацией проверьте предложение по текущим исходникам и тестам.
Условия остановки
Остановите реализацию и вернитесь к владельцу задачи, если согласованное поведение неоднозначно, нужен новый API или другой пользовательский интерфейс, изменилась ревизия, необходимый путь выходит за область задачи или затрагиваются несогласованные права доступа. До продолжения уточните область файлов и нужное согласование.
Связанные материалы
Подробности запроса приведены в руководстве по программному вызову. Для нового репозитория сначала пройдите знакомство с кодовой базой, а затем выбирайте срез реализации.