Feature Chain — Отслеживание всего стека по одному operationId

Какие файлы нужно изменить, чтобы модифицировать одну функциональность? Вводишь один operationId — появляется ответ.

Проблема

В full-stack-приложении «одна функциональность» не живёт в одном файле.

Допустим, нужно изменить функциональность «ExecuteWorkflow». Эта функциональность есть в API-спецификации, в сервисной логике, в схеме базы данных, в политике авторизации, в диаграмме переходов состояний, в вызовах внешних функций, в тестовых сценариях и в компонентах фронтенда.

Исторически есть два способа охватить весь этот объём:

  1. Запустить grep десятки раз
  2. Пройти код вручную

Оба медленные, и оба пропускают что-нибудь. Особенно межслойные ссылки — из API-спецификации в сервис, из сервиса в схему БД, из сервиса в политику авторизации — человеку практически невозможно отследить полностью.

Когда правку отдают ИИ, становится ещё хуже. На 200 эндпоинтах ИИ уже не удерживает контекст целиком. Контекст рушится, паттерны дрейфуют, и 201-я функциональность стоит в 10 раз дороже 21-й. Это стена, в которую упирается vibe coding.

Но если исходник каждого слоя символически ссылается на другие слои, достаточно пройти по этим ссылкам — и весь объём раскрывается автоматически.

Что такое Feature Chain

Feature Chain — это множество всех исходных узлов, связанных с одной API-функциональностью (operationId).

Начиная с одного operationId, он идёт по символическим ссылкам между источниками и выводит разом все связанные файлы и номера строк. Десятки grep заменяются одной командой.

yongol chain ExecuteWorkflow specs/

── Feature Chain: ExecuteWorkflow ──

  OpenAPI    api/openapi.yaml                         POST /workflows/{id}/execute
  SSaC       service/workflow/execute_workflow.ssac   @get @empty @auth @state @call @publish @response
  DDL        db/workflows.sql                         CREATE TABLE workflows
  DDL        db/execution_logs.sql                    CREATE TABLE execution_logs
  Rego       policy/authz.rego                        resource: workflow
  StateDiag  states/workflow.md                       diagram: workflow → ExecuteWorkflow
  FuncSpec   func/billing/check_credits.go            @func billing.CheckCredits
  FuncSpec   func/billing/deduct_credit.go            @func billing.DeductCredit
  FuncSpec   func/worker/process_actions.go           @func worker.ProcessActions
  FuncSpec   func/webhook/deliver.go                  @func webhook.Deliver
  Hurl       tests/scenario-happy-path.hurl           scenario: scenario-happy-path.hurl

Полная структура функциональности помещается на одном экране. Несвязанные слои не выводятся.

Почему это возможно

Это не магия. Возможно потому, что исходники уже ссылаются друг на друга.

В фреймворке yongol каждый слой SSOT (Single Source of Truth) символически указывает на другие слои:

  • @get Model.Method в SSaC → таблица DDL
  • @auth action resource в SSaC → политика авторизации Rego
  • @state diagramID в SSaC → диаграмма состояний Mermaid
  • @call pkg.Func в SSaC → реализация FuncSpec
  • @publish "topic" в SSaC → функции, подписанные на тот же topic
  • operationId в OpenAPI → имя файла SSaC
  • Сценарий Hurl → эндпоинт OpenAPI
  • apiClient.<op>() в React TSX → operationId OpenAPI

Эти ссылки изначально создавались для yongol validate — этапа, на котором перекрёстно проверяется согласованность 9 SSOT до компиляции. Поскольку validate уже их парсит, повторное использование той же инфраструктуры превращает извлечение feature chain в обход графа.

Маршрут обхода

Если взять operationId за отправную точку, граф ссылок разворачивается так:

operationId (точка входа)
├── OpenAPI → path + method
├── SSaC → файл сервисной функции
│   ├── @get → таблицы DDL
│   ├── @auth → правила политики Rego
│   ├── @state → переходы Mermaid stateDiagram
│   ├── @call → реализации FuncSpec
│   └── @publish → подписчики очереди
├── Hurl → тестовые сценарии, ссылающиеся на operationId
└── React TSX → фронтенд-файлы, вызывающие эндпоинт через apiClient

