Skip to content

Concepts RU

Pavel Erokhin edited this page Nov 20, 2026 · 3 revisions

English version

Несколько идей проходят через все команды и тесты. Разберитесь с ними один раз, и остальная вики пойдёт быстрее.

Loadout

Файлы проекта проходят через харнесс, он добавляет свой системный промпт и инструменты, и получается контекст модели: системный промпт, встроенные инструменты, правила, скиллы, MCP-серверы и инструменты, команды.

Loadout — всё, с чем агент вошёл в ход: то, что харнесс положил в контекст модели, кусок за куском. ctxray inspect его показывает, ваши тесты его проверяют, а ctxray diff сравнивает два. В каждом Loadout есть:

Часть Что это
Системный промпт Собственные инструкции харнесса, разбитые на секции. Виден, только когда харнесс запущен
Правила Файлы инструкций вроде CLAUDE.md, AGENTS.md, GEMINI.md, .claude/rules/*.md, .cursor/rules/*.mdc, у каждого — активация, причина и токены
Скиллы в списке Скиллы, которые модель видит по имени и описанию и может запросить
Загруженные скиллы Скиллы, чьё тело целиком попало в контекст, потому что модель их запросила
MCP-серверы и инструменты Серверы, настроенные для харнесса, и каждый инструмент со своей схемой. Инструмент, который виден только по имени, а схему получает по запросу модели, помечен как отложенный (deferred)
Команды Слэш-команды, которые предлагает харнесс
Токены Итог, токены по компонентам (system, rules, skills, mcp, commands, tools) и токены каждого MCP-сервера
Происхождение Для каждого куска — файл, из которого он пришёл, почему загрузился и как ctxray их связал

Происхождение (provenance) отвечает на вопрос «откуда это взялось?» для каждого куска. Его evidence говорит, откуда ctxray это знает: static — кусок предсказан по файлам, canary — в запросе вернулась метка, которую ctxray поставил в файл, marker или fingerprint — ctxray узнал обрамление харнесса или сам текст. Про метки рассказывает страница Режимы захвата.

Ещё Loadout перечисляет файлы, которые доходят до модели дважды: отправлены повторно или повторяют текст другого файла. Дубли стоят токенов и ничего нового не говорят.

Loadout зависит от того, где агент стартует и с какими файлами работает. Поэтому inspect принимает --cwd и --files, а resolve() и assemble() в тестах — то же самое.

Активация

У каждого правила и скилла один из четырёх видов активации. Этот словарь общий для всех харнессов: на него ложатся alwaysApply, globs и description из Cursor, paths из Claude Code, вложенные CLAUDE.md и всё остальное.

always загружается в каждой сессии своей зоны, path — когда агент работает с подходящими файлами, intent — когда модель выбирает по описанию, manual — только когда вы его назовёте. always и path решает харнесс, intent — модель, manual — вы.

Рядом с видом у каждого правила указана причина, по которой оно загрузилось в этот раз:

Причина Что значит
cwd Лежит в папке на пути от корня проекта до места, где стартует агент
always Безусловное правило, например файл в .claude/rules без paths
nested:<file> Агент работает с <file>, а правило лежит в папке между стартовой папкой и этим файлом
glob:<glob> Файл, с которым работает агент, подходит под <glob> правила
import:<path> Его импортирует файл <path>, например @AGENTS.md в CLAUDE.md. Активация берётся у импортирующего файла
description Правило Cursor, которое модель может выбрать по описанию
config Его называет конфиг харнесса, например instructions в opencode.json

Если ctxray запустил харнесс и нашёл в запросе правило, которого не предсказывал, причина у правила — observed.

Не каждый харнесс поддерживает все виды. У Codex нет правил по путям: он читает свои AGENTS.md один раз, от корня до стартовой папки, и файлы, которых касается агент, ничего не меняют. Что и как читает каждый харнесс, описано на странице Harnesses.

ИИ-харнесс

ИИ-харнесс — программа, которая оборачивает модель: Claude Code, Codex, Cursor CLI, Gemini CLI, OpenCode. Она находит ваши файлы инструкций, составляет список скиллов, запускает MCP-серверы, пишет собственный системный промпт и отправляет всё это модели. ctxray знает пять харнессов:

Id Харнесс
claude-code Claude Code
codex Codex
cursor-cli Cursor CLI
gemini-cli Gemini CLI
opencode OpenCode

Если в конфиге нет ключа harnesses, ctxray тестирует все пять.

Почему один репозиторий даёт харнессам разные инструкции

Каждый харнесс читает свои файлы. Claude Code читает CLAUDE.md и .claude/rules. Codex — AGENTS.md. Gemini CLI — GEMINI.md или имена из своих настроек. Правило из .claude/rules/payments.md никогда не дойдёт до Codex, и коллега, который работает в Codex, его не увидит.

ctxray ловит это на L1 предупреждением harness-differences. Для каждого файла, который один харнесс читает, а другой нет, ctxray проверяет, получает ли второй тот же текст другим путём: через копию, симлинк, импорт или те же слова в файле, который он читает. Если нет, вы увидите:

⚠ .claude/rules/payments.md  Codex не читает этот файл, и такого текста нет ни в одном файле, который он читает, поэтому ИИ-харнессы получают разные инструкции. Этот файл читает только Claude Code  harness-differences

Обычное решение — держать общие правила в AGENTS.md и импортировать его из CLAUDE.md строкой @AGENTS.md. Если разница задумана, выключите предупреждение флагом --ignore-harness-differences, ключом конфига ignoreHarnessDifferences: true или переменной CTXRAY_IGNORE_HARNESS_DIFFERENCES=1.

Команды и субагенты у каждого харнесса свои, поэтому разницей не считаются. Две соседние проверки смотрят на файлы, которые не читает ни один харнесс прогона. Если файл читает только харнесс вне прогона, будет предупреждение other-harness. Если его не читает никто и на него никто не ссылается, будет unread — это ошибка: файл написан для агентов, а ни один из них его не увидит.

Токены

Каждый Loadout говорит, сколько токенов стоит каждый кусок и как они посчитаны. Счёт на вашей машине — это оценка. ctxray всегда помечает её ≈ и никогда не выдаёт за точное число: ни в терминале, ни в HTML-отчёте, ни в сводке Markdown.

Токенайзер зависит от харнесса и семейства модели за ним:

Харнесс Как считает ctxray Метод в выводе
Claude Code o200k, умноженный на коэффициенты, измеренные по счёту самого Claude для каждого вида текста: проза, код, JSON, нелатинский текст, метаданные local:o200k_base+calibrated:claude-sonnet-5-5
Gemini CLI словарь Gemma, который ctxray носит с собой. Если он не загрузился — o200k local:gemma4
Codex, OpenCode, Cursor o200k, токенайзер нынешних моделей OpenAI local:o200k_base

Коэффициенты Claude лежат примерно между 1,54 и 1,68: на тот же текст Claude насчитывает больше токенов, чем o200k. ctxray calibrate заново измеряет их с вашим ключом, см. Commands.

Чтобы получить точные числа, пусть считает провайдер. Поставьте exactTokens: true в конфиге или CTXRAY_EXACT_TOKENS=1, и каждый захваченный Loadout посчитает собственный эндпоинт провайдера, через ваш upstream и ваш ключ:

Провайдер Эндпоинт Метод в выводе
Anthropic /v1/messages/count_tokens provider:anthropic.count_tokens
OpenAI /v1/responses/input_tokens provider:openai.input_tokens
Gemini /v1beta/models/<model>:countTokens provider:gemini.countTokens

Точные числа теряют ≈ и получают framing — токены, которые не принадлежат ни одному компоненту, например переписку и преамбулу вызова инструментов. ctxray кеширует их в tokens.db в папке своего кеша, так что один и тот же текст не считается дважды. У Chat Completions эндпоинта для подсчёта нет, поэтому у Cursor CLI и провайдера OpenCode по умолчанию остаются оценки. В режиме offline ctxray точный счёт не запрашивает. Про upstream и ключи рассказывают Configuration и Enterprise.

По файлам нельзя узнать, сколько стоят системный промпт, встроенные инструменты и схемы MCP-инструментов. inspect показывает их как «после запуска»: ctxray посчитает их, когда запустит харнесс, начиная с L4.

Бэкенды модели

Тесты начиная с L4 запускают настоящий харнесс, а харнесс разговаривает с моделью. ctxray стоит между ними и решает, кто отвечает:

Бэкенд Кто отвечает Цена
mock Ваш тест говорит, что ответит модель, ход за ходом. Повторный ход получает тот же ответ бесплатно, детерминированно
replay Записанные раньше ответы из __cassettes__/ рядом с файлом теста бесплатно, детерминированно
real Настоящая модель, через вашего провайдера или шлюз и ваш ключ сколько возьмёт провайдер

По умолчанию работает mock. L4 и L5 всегда идут на нём, какой бы бэкенд вы ни выбрали: они проверяют, что харнесс отправляет, а не что отвечает модель. L6 и L7 нужна модель, которая отвечает сама, поэтому на mock они пропускаются. Запустите их один раз с --backend real --record, чтобы сохранить ответы, а потом на каждом merge request бесплатно с --backend replay.

ctxray test --backend real --record --budget 2
ctxray test --backend replay

Бэкендам можно дать имена в конфиге, например backends: { pr: "replay" }, и выбирать их через --backend pr или CTXRAY_BACKEND. Кассеты и бюджеты показаны на странице Writing Tests, а где какой бэкенд уместен — на странице CI Integration.

Clone this wiki locally