// Провести полный анализ соответствия спецификации OpenTelemetry. Парсит спецификацию с сайта, разбивает на секции с полным текстом, агенты верифицируют требования по коду и записывают результат в JSON, скрипт сборки детерминированно генерирует docs/spec-compliance.md.
| name | spec-analysis |
| description | Провести полный анализ соответствия спецификации OpenTelemetry. Парсит спецификацию с сайта, разбивает на секции с полным текстом, агенты верифицируют требования по коду и записывают результат в JSON, скрипт сборки детерминированно генерирует docs/spec-compliance.md. |
Скилл выполняет spec-first анализ соответствия реализации спецификации OpenTelemetry.
Результат - файл docs/spec-compliance.md с трассируемым чеклистом: каждое MUST/SHOULD требование привязано к конкретному файлу и строке в коде.
scripts/extract_requirements.py - разбивает спецификацию на секции по заголовкам, сохраняет полный текст каждой секции в sections.jsonscripts/generate_prompts.py - группирует секции в агентов (5-8 секций на агента), генерирует промпты с JSON-схемой выводаresults/<agent>.jsonscripts/assemble_report.py - детерминированно собирает docs/spec-compliance.md из JSON-результатовПовторный запуск скилла на том же коде должен давать те же статусы (found/partial/not_found/n_a). Формулировки пояснений могут отличаться (генеративная природа агентов), но статусы - нет.
Это достигается за счёт:
1 keyword = 1 requirement: каждое вхождение MUST/SHOULD = отдельная записьexpected_keywords: regex считает ключевые слова в тексте секции (пропуская код-блоки)Никаких ad-hoc скриптов: всё необходимое входит в скилл. Оркестратор только запускает скрипты и агентов.
Каждая секция классифицируется по двум осям:
Стабильность (определяется маркерами Status: в тексте спецификации):
Область применения (scope):
Ключевое правило: основной процент соответствия считается только по Stable + universal требованиям.
Известные условные секции:
| Подраздел спецификации | Фича | Почему условная |
|---|---|---|
| GetAll | GetAll Getter | Добавляется после stable релиза Getter |
| Resource detector name | Resource Detector Naming | Только для SDK с реализованными детекторами |
B3 Propagator и Prometheus Exporter ранее были условными, но теперь реализованы (ОтелB3Пропагатор, ОтелПрометеусЧитательМетрик) и считаются как universal.
Запусти Python-скрипт для парсинга всех страниц спецификации OTel.
ВАЖНО: Скрипт загружает 12 страниц с opentelemetry.io. Убедись, что есть доступ в интернет. При повторных запусках скрипт использует кеш из
<output_dir>/*.txt. Удали кеш-файлы для обновления.
python3 .github/skills/spec-analysis/scripts/extract_requirements.py /tmp/otel-specs
Скрипт:
##/###)/tmp/otel-specs/sections.jsonОжидаемый результат: ~200-250 секций, в сумме содержащих ~800+ ключевых слов MUST/SHOULD.
python3 .github/skills/spec-analysis/scripts/generate_prompts.py /tmp/otel-specs
Скрипт:
sections.jsonresults/<agent>.jsonagents.json (конфигурация с launch_prompt) и prompts/<agent>.md (промпты)Все критерии верификации, примеры false positive и правила n_a определены в
scripts/generate_prompts.py(константаAGENT_INSTRUCTIONS). Для изменения критериев - редактируй эту константу.
Ожидаемый результат: ~30-40 агентов.
ВАЖНО: Используй
agent_type: "general-purpose"(Sonnet), НЕexplore(Haiku). Haiku не обладает достаточной глубиной рассуждений для корректной верификации.
python3 -c "
import json
with open('/tmp/otel-specs/agents.json') as f:
agents = json.load(f)
for a in agents:
print(a['name'])
print(f'Всего: {len(agents)} агентов')
"
Каждый агент в agents.json содержит поле launch_prompt - готовый к использованию промпт.
Агент по этому промпту сам прочитает свой файл инструкций и выполнит анализ.
Запускай агентов волнами по 10 штук (не больше) за один tool-calling ход:
Для каждого agent из agents.json:
task(
agent_type = "general-purpose",
mode = "background",
name = agent["name"],
prompt = agent["launch_prompt"]
)
Порядок волн:
bash: sleep 60) - пауза для восстановления rate limitПочему 10, а не 36? Sonnet-агенты потребляют значительный rate limit. Запуск всех сразу приводит к массовым 429-ошибкам - агенты получают rate limit на первом же запросе и завершаются без результата.
total_turns: 0 и без файла результата. Будет перезапущен на шаге 3.5После завершения всех агентов проверь, что файлы записаны:
# Должно совпадать с количеством агентов
ls /tmp/otel-specs/results/*.json | wc -l
КРИТИЧЕСКИ ВАЖНО: Агенты обязаны вернуть данные по 100% секций и 100% ключевых слов. Повторяй до тех пор, пока все не будут пройдены. Rate limit - не причина остановиться.
После завершения всех агентов обязательно выполни проверку:
python3 -c "
import json, os
with open('/tmp/otel-specs/agents.json') as f:
agents = json.load(f)
missing = []
mismatched = []
for agent in agents:
name = agent['name']
path = f\"/tmp/otel-specs/results/{name}.json\"
if not os.path.exists(path):
missing.append(name)
continue
with open(path) as f:
result = json.load(f)
for section in result['sections']:
expected = section['expected_keywords']
actual = len(section.get('requirements', []))
if actual != expected:
mismatched.append(f'{name}: {section[\"section_id\"]} expected={expected} actual={actual}')
if missing:
print(f'❌ Отсутствуют результаты ({len(missing)}):')
for m in missing:
print(f' {m}')
if mismatched:
print(f'⚠️ Несовпадения keywords ({len(mismatched)}):')
for m in mismatched:
print(f' {m}')
if not missing and not mismatched:
print(f'✅ Все {len(agents)} агентов вернули корректные результаты')
"
Если агенты упали по rate limit (результат отсутствует, total_turns: 0 в read_agent):
bash: sleep 120) перед перезапуском - rate limit должен восстановитьсяlaunch_prompt из agents.jsonВолна повтора:
sleep 120
→ запусти 5 агентов
→ дождись завершения
sleep 120
→ запусти следующие 5
→ ...
НЕ ОСТАНАВЛИВАЙСЯ при rate limit. Увеличивай паузу и продолжай. Смена модели (например, на
claude-sonnet-4) допустима как крайняя мера, если основная модель заблокирована более 10 минут.
Если агент вернул неверное количество требований:
rm -f /tmp/otel-specs/results/<name>.jsonlaunch_prompt:⚠️ ПОВТОРНЫЙ ЗАПУСК: В предыдущей попытке количество требований не совпало.
Ошибки:
- Секция <section_id>: ожидалось <expected>, получено <actual>
Перечитай текст секции ВНИМАТЕЛЬНО и убедись, что нашёл РОВНО expected_keywords ключевых слов.
<оригинальный launch_prompt>
python3 .github/skills/spec-analysis/scripts/assemble_report.py /tmp/otel-specs docs/spec-compliance.md
Скрипт:
results/*.jsondocs/spec-compliance.md из git (HEAD)<output_dir>/comparison-report.txtdocs/spec-compliance.mdКатегории расхождений:
Для каждого расхождения указываются возможные причины:
Структура выходного документа:
docs/spec-compliance.md
├── Сводка (Stable) - общий процент, MUST/SHOULD отдельно, таблица по разделам
├── Ключевые несоответствия (Stable)
│ ├── MUST/MUST NOT нарушения
│ └── SHOULD/SHOULD NOT несоответствия
├── Детальный анализ по разделам (Stable) - каждая секция = ####, каждое требование = строка таблицы
├── Требования Development-статуса - с полными таблицами
├── Условные требования (Conditional) - с полными таблицами для Stable+conditional
├── Ограничения платформы OneScript
└── Методология
Каждая секция спецификации = отдельный подзаголовок (####). Каждое MUST/SHOULD = отдельная строка таблицы с полным текстом, статусом, расположением в коде и пояснением.
Скрипт scripts/assemble_report.py автоматически проверяет полноту:
📊 Валидация полноты:
Keywords в спецификации: 824
Требований от агентов (JSON): 824
Требований в markdown: 824
✅ Все 824 требований присутствуют (JSON: 824, markdown: 824)
Если total не совпадает (❌ ОШИБКА в выводе):
Сравнение выполняется автоматически в шаге 4. Скрипт записывает подробный отчёт расхождений в файл:
docs/spec-comparison-report.md
ВАЖНО: Отчёт сохраняется в файл в репозитории (рядом с
spec-compliance.md), а не выводится в терминал. Это критически важно, потому что он может быть очень большим (сотни строк) и вымывается из контекста при выводе в stdout. Всегда читай его из файла.
cat docs/spec-comparison-report.md
Если файл слишком большой, используй view tool для чтения по частям.
Обрати внимание на:
Если изменений много (>10 понижений или >20 пропущенных требований), дополнительно проверь diff:
git --no-pager diff docs/spec-compliance.md | head -100
git add docs/spec-compliance.md docs/spec-comparison-report.md
git commit -m "docs: обновить анализ соответствия спецификации OpenTelemetry vX.Y.Z
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"
При анализе учитывай, что OneScript не поддерживает:
Текущая версия спецификации определяется автоматически из заголовка страницы при парсинге. Если версия изменилась, обнови бейдж в README.md:
[](docs/spec-compliance.md)
[HINT] Download the complete skill directory including SKILL.md and all related files