Skip to content

Техдолг: стандарт кода, карта слоёв и ответы на 58 замечаний — ревью всего кода параллельными агентами #459

Open

Description

@bim-ba

Зачем

Код писался быстро и большими мазками; владелец прочитал ядро и корни и оставил 58 замечаний (комментарии от 2026-10-09 ниже). Почти все сводятся к трём вещам: нет записанных стандартов, слои перемешаны, написано руками то, что умеют библиотеки. Ревью должно дать не список придирок, а три результата.

Три результата

№ Результат В каком виде
1 Стандарт кода docs/conventions/code.md: по правилу на вопрос «как у нас принято», и к каждому правилу — проверка ast-grep (или тест архитектуры там, где ast-grep не может)
2 Карта слоёв, к которой идём что такое ycli.core (обобщённое, без слова «Яндекс», с расчётом на перенос в refract), что остаётся в ycli.yandex, куда уходят sync и status, что уезжает из ycli.cli и ycli.mcp в ядро; вместе с #508
3 Ответ на каждое из 58 замечаний таблица: замечание → что в коде на самом деле (файл:строка) → вердикт «исправить / обсудить / оставить и объяснить» → чем заменить

Находки сверх замечаний идут в тот же отчёт теми же тремя вердиктами.

Состояние на старте

Что показал замер (наводки, не выводы)

Что Результат
Размер 145 тысяч строк Python; из них 26,5 тысячи — сгенерированный слой DataLens
Повторы без сгенерированного слоя 14,1 % кода, 245 групп; 168 пересекают области
Повторы между сервисами 89 групп, почти все в models.py: Forms + Tracker 39, Tracker + Wiki 32, Forms + Wiki 15
Список параметров операции 471 операция; у 435 записан во всех четырёх слоях; у 99 команда собирает тело из опций руками
Сложность функций низкая: 7 функций за порогом цикломатической; когнитивная ≥ 15 — в скриптах (25), проверках (19), e2e (11), ядре (8), корнях (8)
Мёртвый код три инструмента не сходятся ни в одном месте
Сервис импортирует другой сервис ни разу; но каждый сервис импортирует ycli.cli (DataLens 30, Tracker 20, Forms 17, Wiki 9)

Где стандарт уже есть, но не записан: X | None (3867, Optional — 0), @cache (14, других нет), модели сервисов — только pydantic (457). Где его нет: псевдонимы типов (type X = 10 против ~360 присваиваний), место опций команд (все восемь сочетаний typedefs.py / верх cli.py / подпись), имена «дай объект» (135 голых слов, get_* — 0), функции и константы на уровне модуля. Всё это с местами — в ways.md.

Области

Агент читает область целиком в одном контексте, поэтому ориентир — до 10 тысяч строк.

Область Файлов Строк Модель
core (yandex/core, models, sync, status, модули верхнего уровня, settings.py) 45 8 522 Opus
roots-cli-mcp (ycli/cli, ycli/mcp) 28 3 900 Opus
tracker-1 (applications … dashboards) 72 5 780 Sonnet
tracker-2 (entities … issues) 30 7 252 Sonnet
tracker-3 (issuetypes … worklog) 112 8 781 Sonnet
forms 105 9 633 Sonnet
wiki 72 7 859 Sonnet — пилот
datalens-1 (audit … entries), рукописный 73 7 529 Sonnet
datalens-2 (entrylocks … workbooks), рукописный 103 7 619 Sonnet
scripts (генераторы, дрейф API) 11 5 984 Sonnet
tests-checks-1, tests-checks-2 (архитектура, контракт, инструменты, документация) 52 10 503 Sonnet × 2
tests-unit-core-cli-mcp-1, -2 75 13 354 Sonnet × 2
tests-unit-tracker 91 9 152 Sonnet
tests-unit-datalens 69 6 452 Sonnet
tests-unit-forms-wiki 64 6 009 Sonnet
e2e (Python и сценарии YAML) 11 2 172 Sonnet

Сгенерированный слой DataLens (26 523 строки) не читается: читается его генератор в scripts. Корни отданы Opus вместе с ядром, потому что почти все замечания владельца — про эти две области.

Этапы

Этап Что Агенты
0. Замер сделан —
1. Пилот область wiki целиком; цель — отладить задание и формат находок и измерить цену одной области 1 читатель Sonnet + 1 проверяющий Opus
2. Чтение остальные 17 областей, волнами по 4–5 одновременно 15 Sonnet + 2 Opus
3. Сверка с документацией каждое «библиотека это умеет» — по текущим докам pydantic, typer, httpx2, stamina, rich, fastmcp; отдельно ответ на замечание 58: что из них мы не используем, хотя могли бы 2 исследователя Sonnet
4. Сведение один ищет общее между областями (повторы, разные решения одной задачи, кандидаты в стандарт и в ycli.core); второй пытается опровергнуть находки 2 проверяющих Opus
5. Отчёт сводный отчёт, таблица ответов на 58 замечаний, карта CodeCharta с числом находок на файл 1 автор Sonnet

После отчёта: решения владельца → исправления пачками PR по областям (пишет Sonnet, каждую пачку проверяет Opus и тесты); перестройка слоёв — вместе с #508, пишет Opus.

Цена не измерена: ревью одного PR на 158 файлов стоило около 470 тысяч токенов. Пилот даёт настоящую цифру на область; по ней решается размер волн.

Что получает читатель области

Досье своей области, ways.md, cross-area.md, parameters.csv, ARCHITECTURE.md, docs/conventions/, замечания владельца, относящиеся к его файлам, и список вопросов ниже.

На что смотреть (один список для всех)

  1. Способы. По каждому пункту ways.md в своей области: какой способ — правило, какие места — отступления, и почему. Плюс способы, которых замер не видел.
  2. Слои. Что в файле не принадлежит его слою: ввод-вывод, чтение настроек, знание о соседней поверхности, яндексовое в общем коде и общее в яндексовом. Для ядра — что мешает ему стать ycli.core без слова «Яндекс».
  3. Самодельное вместо библиотечного. pydantic 2 (Annotated-метаданные, валидаторы и сериализаторы, TypeAdapter, дискриминаторы, validate_call, секреты), typer, fastmcp, httpx2, stamina; Python 3.12+. Утверждение «библиотека умеет» помечается для этапа 3, а не доказывается памятью.
  4. Признаки по строкам. Имена полей, списки имён, правка текста регулярными выражениями, комментарии-метки вместо типизированных объектов (Техдолг: признаки полей — типизированные метки, а не строки, списки имён и правка текста (аудит и исправление) #457).
  5. Список параметров операции. Где и сколько раз записан, собирается ли тело руками (319 функций с длинным списком аргументов: природа CLI или параметры должны стать объектом — одно решение #562); parameters.csv — отправная точка.
  6. Повторы. Для каждой группы клонов из досье: совпадение, недостающий механизм или намеренное зеркало CLI и MCP.
  7. Лишнее. Мёртвый код (каждого кандидата проверить чтением), обёртки в одну строку, параметры, которые никто не передаёт, абстракции с одним пользователем, тесты, проверяющие реализацию вместо поведения.
  8. Читаемость. Функции уровня модуля и константы — обоснованы ли; длинные функции без логических частей; докстринги, которые пересказывают код; имена.
  9. Типы. Any, dict[str, Any], cast, # type: ignore, # noqa — каждое с вопросом «почему нельзя точнее».
  10. Свои же правила. ARCHITECTURE.md, docs/conventions, решения закрытых issue.

Правила для агентов

  • Читать область целиком; что не прочитано — назвать.
  • Находка без файл:строка не принимается. Наводка инструмента подтверждается или опровергается чтением и так и помечается.
  • Вердикт на каждую находку: исправить / обсудить / оставить и объяснить; к «исправить» — чем заменить.
  • Ничего не править, не коммитить, не писать в GitHub. Сгенерированное руками не трогать.
  • Писать находки в свой файл по ходу: ~/.cache/ycli-research/techdebt/findings/<область>.md; итог возвращать текстом, а не ссылкой.
  • Слова вердикта о проверенности: подтверждено / опровергнуто / не удалось проверить.

Замечания владельца: кто отвечает

Замечания О чём Область
18–21 settings.py: функции уровня модуля, система профилей, префикс окружения core
22–26 yandex/base.py: длинный комментарий, проверка через bool, единый объект авторизации вместо трёх аргументов core
27–30 yandex/errors.py: функции и константы уровня модуля, тяжёлые методы core
31–32 yandex/factory.py: проверка без pydantic, фабрика функцией core
33–41 yandex/mcp.py: константы, ввод-вывод в модуле MCP, тяжёлые функции, имена get_* core
42–52 yandex/models.py: Literal[...] | str, поиск по строке, метка Secret(), место для меток, датаклассы меток, единственная ответственность core
53–55 polling.py (почему не stamina), registry.py, service.py (датакласс или pydantic) core
56–57, 59–65 core/: авторизация, токен продолжения, псевдонимы типов, @cache, пагинация как абстракция с базовой реализацией, profile.py, session.py на 500 строк core
66 sync и status под yandex core + сведение
67–70 ycli/cli, ycli/mcp: где лежат опции, транспорт в mcp/http_auth.py, cli/api_response.py, лишнее в корнях roots-cli-mcp
25, 58 pydantic для проверки функций; что не используем из библиотек этап 3
70–72 стандарты и сложность через ast-grep; то же для документации, e2e, скриптов и тестов сведение
73–75 smoke_test.py, conftest.py, pyproject.toml tests-checks, scripts

Номера — индексы комментариев с нуля, как их отдаёт gh issue view 459 --json comments --jq '.comments | to_entries[] | "[\(.key)] \(.value.body)"'; замечания владельца — индексы 18–75 (все от 2026-10-09).

Что на выходе

  • Отчёт в docs/ с числом находок по областям и видам и с ответами на 58 замечаний.
  • Черновик docs/conventions/code.md и правила ast-grep к нему; каждое правило показано падающим на нарушении.
  • Карта слоёв — отдельным issue needs-decision вместе с Вывод SDK, CLI и MCP из описания операции: итог исследования и пять решений до пробы #508.
  • Всё, где есть выбор (заменить подход, убрать поверхность, поменять публичное имя), — отдельными issue needs-decision.
  • Механические исправления — пачками PR по областям, после решений.

Чего не делать

  • Не править код внутри ревью: сначала полный список, потом решения, потом исправления.
  • Не начинать волну до пилота и не начинать чтение, если main сдвинулся: сначала перезапустить замер.
  • Не решать за владельца то, что меняет публичные имена, поверхности или слои.

Перед стартом: уборка

В репозитории лежат рабочие копии и ветки прошлых сессий: 12 рабочих копий, около 230 локальных веток, 2 старых тайника (git stash) неизвестного содержания. Первым шагом — сверить каждую с main и принести владельцу список «слито / не слито / неизвестно»; удалять только по его слову.

Связанное

#508 (вывод слоёв из описания операции), #562 (список параметров — один раз), #575 (хвосты), #457 (признаки полей), #234, #320, #113.

Activity

  1. bim-ba commented on Oct 6, 2026

    @bim-ba
    OwnerAuthor

    Дополнение (владелец, 2026-10-06): ещё два взгляда для каждого агента

    1. Залепы вместо устройства. Места, где задача решена условием, флагом, функцией-помощником или особым случаем там, где должен быть класс, интерфейс (Protocol/ABC), наследование или композиция. Признаки: if kind == … по строке вместо полиморфизма; функция с заглавной буквы и # noqa, изображающая класс; параметр-флаг, меняющий смысл вызова; один и тот же набор аргументов, который таскают вместе через несколько функций (значит, это объект); помощники _… в cli.py и mcp.py, повторяющие друг друга.

    2. Унификация. Одно понятие — одно устройство, от которого идут частные случаи. Пример владельца, с которого надо начать: Endpoint и RPC должны быть видами одного базового понятия Operation, чтобы к нему же добавлялись другие виды API (gRPC и прочие) — это же связывает ядро с проектом refract (ARCHITECTURE.md, раздел про refract: у Endpoint[T] та же форма, что у Request в refract).

      Как это выглядит сегодня (main f17029dc, src/ycli/yandex/core/endpoint.py): Endpoint[T] — класс; RPC — функция (с # noqa: N802 за заглавную букву), которая возвращает Endpoint с методом POST и путём rpc/<имя>; в её докстринге прямо сказано «one more way to write an Endpoint, not another kind of request». То есть сейчас вид API — это способ записи, а не тип. Агент по ядру должен разобрать: что общего у REST-запроса, RPC-вызова и будущего gRPC (имя операции, эффект, тип ответа, тело), что различается (транспорт, адрес, кодирование), и предложить иерархию или композицию с ценой перехода — сколько файлов endpoints.py и проверок ARCH она затронет.

      Искать так же по остальному коду: пагинация (восемь классов в core/pagination.py — это семейство с общим интерфейсом или набор похожих?), ошибки, вход (auth), модели запросов и ответов, корни CLI и MCP.

    По этим двум пунктам агент не предлагает правку на месте: каждая находка — кандидат в отдельный issue needs-decision с вариантами устройства, потому что это меняет архитектуру (ARCHITECTURE.md и проверки меняются в том же PR).

  2. bim-ba commented on Oct 6, 2026

    @bim-ba
    OwnerAuthor

    Стратегия и план (архитектор, 2026-10-06). Запуск — по команде владельца, после полного покрытия DataLens

    Стратегия

    Сначала машина, потом агенты, потом человек. Всё, что можно найти инструментом, находится инструментом и приходит агентам готовым списком; агенты тратят внимание на то, чего инструмент не видит (устройство, унификация, красота); владелец решает только развилки.

    flowchart LR
        A[0. Заморозка и базовая линия] --> B[1. Машинный проход]
        B --> C[2. Агенты по областям, параллельно]
        C --> D[3. Сквозные агенты: дубли и унификация]
        D --> E[4. Проверяющий поверх всего]
        E --> F[5. Сводный отчёт и issue]
        F --> G[6. Решения владельца]
        G --> H[7. Исправления пачками PR]
    
    Loading

    Этапы

    Этап Что делается Результат
    0. Заморозка Очередь слияния пуста, исполнители не открывают PR; фиксируется коммит main. Один черновой прогон на ядре (1,3 тыс. строк) — проверить, что задание агенту даёт находки нужного качества, и поправить его до общего запуска sha, отлаженное задание
    1. Машинный проход Инструменты из таблицы ниже по всему коду; результаты складываются в файлы по областям списки находок по файлам, без оценки
    2. Агенты по областям 10 агентов параллельно, каждый читает свою область целиком + машинный список по ней + правила проекта. Девять взглядов из этого issue таблица находок на область
    3. Сквозные агенты 3 агента, каждый по одной теме через все сервисы: (а) одна задача, решённая по-разному в Трекере, Вики, Формах и DataLens; (б) ядро: Operation над Endpoint и RPC, пагинация, ошибки, вход; (в) помощники в cli.py и mcp.py кандидаты на унификацию с ценой перехода
    4. Проверяющий Один агент, не видевший кода до этого: перепроверяет каждую находку «исправить» по файлу и строке, выбрасывает ложные, сводит дубли, отмечает противоречия между агентами проверенный список
    5. Отчёт Сводка в docs/; находки с выбором — отдельными needs-decision; механические — списком на исправление отчёт и issue
    6. Решения Владелец отвечает в issue записанные решения
    7. Исправления Исполнители, пачками по областям; каждое новое правило — в docs/conventions и, где возможно, в проверку PR

    Запускается этап 2 только после того, как черновой прогон этапа 0 показан владельцу.

    Какими инструментами (все запускаются через uv/uvx, версии проверены 2026-10-06)

    Инструмент Зачем Первая базовая линия (main f17029dc, без сгенерированного слоя)
    ruff 0.15.20 со всеми правилами (--select ALL), а не только выбранными в проекте старые идиомы, сложность, булевы параметры-флаги, обработка исключений, неиспользуемые аргументы не выбранных проектом срабатываний: PLR (сложность, число аргументов) 274, PYI 296, EM/TRY (исключения) 165, FBT (булевы флаги) 73, ARG (неиспользуемые аргументы) 21
    ty 0.0.55 типы; места, где тип размыт —
    поиск по тексту слабые типы и подавления Any — 207 мест, dict[str, Any] — 72, cast( — 9, # noqa — 12, # type: ignore — 0
    vulture 2.16 мёртвый код 11 кандидатов при уверенности 80 %
    complexipy 8.0.1 когнитивная сложность функций —
    ast-grep 0.45.3 структурный поиск образцов: if x == "строка" по виду, функции с заглавной буквы, одинаковые тела в cli.py и mcp.py, регулярные выражения по сгенерированному тексту —
    graphify (граф кода, уже описан в CLAUDE.md) кто от кого зависит; абстракции с одним пользователем; кандидаты в общий базовый класс —
    import-linter, tests/architecture уже действующие границы — чтобы находки им не противоречили —

    Числа базовой линии — не находки, а размер работы: каждое срабатывание агент оценивает сам.

    В какие источники ходят агенты

    Вопрос Источник Правило
    «Библиотека это умеет?» текущая документация pydantic 2, Typer, FastMCP, httpx2, stamina — через сервер документации context7; для Python — «What's New» 3.12–3.14 на docs.python.org ссылка на страницу в каждой такой находке; память не источник
    «Как устроены наши правила?» ARCHITECTURE.md, docs/conventions/*, закрытые issue с решениями владельца (метка needs-decision снята, комментарий «Решено») находка, противоречащая решению владельца, идёт не в «исправить», а в «обсудить» со ссылкой на решение
    «Как это делают в образцовом коде?» исходники самих библиотек (pydantic, httpx, Typer, FastAPI) через deepwiki — только для вопросов устройства: как там разделены запрос, транспорт и операция образец — довод, а не правило
    «Что общего с refract?» репозиторий bim-ba/refract и раздел о нём в ARCHITECTURE.md для сквозного агента по ядру

    Чего агенты не делают

    Не правят код. Не предлагают «исправить на месте» по пунктам 8 и 9 (устройство и унификация) — только варианты для решения. Не пересматривают решения владельца. Не читают сгенерированный слой построчно — его качество оценивается через генератор.

    Стоимость (оценка, не замер)

    14 агентов; по опыту сегодняшнего исследования исходников DataLens один агент на большом чтении тратит порядка 300 тысяч токенов — весь проход порядка 4–5 миллионов. Точнее скажу после чернового прогона на ядре.

  3. bim-ba commented on Oct 6, 2026

    @bim-ba
    OwnerAuthor

    Взгляды архитектора (дополнение к девяти)

    Каждый — из дефекта, который нашла живая проверка за последние дни: это то, что ревью «по чистоте» обычно пропускает, а пользователь встречает первым.

    1. Тихая потеря входа. Код принял то, что дал человек, и молча выбросил. Три дефекта за один день были ровно такими: поля name и workbook_id из --body-file терялись в чартах (feat(datalens): charts of the wizard, QL charts and charts of the editor are read and written (#352) #445) и датасетах (fix(datalens): datasets update and validate keep the fields a file or -F gives #453); null в обязательных полях дашборда выбрасывался из запроса (feat(datalens): dashboards are read, created, saved and deleted (#352) #454). Агент ищет каждое место, где значение берётся «по ключу из слитого словаря», фильтруется по is not None, заменяется умолчанием или отбрасывается без ошибки, и для каждого отвечает: это намерение или потеря?

    2. Текст ошибки как интерфейс. The request cannot be built: body: Input should be a valid dictionary человеку ничего не говорит (было в feat(datalens): charts of the wizard, QL charts and charts of the editor are read and written (#352) #445). Для каждого места, где ycli сам отказывает: названо ли поле, сказано ли, что сделать, не утекает ли входное значение. И обратное: где ycli молчит, а отказать должен.

    3. Утверждения в описаниях без свидетельства. Описание инструмента — это обещание агенту. За неделю три оказались неверными: «значение строки приходит текстом», «без фильтра — запуски всех форм», «подключение Google Sheets создаётся через API». Агент выписывает каждое утверждение о поведении API в докстрингах, описаниях инструментов, справке команд и навыках и ставит рядом свидетельство — записанный ответ, контрактный случай по замеру, страницу справки — или пометку «свидетельства нет».

    4. Проверки, которые не кусаются. Архитектурный тест, список исключений в нём, пометка # violation(…) (их 65), контрактный случай, написанный по документу, а не по замеру. По каждой: видела ли она когда-нибудь дефект, который должна ловить; нужна ли пометка до сих пор; что она пропускает (тест «имя не от генератора» ловил суффикс Model, но не CHTABLE1).

    5. Рукописное, которое выводится из одного источника. На каждую операцию четыре файла, и большая часть cli.py и mcp.py повторяет друг друга и client.py: те же аргументы, те же описания, тот же вызов. Агент меряет, какая доля этих файлов механически следует из endpoints.py и модели запроса, и что в них действительно написано рукой (описания, оговорки, порядок опций). Это кандидат на самое большое удаление кода в проекте — и ответ на вопрос, почему DataLens покрывается медленно. Только варианты, решение за владельцем.

    6. Публичная поверхность SDK. Что человек может импортировать и на что тем самым мы подписались: имена, попавшие в публичные случайно; один смысл под разными именами в разных сервисах (get / get_by_id, list / list_global, page_id / id); что возвращает удаление (ничего, Ack, модель); где аргумент позиционный, а где только именованный. Таблица расхождений между сервисами.

    7. Путь секрета. От входа до провода и обратно: журнал, текст ошибки, --dry-run, repr, дамп, записанные ответы, URL. Для каждого места, где печатается что-то пришедшее извне: может ли там оказаться секрет. После DataLens: строгие объединения в запросах отклоняют виды, которые сервис принимает (GSHEETS_V2) — оставить строго или пропускать? #444 и Секрет в ответе, выданный один раз (privateKey секрета встраивания DataLens): печатать, маскировать или писать в файл? #448 гарантия стала составной («для тела, подошедшего под свой вид», «секрет в ответе печатается») — проверить, что код делает именно то, что записано, и не больше.

    8. Цена запуска. ycli --help и старт MCP-сервера импортируют все сервисы; инструментов уже около четырёхсот. Что импортируется при запуске одной команды, сколько это занимает, какого размера tools/list. Не красота, но прямо влияет на то, каким продукт ощущается.

    9. Что удалить целиком. Не строки, а возможности: параметры, которые никто не передаёт; классы без пользователей (BotTokenAuth, APIKeyAuth, debt: delete what nothing uses, and use what we already have instead of our own code #234); 135 файлов с from __future__ import annotations (debt: drop from __future__ import annotations everywhere #320); команды, дублирующие друг друга (tracker_issues_list рядом с tracker_issues_search). Список кандидатов с доказательством, что пользователей нет.

    Пункты 10–13 и 16 — «исправить» (это дефекты). Пункты 14, 15, 17, 18 — только варианты на решение.

  4. bim-ba commented on Oct 6, 2026

    @bim-ba
    OwnerAuthor

    К пункту 14 (владелец, 2026-10-06): направление — декларативное описание операции

    Цепочка, как её назвал владелец и как она устроена в коде сейчас:

    flowchart LR
        O[Операция: endpoints.py<br/>запрос, эффект, тип ответа] --> S[SDK: client.py<br/>метод отправляет операцию]
        S --> C[CLI: cli.py]
        S --> M[MCP: mcp.py]
        S --> X[другая поверхность,<br/>если появится]
    
    Loading

    Операция — точка входа для SDK, SDK — точка входа для всех поверхностей. Сегодня каждая стрелка написана руками: метод клиента повторяет аргументы операции, команда и инструмент повторяют аргументы метода и его описание. Унификация здесь — одно декларативное описание операции, из которого поверхности выводятся, а не пишутся; то же описание — общий язык с refract.

    Что сквозной агент по этой теме должен принести (только варианты, без правок):

    1. Замер. На трёх ресурсах разного возраста (старый из Трекера, средний из Форм, новый из DataLens): какая доля строк client.py, cli.py, mcp.py механически следует из endpoints.py и модели запроса, и что написано рукой. Список рукописного по видам: тексты описаний, имена и короткие формы опций, поведение только CLI (--wait, слияние --body-file и -F, подтверждение удаления, чтение файла), только MCP (OverBudget, аннотации), порядок аргументов.
    2. Где рукописное должно жить при декларативном подходе — в самом описании операции (поля с текстом), в метаданных модели запроса, в отдельном слое «оговорок поверхности».
    3. Два способа вывода и их цена:
      • во время импорта (поверхности строятся из реестра операций, как FastAPI строит маршруты из сигнатур) — нет сгенерированных файлов, но справка, снимки и поиск по коду работают через реестр;
      • генерацией файлов (как слой моделей DataLens) — код виден и находится поиском, но это ещё один генератор и ещё один слой, который нельзя править руками.
    4. Что уже декларативно и на что можно опереться: Effect → аннотации инструментов; контрактные случаи с формами CLI, MCP и SDK; проверка DataLens: как RPC-операция выглядит в SDK, CLI и MCP — конверт или аргументы #371 «аргументы = поля запроса»; scripts/gen_openapi.py, который уже выводит OpenAPI из операций.
    5. Связь с пунктом 9: если операция становится базовым понятием (Operation над Endpoint и RPC), то она же и есть это декларативное описание — два пункта решаются одним устройством или двумя?
    6. Цена перехода: сколько ресурсов (сейчас около 500 операций в четырёх сервисах), какие инварианты ARCH меняются (ARCH-1 «четыре файла на ресурс» — первым), можно ли переходить по одному сервису.

    Итог — один issue needs-decision с вариантами устройства; решает владелец.

  5. bim-ba commented on Oct 6, 2026

    @bim-ba
    OwnerAuthor

    Находки к взгляду 9 (унификация), от E5 при исполнении #412; строки по main bbced15a:

    • Свой локальный -F у четырёх команд Трекера. tracker issues update-bulk / move-bulk / transition-bulk (BulkValueOpt, src/ycli/yandex/tracker/issues/cli.py:276) и tracker entities update-bulk (BulkFieldOpt, src/ycli/yandex/tracker/entities/cli.py:72) объявляют собственную опцию --field/-F; глобальный -F на них запрещён (OWN_FIELD, src/ycli/cli/inject.py:111-114). Разбор у них был другой (без a[b] и @file) — его выровнял feat(cli)!: -F key=@file reads a field's value from a file #472; сама отдельная опция осталась: она задаёт поле каждой задачи (уходит под values), а глобальная — поле запроса.
    • Одна буква — два смысла. tracker entities reports-create -F (src/ycli/yandex/tracker/entities/cli.py:365) — список имён колонок, а не key=value.
    • Ещё два key=value с простым разбором, не -F: tracker entities search --filter (entities/cli.py:210) и tracker issues scroll-clear --pair (issues/cli.py:253); --acl у permissions-update (entities/cli.py:281) выровнен тем же feat(cli)!: -F key=@file reads a field's value from a file #472.
  6. bim-ba commented on Oct 6, 2026

    @bim-ba
    OwnerAuthor

    Находка к взгляду 11 (текст ошибки), от E5 и архитектора при приёмке #474; воспроизведено на main 798a6876 прямой проверкой модели CreateSparkApplicationArgs:

    • Отказ объединения-конверта печатается именами сгенерированных классов. datalens sparkapplications create без вида даёт три строки вида CreateSparkApplicationArgsVariant1.sparkApplication: Field required; с двумя видами — пять строк, среди них CreateSparkApplicationArgsVariant2.sparkApplication: Extra inputs are not permitted. Человеку нужно одно: «дай ровно один из sparkApplication, pysparkApplication, sparkConnectApplication». То же ждёт htmlpages update и любой запрос, который документ пишет объединением объектов (refactor(datalens): a request given as a union of objects has an envelope per member #464). Это вопрос к тому, как CLI и MCP печатают ValidationError такого объединения, а не к отдельной команде; в feat(datalens): a Spark application is made, of any of its three kinds (#352) #474 не правилось.
  7. bim-ba commented on Oct 7, 2026

    @bim-ba
    OwnerAuthor

    Находка к взглядам 9 (унификация) и 16 (путь секрета), от E5 при исполнении #477; main a3e2130c:

    • 100 мест создают FastMCP( напрямую; защита отказа аргументов ставится в 5 из них. Серверов, которые можно импортировать и смонтировать у себя, три уровня: корневой (ycli.mcp.server.build_server), четыре сервисных (ycli.yandex.<сервис>.mcp.server.mcp) и серверы ресурсов (ycli.yandex.<сервис>.<ресурс>.mcp.mcp, около 95). ArgumentRefusals (отказ аргументов без повторения присланного, fix(mcp): a refusal of a tool's arguments no longer repeats what was sent #477) несут корневой и четыре сервисных; сервер одного ресурса, смонтированный кем-то сам, отвечает сырым текстом pydantic с input_value. Закрыть всё — общий конструктор сервера ресурса (правка ~100 файлов, генератор new_endpoint.py, архитектурный тест «сервер создан конструктором»); решение владельца: считать ли серверы ресурсов публичной поверхностью. Сейчас это сказано в докстрингах сервисных серверов и самого ArgumentRefusals.
  8. bim-ba commented on Oct 7, 2026

    @bim-ba
    OwnerAuthor

    Находка к взгляду 12 (пример, который сервис не примет), от E5; посчитано на main 4cb641eb по контрактным случаям (tests/contract.load_cases) и записанным ответам (tests/fixtures/replies/<сервис>/<ресурс>/<метод>.json). Кода не меняла.

    У 74 из 261 записывающей операции нет ни одного записанного живого ответа — их контрактные случаи написаны по документу или по догадке, и тело из случая сервис мог ни разу не принять.

    Сервис Записывающих операций Есть записанный ответ 2xx Нет записи Доля без записи
    DataLens 71 29 42 59%
    Tracker 108 83 25 23%
    Forms 48 42 6 13%
    Wiki 34 33 1 3%
    Всего 261 187 74 28%

    Где именно нет записи:

    Границы подсчёта:

    • «Записывающая» — операция, у которой хотя бы один случай заявляет эффект сильнее чтения (Case.expected_effect).
    • Запись ответа доказывает, что операция отвечала 2xx живому сценарию, а не что сервис принимал именно тело из контрактного случая: запрос в записи не хранится, и тело сценария может отличаться от тела случая. Поэтому 187 — верхняя граница «подтверждено», а не точное число. Пример с dashboards create (случай слал тело без entry.meta) как раз из 74.
    • Ошибочных ответов среди записей нет: все 187 — 2xx.
  9. bim-ba commented on Oct 7, 2026

    @bim-ba
    OwnerAuthor

    К моему счёту по взгляду 12 — два подтверждённых примера «случай по документу → сервис отвечает 400» (измерено вживую 2026-10-07 при записи #481; принятые тела — в e2e/scenarios/datalens/entries_content.yaml):

    • datalens.reports.create: случай шлёт data: {"slides": [{"id": "s1"}]}; DataLens на ровно это тело отвечает 400 VALIDATION_ERROR и требует data.counter, data.salt, data.slideGroups, data.slidesOrder, data.visualSettings, data.slideSettings.
    • datalens.dashboards.create: сервис требует tabs[].connections, tabs[].aliases, settings.silentLoading, settings.expandTOC; в случае нет ни одного из четырёх (измерено на теле без тех же четырёх ключей, не на самом теле случая).

    После #481 у 19 записывающих операций DataLens из 42 запись появилась: без записанного ответа остаётся 55 из 261 (DataLens 23 из 71 — разделы по документу, #456).

  10. bim-ba commented on Oct 7, 2026

    @bim-ba
    OwnerAuthor

    Дополнения к плану (владелец, 2026-10-07)

    Когда. После движка «файлы в git» и двух первых видов (#490, вариант Б): ревью идёт от явного baseline, «как с чистого листа».

    Ещё один агент в составе ревью — разведчик идей. Не ищет дефекты, а собирает мелкие улучшения и фичи: читает документацию зрелых инструментов того же рода (gh, kubectl, Terraform, AWS CLI, Stripe CLI, спецификация MCP, FastMCP) и сверяет с тем, что ycli умеет сегодня (по справке команд и коду, не по памяти). Возвращает таблицу: идея одной фразой с примером команды, у кого подсмотрено и ссылка, есть ли у нас что-то близкое (файл или текст справки), кому полезно, размер, достоверность. Предпочтение — тому, что выводится из уже объявленного (реестр операций, модели, метки) и ложится на все операции разом.

    • По разведчику на область ревью, где это имеет смысл: CLI, MCP, sync, вход и первый запуск, документация и навыки.
    • Модель — дешёвая (Sonnet): это чтение и сопоставление.
    • Выход идёт не в находки ревью, а отдельным списком на отметку «беру / нет» — образец: Идеи сверху, заход 1: мелкие находки для sync, CLI и MCP — отметить, что берём #492 (первый заход, 29 идей).
    • Правило отбора до показа владельцу: каждое утверждение про наш код проверено запуском (в первом заходе так подтвердились молчаливый обрыв списка на лимите и --yes в справке команды чтения).

    #234 и #320 (удалить неиспользуемое; убрать from __future__ import annotations) — не раньше ревью: оно само допишет в техдолг, тогда и разберём вместе.

  11. bim-ba commented on Oct 7, 2026

    @bim-ba
    OwnerAuthor

    Находки до ревью (разведчик SDK, 2026-10-07; проверено с двух сторон, первая подтверждена чтением)

    К взглядам «метки вместо строк» (#457) и «современные средства библиотек»:

    • ycli/yandex/models.py: «поле игнорируется API» распознаётся по строке-приставке "Ignored by the API: " в описании поля — нужна типизированная метка в Annotated, как NoDropNull.
    • ycli/yandex/errors.py: разбор тела ошибки — цепочка isinstance по пяти формам; есть TypeAdapter над объединением моделей тела (он же дал бы типизированный код ошибки).
    • endpoints.py ресурсов (491 функция): параметры запроса — словари со строковыми ключами (params={"scrollTTLMillis": …}); есть модель параметров, сериализуемая тем же путём WIRE, что тело.
    • core/session.py: Retry-After в виде HTTP-даты не разбирается; в стандартной библиотеке есть email.utils.parsedate_to_datetime.
    • Направление «декларативная операция»: 421 рукописное тело метода клиента поверх send — кандидат на вывод из описания операции (см. идею 40 в заходе 2).
  12. bim-ba commented on Oct 7, 2026

    @bim-ba
    OwnerAuthor

    Цифры к направлению «операция описана один раз» (карта слоёв, #503)

    • Знание об операции — 2–14 строк в endpoints.py; руками вокруг него пишется 44–148 строк в пяти-шести файлах (клиент, CLI, MCP, случаи, модель).
    • Описаниями операций пользуются только клиенты (87 импортов); CLI и MCP их не читают.
    • Восемь повторов с числом операций — в Карта слоёв: где какая ценность, что повторено руками и что из этого следует — на отметку #503; самые большие: имя в пяти местах (467), описание словами трижды (467), один запрос в четырёх написаниях в каждом случае (746 случаев), 712 опций CLI, повторяющих поля моделей.
    • Знание только на одной поверхности: ожидание долгой операции (CLI), «показать, не отправляя» (CLI), обратная операция и поле-идентификатор (только живые сценарии), пример вызова (только тесты).

    Ревью должно пройти по этим восьми повторам как по списку.

  13. 53 remaining items

  14. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    https://github.com/bim-ba/ycli/blob/7d2dbd30bfe401e0b1fff719604614fff11d3034/src/ycli/yandex/core/session.py

    вот тут как-будто бы очень усложнено и нарушаются SRP принципы, не проще например декомпозировать сессию на подмодули: sync, async, utils? почти 500 строк блин на эту штуку, неужели никак нельзя красиво это сделать? да и опять эти топ-левел функции меня встречают..

  15. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    https://github.com/bim-ba/ycli/blob/7d2dbd30bfe401e0b1fff719604614fff11d3034/src/ycli/yandex/sync

    блин, мне не нравится что типа у нас в yandex модуле лежит подмодуль sync
    ну это же по идее независимая от yandex штука? это просто правильное i/o разных документов и моделей? почему он лежит именно там? мы в этом уверены?
    и кстати все то же самое с status

    вот типа смотри у нас в яндексе лежит: ядро, 4 сервиса, статус, синк
    это точно нормальная история? так делают?

  16. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    ycli/src/ycli/mcp/cli.py

    Lines 79 to 104 in 7d2dbd3

    _Kind = Annotated[
    Kind,
    typer.Option(
    "--kind",
    help="What to list: tools (default), prompts, or resources (addresses and templates).",
    ),
    ]
    _Transport = Annotated[
    Transport,
    typer.Option(
    "--transport",
    help=(
    "stdio (default): one local client, credentials from the environment or from "
    "--profile. http: "
    "Streamable HTTP for many users, each signed in through Yandex ID (needs "
    "YCLI__MCP__BASE_URL and your Yandex OAuth app; see "
    "https://ycli.savaznatnov.dev/how-to/self-host-over-http/)."
    ),
    ),
    ]
    _Host = Annotated[
    str | None, typer.Option("--host", help="HTTP only: listen address (YCLI__MCP__HOST).")
    ]
    _Port = Annotated[
    int | None, typer.Option("--port", help="HTTP only: listen port (YCLI__MCP__PORT).")
    ]

    блин, где-то у нас это лежит в typedefs.py, где то вот так вверху модуля, в чем система и стандарт? почему бы cli не разделять например на: commands, typedefs, models, итд... и то же самое делать и с mcp например?

  17. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    https://github.com/bim-ba/ycli/blob/7d2dbd30bfe401e0b1fff719604614fff11d3034/src/ycli/mcp/http_auth.py

    что это вообще тут делает? это же уровень транспорта, то есть ядра?

  18. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    https://github.com/bim-ba/ycli/blob/7d2dbd30bfe401e0b1fff719604614fff11d3034/src/ycli/cli/api_response.py

    опять же почему это вообще тут а не на уровне ядра? я не понимаю?

  19. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    у нас в ycli.cli и ycli.mcp как будто очень много лишней фигни, которой могло бы не быть если бы мы просто правильно все разделили архитектурно по слоям? типа многое из cli и mcp можно вынести именно в ядро. в yandex оставить только то что релевантно яндексу. само ядро вынести в ycli.core (еще раз, оно должно быть генерализированным, универсальным и унифицированным). а сейчас мне кажется у нас вообще очень много слоев между собой смешалось и это все нереально читать теперь и поддерживать. да и стандартов как-будто никаких вообще нету для кода. а кодстандарты и best-practices мы бы могли сделать если бы у нас было много хороших ast-grep правил ведь

  20. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    кстати, мне кажется сложность кода и его качество тоже можно было бы замерять через ast-grep? нам нужно просто определиться именно с правилами, скорами, системностью и стандартами, верно? можно например те же нейминги сюда же внести мне кажется. это же очень полезная штука, которая не только людей будет направлять, но и агентов наших, а то сейчас это все получается большими мазками поверх несистемности и без стандартов каких-то

  21. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    и причем все это относится еще и к документации, e2e, скриптам, тестам и так далее

  22. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    https://github.com/bim-ba/ycli/blob/7d2dbd30bfe401e0b1fff719604614fff11d3034/smoke_test.py

    нахера эта штука вообще нужна тут?

  23. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    https://github.com/bim-ba/ycli/blob/7d2dbd30bfe401e0b1fff719604614fff11d3034/conftest.py

    это нам же по стандарту pytest нужно?

  24. bim-ba commented on Oct 9, 2026

    @bim-ba
    OwnerAuthor

    https://github.com/bim-ba/ycli/blob/7d2dbd30bfe401e0b1fff719604614fff11d3034/pyproject.toml

    вот в этом файлике нету какого-то легаси и так далее? все норм?

  25. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Решено (владелец, 2026-10-10): как проводить — три слоя, инструменты как подсказки

    Дополняет раздел «Как проводить» выше; план целиком перепишу, когда разберу комментарии владельца от 9 октября.

    Слой Кто Что делает Что выдаёт
    1. Замер инструменты, без LLM считает всё, что считается досье на каждую область: списки с файл:строка
    2. Чтение агенты по областям читают область целиком; досье — наводки находки со ссылкой на код и вердиктом
    3. Сведение проверяющий агент сверяет находки между областями и с досье отчёт и карта

    Правила:

    • Агенты читают весь код, выводы делают только из кода. Находка без строки кода не принимается; наводку инструмента агент подтверждает или опровергает чтением.
    • Сложность меряется и по смыслу: сколько способов сделать одно дело, сколько мест править ради одного параметра, где нет стандарта. Способы считаются правилами ast-grep — по правилу на способ.
    • Вид каждого повтора определяет агент: совпадение, недостающий механизм или намеренное зеркало CLI и MCP.

    Инструменты слоя 1 (запущены на src, main 7d2dbd30): pyscn 1.32.4, ruff с выключенными у нас правилами C901 и PLR09xx, wemake-python-styleguide, skylos 4.47.2, vulture 2.16, complexipy 8.0.1, graphify, наши ast-grep и import-linter. Свои правила пишем в ast-grep: pyscn расширяется только порогами и слоями. semgrep и CodeQL не берём — второй движок правил ради того же.

    Первый замер:

    Что Результат
    Сложность функций 2 сложные функции, средняя 1,3
    Повторы 41 % фрагментов — клоны, 875 групп (сгенерированный слой DataLens не отделён; перемерить без него)
    Больше пяти аргументов 319 функций — вынесено в #562
    Мёртвый код инструменты расходятся: skylos 62, vulture 8, pyscn 0 — проверяет агент
    Тяжело читать 161 перегруженная строка, 101 модуль с лишним числом членов, 24 функции с высокой когнитивной сложностью

    Визуализация: отчёт pyscn и граф graphify как есть; плюс проба CodeCharta с нашими метриками и находками агентов с лимитом полчаса, а если не взлетит — своя страница.

  26. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    В план ревью (решено владельцем в #562, 2026-10-10): каждый агент области отвечает по каждой операции, где и сколько раз записан её список параметров (описание, метод SDK, команда, инструмент) и собирается ли тело руками в команде. Замер до чтения: 319 функций с более чем пятью аргументами, 166 операций; у 35 список записан в четырёх слоях, у 126 — длинный только у команды или инструмента. Карта идёт в #508, где решается «плоско или объектом».

  27. changed the title [-]Техдолг: полное ревью кода на clean code и красоту — параллельные субагенты по областям, проверяющий поверх[/-] [+]Техдолг: стандарт кода, карта слоёв и ответы на 58 замечаний — ревью всего кода параллельными агентами[/+] on Oct 10, 2026
  28. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Правила работы, выведенные 10–11 октября (кандидаты в docs/conventions/delivery.md)

    Каждое стоило круга работы; записаны здесь, чтобы пережить сжатие сессий. В репозиторий пойдут отдельным PR после слова владельца.

    Правило Что случилось без него
    Склеивать и переносить коммиты на базу, названную хешем, а не на origin/main main сдвинулся между прогоном и склейкой; голова #571 откатывала слитый #574 в 43 файлах
    «Дерево сохранено» проверять против базы, на которой шёл прогон, а не против самого себя та же история: проверка сравнивала дерево с собой
    Проверка считается работающей, только когда она упала на подставленной ошибке; в описании PR — замер в обе стороны тест -o name был зелёным при неработающем отказе: лазейка пропускала 312 случаев
    Результат инструмента читать по коду выхода, а не по последней строке вывода ошибка ast-grep прошла мимо: последняя строка при ошибке пустая
    Полный прогон не считается, если во время него правили файлы два прогона пришлось не засчитать
    Незакоммиченная работа не живёт в /tmp; рабочие копии — вне /tmp, коммит по ходу три готовых PR пропали при очистке /tmp
    Вывод живого прогона — сначала в файл причина одного из двух падений утеряна: на экране была только последняя
    Очередь слияния ждёт, пока обязательные проверки появятся и пройдут; пустой ответ GitHub — сбой связи, а не «голова сдвинулась» очередь дважды останавливалась ложно и один раз сочла PR зелёным до появления проверки tests
    Сливать по точному хешу проверенной головы (--match-head-commit), после слияния сверять дерево main с деревом этой головы — (правило сработало: ни одного расхождения)
    pkill -f <имя скрипта> убивает и оболочку, которая его запустила потеряны два фоновых прогона
    PR, меняющий ядро, формат токена или защиту, идёт через независимого проверяющего с пробами; исправления после него — узким повторным проходом его же прогонов #534: потеря данных при продолжении списка; #567: трассировки на поддельных токенах; #571: дыра в --tool-search; #576: сломанные ссылки в 154 схемах — всё при зелёном наборе тестов
    Ветку удалять после сверки её файлов с main, а не по статусу PR — (правило сработало)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions