Skip to content

The Loadout Stack RU

Pavel Erokhin edited this page Nov 16, 2026 · 1 revision

English version

ctxray проверяет настройку агента в семь слоёв, от дешёвых к дорогим. Каждый слой отвечает на один вопрос, и дешёвый слой ловит всё, что может, раньше дорогого. L1–L3 только читают файлы и проходят за миллисекунды. L4 и L5 запускают настоящий харнесс с mock-моделью, и это ничего не стоит. Только L6 и L7 обращаются к модели или воспроизводят её ответы, записанные один раз.

The Loadout Stack: L1 Lint, L2 Policy и L3 Resolve читают файлы. L4 Assemble и L5 Wire запускают ИИ-харнесс с mock-моделью. L6 Activate и L7 Scenario спрашивают модель.

Слой Вопрос Цена Кто пишет
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 Lint

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 Policy

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 Resolve

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 Assemble

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 Wire

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 Activate

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 Scenario

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.

Clone this wiki locally