Repository navigation
The Loadout Stack RU
ctxray проверяет настройку агента в семь слоёв, от дешёвых к дорогим. Каждый слой отвечает на один вопрос, и дешёвый слой ловит всё, что может, раньше дорогого. L1–L3 только читают файлы и проходят за миллисекунды. L4 и L5 запускают настоящий харнесс с mock-моделью, и это ничего не стоит. Только L6 и L7 обращаются к модели или воспроизводят её ответы, записанные один раз.
| Слой | Вопрос | Цена | Кто пишет |
|---|---|---|---|
| L1 Lint | Файлы разбираются, ссылки целы, всё доходит до каждого харнесса? | читает файлы | ctxray запускает сам |
| L2 Policy | Настройка соблюдает правила вашей компании? | читает файлы | ctxray, по policies из конфига |
| L3 Resolve | Какие правила и скиллы загрузятся для этой папки и этих файлов? | читает файлы | вы, через test.resolve
|
| L4 Assemble | Что харнесс на самом деле отправляет в первом запросе? | запускает харнесс с mock-моделью | вы, через test.assemble, и встроенная проверка стартового контекста |
| L5 Wire | Что добавляется в контекст по ходу сессии? | запускает харнесс с mock-моделью | вы, через test.wire
|
| L6 Activate | Выбирает ли модель нужный скилл или правило по промпту? | спрашивает модель | вы, через test.activate
|
| L7 Scenario | Проходит ли целая задача так, как должна? | спрашивает модель | вы, через test.scenario
|
Примеры ниже взяты из фикстуры payments самого ctxray. Полный API тестов описан на странице Writing Tests.
L1 проверяет каждый файл, который читает каждый харнесс: frontmatter, который не разбирается, @import в никуда, glob, под который не подходит ни один файл, скилл, чья папка не совпадает с именем, файл больше, чем принимает харнесс. Ещё он проверяет охват из Concepts: правило, которое читает один харнесс и никогда не получает другой. Писать для него ничего не нужно.
проверки ctxray
L1 lint файлы проекта
claude-code ✓ 1 предупреждение codex ✓
⚠ claude-code › L1 lint › файлы проекта
.claude/rules/web.md Ни один файл репозитория не подходит под frontend/**/*.tsx, правило никогда не загрузится dead-rule
Ошибки валят прогон, предупреждения видны, но не валят. С --error-on-warnings прогон падает и на предупреждениях. Каждая находка заканчивается id проверки, здесь dead-rule: по нему раздел lint в Configuration меняет её уровень. ctxray baseline записывает сегодняшние находки, и следующие прогоны падают только на новых, см. Commands.
L2 проверяет правила, которые задаёт ваша компания: лимиты токенов, MCP-серверы, которые обязаны быть или запрещены, файлы, которые должны существовать. Вы пишете их один раз в конфиге, и ctxray проверяет их для каждого харнесса без обращения к модели:
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
harnesses: { "claude-code": {}, codex: {} },
policies: [
{ id: "no-jira", denyMcp: ["jira"] },
{ id: "lean-rules", maxTokens: { rules: 2_000 } },
],
}); L2 policy no-jira
claude-code ✗ codex ✗
L2 policy lean-rules
claude-code ✓ codex ✓
✗ claude-code › L2 policy › no-jira
MCP-сервер «jira» запрещён
Лимит, на который файлы ответить не могут, например total с системным промптом и MCP-инструментами, переходит в проверку стартового контекста на L4, где ctxray видит настоящий запрос. Все проверки и то, как компания делится ими через общий конфиг, описаны на странице Policies.
L3 предсказывает Loadout по файлам: какие правила и скиллы загрузятся, когда агент стартует в папке и работает с какими-то файлами. Ему не нужны ни промпт, ни харнесс, поэтому он проходит за миллисекунды для каждого харнесса.
test.resolve("payments rules attach to payment sources", { requires: ["pathRules"] }, async ({ resolve }) => {
const l = await resolve({ cwd: "app", files: ["app/src/main/kotlin/payments/Charge.kt"] });
expect(l.rules).toInclude([".claude/rules/kotlin.md", ".claude/rules/payments.md"]);
expect(l.rules).not.toInclude(".claude/rules/web.md");
expect(l.rules.get(".claude/rules/payments.md").reason).toBe("glob:**/payments/**/*.kt");
});requires: ["pathRules"] пропускает тест на Codex, у которого нет правил по путям, и отчёт так и говорит.
L4 запускает настоящий харнесс на копии проекта, даёт ему собрать первый запрос и отвечает mock-моделью. Теперь ctxray видит то, чего не видно по файлам: системный промпт, встроенные инструменты и каждый MCP-инструмент со схемой.
test.assemble("context budget", async ({ assemble }) => {
const l = await assemble({ cwd: "app" });
expect(l.tokens.total).toBeLessThan(25_000);
expect(l.tokens.byMcpServer("jira")).toBeLessThan(3_000);
expect(l.mcp.servers).toEqual(["github", "jira"]);
expect(l).toMatchLoadoutSnapshot();
});Ещё ctxray сам запускает одну проверку L4 для каждого харнесса, который умеет запустить, — стартовый контекст. Так настоящий итог виден даже без тестов:
L4 assemble стартовый контекст
claude-code ✓ ≈ 17 009 токенов codex ✓ ≈ 8 227 токенов
Для L4 нужен git и харнесс в PATH или закреплённый в ctxray.lock. Как ctxray запускает его, не трогая ваши файлы и домашнюю папку, рассказывает страница Режимы захвата.
L5 ведёт сессию ход за ходом. Ваш тест играет модель: читает файл, вызывает инструмент или что-то говорит, а потом проверяет следующий запрос. Так видно, как вложенное правило попадает в контекст после чтения файла.
test.wire("nested instructions load on read", { requires: ["pathRules"] }, async ({ session }) => {
await session.model.calls("Read", { path: "app/src/main/kotlin/payments/Charge.kt" });
const next = await session.nextRequest();
expect(next.loadout.rules).toInclude("app/src/main/kotlin/payments/AGENTS.md");
expect(next).toAgreeWithResolver();
});toAgreeWithResolver() сравнивает то, что харнесс на самом деле отправил, с предсказанием L3. Если они расходятся, модель этой версии харнесса в ctxray устарела: тест падает и перечисляет правила и скиллы, которые загрузил только харнесс, и те, что предсказал только L3.
L6 несколько раз задаёт модели промпт и считает, как часто активировался скилл или правило. Результат идёт с доверительным интервалом, так что один удачный прогон тест не пройдёт.
test.activate(
"refund prompt → refunds skill",
{ prompt: "Make a partial refund of 40 EUR for order 123.", samples: 5, requires: ["skills"] },
({ runs }) => {
expect(runs).skill("refunds").toActivate({ min: 0.5 });
expect(runs).skill("payouts").not.toActivate({ max: 0.5 });
},
);Запишите ответы один раз с --backend real --record, а потом бесплатно воспроизводите их с --backend replay. ctxray gen-prompts набрасывает промпты по описаниям ваших правил и скиллов, см. Commands.
L7 даёт агенту целую задачу и позволяет работать, пока он не остановится, по умолчанию не больше 30 ходов модели. Потом тест проверяет прогон: какие скиллы и правила дошли до модели, какие инструменты вызвал агент и какие файлы он изменил.
test.scenario(
"a refund goes through the refunds skill",
{ prompt: "Make a partial refund of 40 EUR for order 123.", samples: 3, min: 0.6, requires: ["skills"] },
({ run }) => {
expect(run.skills).toInclude("refunds");
expect(run.changed).not.toInclude(".github/CODEOWNERS");
},
);min — доля прогонов, которые должны пройти, по умолчанию все.
ctxray test по умолчанию запускает все слои. --layer выбирает часть — списком, диапазоном или и тем и другим:
ctxray test --layer L1-L3 # только то, что читает файлы: на каждый коммит, за миллисекунды
ctxray test --layer L3,L5
ctxray test --layer 4-5В CI то же самое делает CTXRAY_LAYER. Тесты вне выбора помечаются как отфильтрованные.
L6 и L7 нужна модель, которая отвечает сама. На бэкенде mock, который работает по умолчанию, ctxray их пропускает и говорит, что им нужно:
L6 activate refund prompt → refunds skill
claude-code ○ нужен --backend replay или real codex ○ нужен --backend replay или real
L4 и L5 всегда работают с mock-моделью, какой бы бэкенд вы ни выбрали. Ещё тест может быть пропущен как неподдерживаемый, если у харнесса нет того, что тест указал в requires, или как недоступный, если ctxray не может запустить харнесс на этой машине. Бэкенды описаны на странице Concepts, а какие слои где запускать — на странице CI Integration.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие