Repository navigation
Concepts RU
Несколько идей проходят через все команды и тесты. Разберитесь с ними один раз, и остальная вики пойдёт быстрее.
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 и всё остальное.
Рядом с видом у каждого правила указана причина, по которой оно загрузилось в этот раз:
| Причина | Что значит |
|---|---|
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.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие