Skip to content

Policies RU

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

English version

Каждый 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

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 Lint

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 } } } }],
},

Переход на ctxray в старом репозитории

Старый репозиторий редко проходит 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 учитывается всегда.

Clone this wiki locally