Каждая ветвь проходит ровно один шаг символической ссылки. Это обход в ширину, а не в глубину. Каждый слой, в котором функциональность оставляет след, проявляется.

Что это меняет

Оценка области правки

«Где тронуть, чтобы изменить эту функциональность?»

Чтобы ответить, мы читаем код, запускаем grep, спрашиваем коллегу. Feature Chain заменяет вопрос одной командой. Ни один файл не проскальзывает — пока существует символическая ссылка.

Правка силами ИИ

Самое сложное при делегировании правки ИИ — сказать ему, «какова область правки». ИИ способен корректно редактировать, только когда релевантные файлы лежат в его контексте, а решать, какие из них релевантны, приходится человеку.

С Feature Chain иначе. Даёшь один operationId — и вся область определяется автоматически. Контекст для ИИ готовится без пропусков. Поскольку 9 SSOT — это декларативные спецификации, куда более компактные, чем сгенерированный Go-код, — вся цепочка помещается в окно контекста с запасом.

Code review

При ревью PR: «если они тронули эту функциональность, не должен ли измениться и тот файл?» — проверяется тривиально: достаточно сверить с цепочкой. Несогласованность между слоями ловит структура, а не люди.

Онбординг

Когда новый разработчик говорит «я хочу понять, как работает ExecuteWorkflow», — покажи ему Feature Chain. От API до БД, от политики авторизации до тестовых сценариев — весь ландшафт функциональности на одном экране.

Почему именно operationId

Выбор точки входа важен. Feature Chain выбрал operationId.

Причина проста. В full-stack-приложении единица функциональности — это API-эндпоинт. Пользователь нажимает кнопку, вызывается API, отрабатывает сервисная логика, читается БД, проверяется авторизация, происходят переходы состояний. Начало всего этого потока — operationId.

operationId уже определён в спецификации OpenAPI и является именем, общим для всей команды. Сказав «надо изменить ExecuteWorkflow», и бэкенд-инженер, и фронтенд-инженер, и QA думают об одном и том же. Feature Chain устроен вокруг этого универсального имени как нити, прошивающей весь стек.

yongol называет это «operationId — замковый камень (keystone)». Один идентификатор в PascalCase физически связывает 9 слоёв.

Предпосылки

Чтобы Feature Chain работал, есть предположения:

  1. Источники должны символически ссылаться друг на друга. Директивы @get, @auth, @state, @call, @publish в SSaC должны явно указывать на другие SSOT. Если ссылка неявная — например, имя таблицы БД существует только как строка внутри кода — её невозможно отследить.

  2. yongol validate должен проходить. Feature Chain идёт по символическим ссылкам; если ссылки невалидны, результат будет неверным. validate гарантирует целостность ссылок; Feature Chain обходит поверх этого.

Вот почему Feature Chain — не универсальный инструмент. Его нельзя применить к произвольному проекту. Он работает только в проектах, где межисходные ссылки заложены по дизайну — в структурах вроде yongol, где SSOT явно указывают друг на друга.

Будущее: GEUL + SILK

Сегодня Feature Chain обходит, поочерёдно вызывая каждый парсер SSOT. Он вызывает парсер SSaC, DDL, Rego, Mermaid, Hurl и TSX — и затем комбинирует результаты.

Когда все SSOT будут переведены в граф GEUL, Feature Chain превратится в один индексный запрос. Побитовой операцией AND на SIDX в SILK все узлы, связанные с operationId, извлекаются за один запрос.

От обхода по парсерам — к запросу по графу. Интерфейс Feature Chain остаётся прежним, но внутренности меняются принципиально.

Итог

В full-stack-приложении «функциональность» не живёт в одном файле. Она распределена по нескольким слоям, и слои ссылаются друг на друга. Feature Chain идёт по этим ссылкам, чтобы автоматически извлечь всю область одной функциональности.

Вводишь один operationId — и получаешь всё: от API-спецификации до схемы БД, от политики авторизации до тестовых сценариев, от реализации функции до фронтенд-компонента. Десятки grep заменяются одной командой. ИИ получает контекст без пропусков; человек — свободу на рельсах.

Код: github.com/park-jun-woo/yongol