Repository navigation
Policies RU
Каждый ctxray test проверяет два слоя без единого вашего теста. L1 Lint проверяет, что файлы агента разбираются, ссылки ведут куда надо, а размеры укладываются в лимиты. L2 Policy проверяет правила, которые ваша организация задаёт для контекста: лимиты токенов, запрещённые и обязательные MCP-серверы, файлы, которые должны быть в каждом репозитории. Оба слоя только читают файлы, не обращаются к модели и укладываются в миллисекунды, поэтому работают в каждом merge request. Здесь описаны политики, проверки линтера и их уровни, лимиты размера и baseline, с которым старый репозиторий переходит на ctxray, не исправляя всё сразу.
Политика — это элемент policies в конфиге. Каждая называет себя и говорит, что проверяет:
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
harnesses: { "claude-code": {}, codex: {} },
policies: [
{ id: "context-budget", maxTokens: { total: 25000, rules: 8000 } },
{ id: "no-public-mcp", denyMcp: ["jira"], requireMcp: ["github"] },
{ id: "agents-md", severity: "warning", requireFiles: ["AGENTS.md", "docs/adr/*.md"] },
],
});| Поле | Тип | По умолчанию | Значит |
|---|---|---|---|
id |
string |
обязательно | Уникальное имя. Его показывает отчёт, и унаследованная политика с тем же id сливается с этой |
severity |
"error" или "warning"
|
error |
warning сообщает о найденном, но прогон не роняет |
harnesses |
id харнессов | все харнессы прогона | Харнессы, к которым относится политика |
maxTokens |
{ total?, system?, rules?, skills?, mcp?, commands?, tools? } |
— | Лимиты токенов на весь контекст и по компонентам |
denyMcp |
string[] |
— | MCP-серверы, которых не должно быть в настройках |
requireMcp |
string[] |
— | MCP-серверы, которые должны быть в настройках |
requireFiles |
string[] |
— | Файлы, которые должны существовать, относительно корня проекта. Глоб проходит, если под него подходит хоть один файл |
Политика обязана что-то проверять: без maxTokens, denyMcp, requireMcp и requireFiles она останавливает прогон, и ctxray называет политику, которая ничего не проверяет. Две политики с одним id в одном файле — тоже ошибка.
ctxray проверяет каждую политику на каждом харнессе, к которому она относится, и показывает её под её id:
проверки ctxray
L2 policy context-budget
claude-code ✓ codex ✓
L2 policy no-public-mcp
claude-code ✗ codex ✗
L2 policy agents-md
claude-code ✓ 1 предупреждение codex ✓ 1 предупреждение
✗ claude-code › L2 policy › no-public-mcp
MCP-сервер «jira» запрещён
⚠ claude-code › L2 policy › agents-md
Нет файла docs/adr/*.md
denyMcp и requireMcp сравнивают имена с MCP-серверами, которые объявляют в проекте собственные конфиги каждого харнесса, например .mcp.json у Claude Code или .codex/config.toml у Codex.
L2 только читает файлы. Он знает, во что обходятся правила, скиллы и команды, но не знает системного промпта, встроенных инструментов и схем инструментов MCP: их отправляет только работающий харнесс. Поэтому лимиты делятся так:
| Лимит | Где проверяется |
|---|---|
rules, skills, commands
|
В L2 — на контексте, с которым сессия стартует в корне проекта, и ещё раз в L4 |
total, system, tools, mcp
|
Только в L4 |
В L4 ctxray один раз запускает каждый харнесс против mock-модели и сверяет первый запрос со всеми лимитами maxTokens. Эта проверка ничего не стоит и не требует теста, нужен только харнесс, который ctxray умеет запускать, как описано на странице Harnesses. Если L4 не запускается, эти лимиты остаются непроверенными. Политика, где есть только лимиты L4, в L2 не появляется вовсе, а политика с лимитами обоих видов проверяет статическую часть в L2. Ещё проверка L4 предупреждает, если одни и те же инструкции попадают к модели дважды.
L2 считает токены на вашей машине, поэтому это оценки. Лимит, близкий к реальному размеру, может пройти в L2 и не пройти в L4, где считается собственный запрос харнесса. Про exactTokens рассказано в Configuration.
Опубликуйте политики один раз, npm-пакетом или общим файлом, и пусть каждый репозиторий наследует их:
// ctxray.config.ts проекта
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
extends: "@acme/ctxray-config",
harnesses: { "claude-code": {}, codex: {} },
policies: [{ id: "agents-md", severity: "warning" }],
});Политика проекта с унаследованным id сливается с унаследованной поле за полем. Здесь проект сохраняет requireFiles организации и только понижает уровень. Политика с новым id добавляется в список. Сторона пакета показана на странице Enterprise, а полные правила слияния — в Configuration.
L1 работает на каждом харнессе прогона и проверяет всё, что тот читает: файлы инструкций, правила, скиллы, команды и конфиги MCP. Ошибка роняет прогон, предупреждение показывается, но прогон не роняет:
⚠ claude-code › L1 lint › файлы проекта
CLAUDE.md:8 Ссылка на missing.md никуда не ведёт broken-link
Последнее слово находки — её id. По нему проверку называют конфиг и комментарии-заглушки.
| Id | По умолчанию | Находит |
|---|---|---|
frontmatter |
ошибка в скилле, предупреждение в правиле Claude Code | Frontmatter, который не является валидным YAML, поэтому харнесс его игнорирует, или отбитый табами: такой скилл Claude Code и Codex не берут |
loose-frontmatter |
предупреждение | Невалидный YAML во frontmatter, который Claude Code и Codex всё же читают построчно, а более строгие инструменты — нет |
rule-field |
предупреждение | Поле правила Claude Code кроме paths или alwaysApply правила Cursor в виде строки вроде "true": и то и другое ни на что не влияет |
too-large |
ошибка | Файл больше 4 МиБ, который Claude Code пропускает целиком |
import-missing |
предупреждение |
@import несуществующего файла |
import-depth |
предупреждение |
@import, вложенный слишком глубоко, чтобы когда-нибудь загрузиться |
shadowed-command |
предупреждение | Команда, которую скрывает скилл с тем же именем |
no-description |
предупреждение | Скилл без описания: модели не по чему его выбрать |
long-description |
предупреждение | Описание скилла длиннее, чем оставляет список скиллов харнесса: 1 536 символов у Claude Code, 1 024 у Codex |
skill-listing |
предупреждение | Скиллы проекта не влезают в список скиллов харнесса. Claude Code отводит на него 1% окна модели, а скиллам, которые не влезли, оставляет только имя, и модель не выберет их по назначению. Codex отводит 2% и урезает все описания, а когда не влезают даже имена, выкидывает скиллы |
bad-json |
ошибка | JSON-конфиг, который не разбирается |
bad-toml |
ошибка | TOML-конфиг, который не разбирается, поэтому харнесс его игнорирует |
mcp-transport |
ошибка | MCP-сервер без command и без url
|
empty-file |
предупреждение | Пустой файл инструкций, который харнесс пропускает |
shadowed-file |
предупреждение | Файл инструкций, который Codex пропускает, потому что в папке побеждает другой |
skill-field |
ошибка | Скилл без name или description, которые нужны харнессу |
codex-budget |
предупреждение | Файлы AGENTS.md сверх байтового бюджета Codex: 32 КиБ, если project_doc_max_bytes не говорит иного |
bad-glob |
ошибка | Пустой глоб, глоб с незакрытой скобкой или глоб, который выходит из своей папки через ..
|
skill-name |
предупреждение | Имя скилла, которое принимают не все харнессы: используйте строчные буквы, цифры и дефисы, до 64 символов |
skill-folder-name |
предупреждение | Скилл, чьё имя расходится с именем его папки |
duplicate-skill |
предупреждение | Два скилла с одним именем в одной папке |
duplicate-text |
предупреждение | Два файла инструкций с одинаковым текстом, который модель читает дважды |
broken-link |
предупреждение | Ссылка на несуществующий файл |
dead-rule |
предупреждение | Правило, под глобы которого не подходит ни один файл репозитория, поэтому оно никогда не загрузится |
size |
по лимитам | Файл сверх лимита размера |
unread |
ошибка | Файл агента, который не читает ни один харнесс и на который не ссылается ни один прочитанный файл, поэтому он не доходит ни до одной модели |
other-harness |
предупреждение | Файл, который читает только харнесс вне прогона |
harness-differences |
предупреждение | Файл, который одни харнессы прогона читают, а другие нет, и ничто из прочитанного ими не говорит того же |
misnamed-file |
ошибка | Файл, названный или положенный почти правильно, который харнесс не читает: AGENT.md, .cursorrule, .claude/rule/, .agent/skills/, mcp.json в корне, скилл одним .md-файлом, правило .md в .cursor/rules. Находка называет файл, который ищет харнесс |
letter-case |
ошибка | Имя, которое отличается только регистром, как claude.md, .Claude/ или skill.md: на macOS и Windows харнесс может открыть его под правильным именем, в Linux и CI — нет |
absolute-path |
предупреждение | Путь в домашнюю папку или на диск Windows, как /Users/…, /home/…, ~/… или C:\…, в @-импорте, ссылке, paths или globs или в MCP-конфиге: у команды и в CI такого пути нет |
byte-order-mark |
ошибка | SKILL.md, который начинается с метки порядка байтов (BOM): Codex такой скилл пропускает |
not-shared |
предупреждение | Файл, который харнесс читает у вас, а у команды и в CI его нет: его скрывает .gitignore, он ещё не закоммичен или лежит за символической ссылкой за пределы репозитория. CLAUDE.local.md не в счёт |
broken-symlink |
ошибка | Файл агента или папка харнесса, чья символическая ссылка никуда не ведёт |
secret |
ошибка | Ключ, токен, пароль или закрытый ключ в файле, который читает модель. Находка называет вид и строку, но не значение |
personal-data |
предупреждение | Почта, телефон или номер карты в файле, который читает модель |
lint.rules задаёт уровень любой проверки по её id: error, warning или off.
export default defineConfig({
lint: {
rules: {
"broken-link": "error",
"harness-differences": "off",
"skill-name": { level: "warning" },
},
ignore: ["docs/archive/**"],
errorOnWarnings: false,
overrides: [
{ include: ["legacy/**"], rules: { "dead-rule": "off" } },
{ include: [".claude/skills/**"], harnesses: ["codex"], rules: { "skill-field": "warning" } },
],
},
});| Ключ | Значит |
|---|---|
rules |
Уровень каждой проверки по её id |
ignore |
Глобы от корня проекта: эти файлы L1 пропускает целиком |
errorOnWarnings |
Любое предупреждение роняет прогон, как ошибка. --error-on-warnings включает это на один прогон |
overrides |
Уровни и лимиты для части файлов: include (глобы, обязательно), harnesses (по умолчанию все), rules и limits
|
ctxray применяет сначала rules, затем по порядку каждое переопределение, которое покрывает файл: побеждает последний уровень. Глоб сопоставляется и с собственным путём файла, и с реальным путём за символической ссылкой.
--ignore-harness-differences, CTXRAY_IGNORE_HARNESS_DIFFERENCES=1 и ignoreHarnessDifferences: true выключают harness-differences, не трогая настройки линтера.
Комментарий в Markdown-файле глушит проверки только для этого файла. Без id он глушит все проверки, а текст после двоеточия объясняет ревьюерам причину:
<!-- ctxray-ignore -->
<!-- ctxray-ignore broken-link, size: ссылки ведут на сгенерированную документацию API -->L1 измеряет тело каждого скилла, тело каждой команды и каждый файл инструкций в строках, символах и токенах. Токены считает локальный токенизатор o200k, какой бы ни был харнесс. Сверх порога warning L1 предупреждает, сверх error — падает.
| Вид | К чему относится | Встроенный лимит |
|---|---|---|
skill |
тело SKILL.md
|
предупреждение сверх 500 строк |
command |
тело команды | предупреждение сверх 500 строк |
instruction |
CLAUDE.md, AGENTS.md, правило, любой другой файл инструкций | предупреждение сверх 40 000 символов |
Anthropic советует держать SKILL.md короче 500 строк, а Claude Code предупреждает об инструкциях длиннее 40 000 символов. Свои лимиты задайте в limits:
export default defineConfig({
limits: {
skill: { lines: { warning: 300, error: 500 }, tokens: { error: 5000 } },
instruction: { chars: { warning: 20000, error: 40000 } },
command: false,
},
});Порог, который вы не назвали, сохраняет встроенное значение. false выключает один порог, а false для целого вида — все проверки размера этого вида. Переопределение линтера с limits задаёт лимиты для отдельных папок поверх лимитов проекта:
lint: {
overrides: [{ include: ["docs/agents/**"], limits: { instruction: { chars: { warning: 60000 } } } }],
},Старый репозиторий редко проходит L1 и L2 с первого дня. Если исправлять всё до первого зелёного прогона, переход застрянет. Baseline записывает сегодняшние находки, и прогон падает только на новых:
ctxray baseline ctxray.baseline.json: 11 находок
Закоммитьте файл. ctxray test его читает, а ctxray baseline перезаписывает, когда вы что-то исправите
ctxray test читает ctxray.baseline.json из корня проекта и отбрасывает все известные находки. Проверка, у которой остались только известные находки, проходит, а сводка считает, что baseline придержал:
Baseline 11 находок из ctxray.baseline.json не уронили прогон
Находку узнают по харнессу, проверке, id, файлу и подробностям, без номера строки, поэтому правки выше по файлу не делают её новой. Исправили часть находок — запустите ctxray baseline ещё раз, чтобы файл уменьшился. --harness ограничивает baseline частью харнессов, --config выбирает конфиг. Baseline покрывает только L1 и L2: проверка стартового контекста в L4 учитывается всегда.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие