evidence-wiki: у каждой цифры — источник

Знакомься: Алина — продуктовый аналитик. Шестую неделю она ведёт исследование по выходу B2B-продукта на новый рынок: сорок с лишним документов, десятки цифр, три папки черновиков. На совещании руководитель спрашивает: «Откуда у нас 37 % в оценке рынка?» Алина открывает документ — цифра есть, а откуда она взялась, не написано. Ни ссылки, ни расчёта. Три недели назад она это точно помнила.

Именно от этой ситуации и существует evidence-wiki. Это плагин для Claude Code, который делает две вещи:

1. Дисциплина источников. Следит, чтобы у каждого фактического утверждения в твоих документах был источник прямо в тексте, рядом с утверждением — а не «где-то в голове автора». Источник должен опираться на три типа документов — в пакете их называют «три кита»: решение (ADR), методика расчёта, исследование. Типы можно поменять под свой проект.
2. Слой концепт-страниц. Поверх твоих документов строит атомарные страницы по каждому ключевому понятию, явный граф связей между ними и JSON-индекс, по которому модель (или ты) достаёт ровно нужный контекст, не перечитывая весь корпус. Это идея LLM-Wiki, которую предложил Андрей Карпаты: каждая страница читается без контекста.

Третья часть — автоматизация: команды /wiki-generate и /triple-check, governance-шард и git-хук на pre-commit, чтобы дисциплина не зависела от памяти.

Пакет опубликован: страница @dzhechkov/evidence-wiki на npm, исходники — в монорепозитории dz-harness на GitHub.

Компромисс: ты платишь тем, что каждую цифру придётся сразу снабжать ссылкой — это медленнее, чем писать «как думается». Взамен через месяц любое утверждение прослеживается до источника за один переход, а не за час раскопок.

💬 Как это выглядит в работе. Команды плагина — это слэш-команды внутри Claude Code: ты пишешь /triple-check researches/ в диалоге, и ассистент выполняет проверку. Никакого отдельного бинарника ставить не нужно.

Вот что обнаружила Алина, когда разложила свой хаос по полочкам: в первую неделю ни одной из проблем не было. Она помнила каждую цифру, а сорока документов ещё не существовало. Болезни появились не от небрежности — от длины.

README пакета называет две болезни длинного ресерча, и полезно видеть, что это разные диагнозы:

1. Свалка утверждений. Утверждения копятся, а ссылки на источник — нет. Через месяц ты уже не помнишь, откуда взял цифру, и не можешь ни защитить её, ни поправить. Это болезнь *доверия*.
2. Потеря навигируемости. Документов становится столько, что найти всё, что относится к одному понятию — например, к модели ценообразования, — значит перечитать половину корпуса. Это болезнь *доступа*.

Прежде чем читать дальше, ответь себе: какая из двух у тебя болит сильнее прямо сейчас? Запомни ответ.

Две болезни — два лекарства, и у плагина они разные:

• от свалки лечит дисциплина источников: /triple-check выносит вердикт каждому факту и ловит «дрейф» — команда помнит, откуда цифра, даже когда ты уже забыл;
• от потери навигации лечит атомарный граф концептов: /wiki-generate собирает по странице на понятие и граф «концепт → решение / методика / исследование», по которому достаётся ровно нужный контекст.

У Алины оказалось обе: цифра без источника — свалка; а чтобы ответить, что известно про сегмент клиентов, ей пришлось открыть одиннадцать файлов — навигация.

Компромисс: лечить обе болезни сразу — значит запустить и проверку, и генерацию, а это два разных ритма работы: проверка после каждого документа, генерация — когда документов стало много. Зато ни одно лекарство не мешает другому: можно начать только с /triple-check и добавить вики позже.

Прежде чем что-то запускать, Алина открыла каталог плагина — и обнаружила, что он меньше, чем звучал. Весь состав плагина умещается в семь каталогов, и у каждого одна роль:

• .claude-plugin/plugin.json — манифест: какие навыки и команды подключаются, а в секции config — настройки по умолчанию (где лежит вики, какие типы источников, сколько китов на концепт).
• skills/concept-wiki-generator/ — единственный навык; в нём описан восьмишаговый конвейер генерации страниц.
• commands/ — две слэш-команды: wiki-generate.md и triple-check.md (валидатор).
• governance/triple-pillar.governance.md — спецификация протокола «три кита», написанная без привязки к конкретному проекту.
• shards/triple-pillar.shard.md — образец того, как этот протокол применяют в одном конкретном проекте: с реальными путями adrs/, methodologies/, researches/. Его копируют в .claude/shards/ своего проекта и правят.
• hooks/ — hooks.json (хук Claude Code, который после правки файла запускает проверку в мягком режиме) и два git-хука: bash и PowerShell.
• templates/ — шаблон концепт-страницы и шаблон конфигурации triple-pillar.config.yaml.

Смотри на схему ниже как на карту: спецификация — в governance/, её применение в проекте — в shards/, исполнение — в commands/ и hooks/. Алина сформулировала для себя так: «правило, пример правила, и кто это правило выполняет».

Компромисс: три слоя (спецификация → шард → команды) дают гибкость под любой домен, но новичку легко перепутать, где что править. Правило простое: общий протокол не трогаешь, правишь только шард и конфигурацию под свой проект.

Хватит разглядывать — Алина ставит плагин, и ты вместе с ней. Путь короткий, три шага, и только один из них требует подумать.

Шаг 1 — установить плагин. README даёт два способа:

• из marketplace — /plugin install evidence-wiki (README честно помечает: «когда опубликован»);
• локально, из корня репозитория плагина: cp -r . ~/.claude/plugins/evidence-wiki/.

Шаг 2 — положить конфигурацию в проект. Скопируй шаблон в корень своего исследования:

cp ~/.claude/plugins/evidence-wiki/templates/triple-pillar.config.yaml .

Вот здесь и надо подумать. В шаблоне три типа источников с путями по умолчанию: adr → adrs/*.md, methodology → methodologies/*.md, research → researches/*/. Если твои каталоги называются иначе — а README прямо предупреждает, что не у всех есть именно ADR, методики и исследования, у кого-то это decision / model / experiment, — поправь pillar_types и pillar_paths. Проверка ищет источники по этим путям; конфигурация под проект — это в первую очередь совпадение путей с тем, что реально лежит на диске.

Остальные ключи из plugin.json разумно оставить как есть: wiki_dir: wiki, concept_dir: wiki/concepts, min_pillars_per_concept: 3, маркеры обратных ссылок, triple_check_mode: advisory и порог triple_check_missing_threshold: 3.

Шаг 3 — первичная генерация. /wiki-generate — но только когда есть, из чего генерировать. У Алины на шестой неделе было из чего; на первой она бы получила пустую вики.

Компромисс: один YAML-файл настраивает всё — просто, но именно поэтому ошибка в одном пути молча оставит целый тип источников без проверки. Открой конфигурацию и сверь пути с ls — это минута.

💬 Словами. В Claude Code достаточно сказать: «поставь evidence-wiki и подготовь конфигурацию под мои папки decisions/, models/ и experiments/» — ассистент скопирует шаблон и поправит пути; тебе останется сверить результат.

Первый вопрос, который задала Алина перед запуском проверки, звучал неожиданно: «А что, теперь к КАЖДОМУ предложению ссылку?» Нет. И граница здесь — самое интересное место пакета.

Фактическое утверждение (в документации пакета — *factual claim*) — это предложение, которому нужен источник. Команда /triple-check приводит таблицу, что считается, а что нет:

• Считается: числа, проценты, метрики; заявления о конкурентах; рыночные данные и бенчмарки; ссылки на регуляторные требования; заявления о технических возможностях («поддерживает X»); финансовые проекции — ROI, TCO.
• Не считается: описания собственного продукта; персоны пользователей, которые явно вымышлены; описания процессов; архитектурные диаграммы; заголовки; отдельно стоящие картинки.

Теперь попробуй сам, без подсказки: фраза «наш сегмент — руководители отделов в компаниях от 200 человек» — утверждение или нет? Не торопись, ниже сверим.

Кроме таблицы есть зоны, куда проверка вообще не смотрит: блоки кода (там могут быть числа, которые не являются утверждениями), YAML-заголовок файла, HTML-комментарии и автоматически сгенерированные секции обратных ссылок между маркерами <!-- wiki:see-also-start --> и <!-- wiki:see-also-end -->. А если детектор срабатывает на художественном тексте — есть маркер <!-- triple-check:ignore -->, чтобы выключить проверку точечно.

Вернёмся к фразе про сегмент. Число «200» есть — и детектор пометит предложение как утверждение. Но это описание *собственного* решения о целевом сегменте, а не факт о мире. Алина решила так: цифру про размер компаний она подкрепила ссылкой на своё же решение — ADR о выборе сегмента. Это честно: источник здесь — не внешний отчёт, а документ, где выбор обоснован.

Компромисс: таблица «считается / не считается» даёт быструю границу, но детектор — это классификатор на модели, и на пограничных фразах он ошибается в обе стороны. Лишняя ссылка стоит дёшево; пропущенный факт — дорого. Сомневаешься — ставь источник.

Алина запустила /triple-check researches/market-sizing/ — и получила отчёт, в котором каждое утверждение помечено одним из четырёх слов. Разберём, откуда они берутся, потому что эту таблицу ты встретишь трижды: здесь, в упражнении и в финальном тесте — так и задумано.

Для каждого утверждения проверка ищет источник в том же абзаце (или в скобке «см. …» после предложения) и выставляет четыре признака: has_adr, has_methodology, has_research, has_external_url. Из них по таблице складывается вердикт на каждое утверждение:

• GOLD — есть все три кита: решение, методика и исследование. Полная дисциплина.
• OK — достаточная опора: решение + исследование; или методика + внешняя ссылка; или хотя бы одно исследование.
• WEAK — только внешняя ссылка. Проверка предупреждает, но не блокирует: внешние источники низкого уровня доверия рискованны.
• MISSING — голый факт, источника нет вовсе. Это единственный вердикт, который блокирует.

Отчёт заканчивается машиночитаемым тегом-обещанием — по нему следующая фаза конвейера решает, идти ли дальше:

• <promise>TRIPLE_CHECK_PASSED</promise> — ни одного MISSING и ни одного WEAK;
• <promise>TRIPLE_CHECK_WARN</promise> — MISSING нет, но есть WEAK;
• <promise>TRIPLE_CHECK_FAILED</promise> — есть хотя бы один MISSING.

Три правила, которые Алина выписала себе на стикер: команда только читает и никогда не правит файлы; на WEAK она не блокирует, только предупреждает; MISSING — блок для шага QE в /feature-adr и для чекпоинта архитектуры в /casarium.

В её отчёте оказалось 4 MISSING из 31 утверждения — все четыре в одном абзаце про размер рынка, написанном «по памяти» на третьей неделе. Отчёт показал их списком «file:line — фрагмент» с подсказкой, куда добавить ссылку.

Компромисс: четырёхступенчатая шкала честнее бинарного «есть ссылка / нет ссылки» — она различает полную опору и одну внешнюю ссылку. Но и требует понимания: OK — это не «всё хорошо», а «достаточно, чтобы не блокировать».

Ты уже видел, ЧТО выдаёт проверка. Теперь — КАК, потому что Алина задала правильный вопрос: «А это вообще детерминированно или модель каждый раз решает по-разному?» Ответ: наполовину.

Пять шагов проверки — и у каждого свой исполнитель:

1. Разбор markdown — детерминированно. Файл делится на абзацы и предложения; код, YAML-заголовок, HTML-комментарии и секции обратных ссылок выбрасываются.
2. Детектор утверждений — модель haiku. Каждое предложение получает метку «утверждение / не утверждение»: есть ли число, название компании, заявление о возможности, регуляторная ссылка.
3. Поиск источников — детерминированно. Регулярные выражения ищут в том же абзаце ссылки на adrs/*.md или ADR-NNN, на methodologies/*.md или «(см. Методика: …)», на researches/*/, внешний http(s)-URL.
4. Вердикт — детерминированно, по таблице из прошлой секции.
5. Отчёт — модель haiku только форматирует.

Документ команды прямо запрещает брать для неё sonnet или opus: это классификация плюс таблица, а не творческая работа. Так что «по-разному» может решить только шаг 2 — и именно поэтому на пограничных фразах вердикт иногда плавает.

Что можно передать команде: один файл (/triple-check QUICKSTART.md), директорию (/triple-check wiki/concepts/), glob (/triple-check "wiki/**/*.md") или вообще ничего — тогда проверяются файлы, подготовленные к коммиту (git diff --cached --name-only -- '*.md').

Три сбоя, которые документ описывает заранее, и что делать:

• Файл не найден — опечатка в пути, проверь аргумент.
• 100 % утверждений MISSING — скорее всего документ не markdown или экзотического формата; проверь, что парсер видит именно markdown.
• Таймаут — файл больше 50 КБ; разбей на части.

Компромисс: модель на одном шаге из пяти делает проверку быстрой и дешёвой, но не полностью воспроизводимой. Если тебе нужна абсолютная повторяемость — её тут нет, и документ этого не скрывает.

На четвёртой неделе Алина забыла запустить проверку два дня подряд — и это нормально: дисциплина, которая держится на памяти, не дисциплина. README пакета формулирует это так: хук делает проверку независимой от того, помнишь ли ты про неё.

Хук не ставится сам. В hooks/ лежат два скрипта — pre-commit-triple-check.sh для bash (Linux, macOS, Git Bash) и .ps1 для PowerShell. Ставятся они в .git/hooks/pre-commit целевого проекта:

• Linux / macOS — симлинк: ln -s <plugin>/hooks/pre-commit-triple-check.sh .git/hooks/pre-commit и chmod +x;
• Windows PowerShell — копия: Copy-Item <plugin>\hooks\pre-commit-triple-check.ps1 .git\hooks\pre-commit.

Здесь <plugin> — корень установленного плагина, например ~/.claude/plugins/evidence-wiki или ${CLAUDE_PLUGIN_ROOT}. Ловушка, которую README называет прямо: направить core.hooksPath на каталог hooks/ нельзя — git ищет файл с именем ровно pre-commit, а в каталоге он называется иначе. Поэтому симлинк или копия под нужным именем.

Режим advisory или strict — главный переключатель, и живёт он в переменных окружения:

• TRIPLE_CHECK_MODE=advisory (по умолчанию) — хук печатает список проблемных мест, коммит проходит;
• TRIPLE_CHECK_MODE=strict — коммит блокируется, если MISSING больше порога TRIPLE_CHECK_MISSING_THRESHOLD (по умолчанию 3).

Если в коммите нет числовых утверждений без источника — хук молчит. Он пропускает автоматически сгенерированное: */wiki-backlinks.md, wiki/concepts/*.md и .claude/**.

Есть и второй хук — для самого Claude Code. В hooks.json описан PostToolUse: после каждого Edit или Write он прогоняет тот же скрипт с флагом --advisory-single <файл> с таймаутом 5 секунд и всегда завершается успешно — это подсказка в момент правки, а не блок.

Governance-документ предлагает путь внедрения по шагам, и Алина прошла его за неделю: 1) аудит — прогнать проверку по всем .md; 2) включить хук в advisory; 3) починить документы, где больше пяти MISSING; 4) перейти в strict с порогом 0.

Компромисс: advisory ничего не ломает, но и ничего не гарантирует; strict гарантирует, но встаёт поперёк срочного коммита. Обход git commit --no-verify существует, README помечает его как аварийный: он нарушает дисциплину, пользуйся только когда понимаешь причину.

На пятой неделе у Алины было 21 решение, 9 методик и 11 исследований — и она запустила /wiki-generate. Через несколько минут появился каталог wiki/ и тег <promise>WIKI_GENERATED_INCOMPLETE</promise>. Не ошибка — и сейчас станет ясно, почему.

Команда загружает навык concept-wiki-generator и проходит восемь шагов генерации:

1. Сканирование источников (haiku) — по путям из конфигурации; извлекаются имена, которые упоминаются хотя бы дважды.
2. Ранжирование кандидатов — по трём критериям концепта первого класса (следующая секция), сортировка по числу входящих ссылок.
3. Привязка китов (haiku) — для каждого кандидата ищутся его решение, методика и исследование.
4. Синтез атомарной страницы (sonnet) — wiki/concepts/{slug}.md по шаблону. Если кита нет — на странице появляется секция с тегом TRIPLE_PILLAR_INCOMPLETE и явное предупреждение.
5. Перекрёстные ссылки — [[wikilinks]] между концепт-страницами.
6. Обратные ссылки в источниках — в каждый ADR, методику и исследование вставляется секция между маркерами <!-- wiki:see-also-start --> и <!-- wiki:see-also-end -->; если маркеры уже есть, содержимое заменяется, остальной текст не трогается.
7. Индекс и граф (haiku) — wiki/INDEX.md и wiki/graph.json со всеми узлами и рёбрами, подсчёт метрик целостности.
8. Валидация — /triple-check по новым страницам; тег WIKI_GENERATED, если у всех концептов не меньше min_pillars_per_concept китов, иначе WIKI_GENERATED_INCOMPLETE.

Три формы вызова: /wiki-generate — полная регенерация; /wiki-generate <slug> — один концепт; /wiki-generate --check — только валидация, без генерации.

Теперь про INCOMPLETE. У концепта pricing-model нашлись решение и методика, а исследования — нет. Генератор не спрятал это: страница получила status: incomplete и предупреждение. Правило навыка звучит буквально: концепт без трёх китов помечается, а не скрывается. Алина решала, что делать, и выбрала не «убрать концепт», а написать недостающее исследование — и через день перегенерировать одну страницу командой /wiki-generate pricing-model.

README советует ритм: новый концепт — точечно, раз в неделю — полная регенерация.

Компромисс: генератор пишет в твои исходные файлы (обратные ссылки между маркерами) — это делает граф связным в обе стороны, но означает, что после каждого запуска в git появятся правки в источниках. Маркеры гарантируют, что затронуты только секции между ними.

Теперь ты решаешь сам. Алина показала тебе список кандидатов, которые генератор нашёл на шаге 2, и спросила: «Какие из них — концепты, а какие нет?» Критерии есть, применить их — твоя работа.

Концепт первого класса — доменная сущность, которая проходит все три критерия сразу:

1. появляется в QUICKSTART.md как именованный архитектурный или бизнес-элемент;
2. поддержана хотя бы одним решением (ADR);
3. поддержана хотя бы одной методикой или исследованием — числовым или фактологическим обоснованием.

Навык называет и то, что концептом не является: само решение (это кит, а не концепт), методика (тоже кит), отдельное мелкое решение по маленькой фиче — слишком мелко.

Из чего состоит атомарная страница wiki/concepts/{slug}.md:

• YAML-заголовок: slug, type: concept, title, pillars с тремя списками (adr, methodology, research), related_concepts, status (active / proposed / deprecated), last_updated;
• тело не длиннее примерно 80 строк: TL;DR — один абзац, читается без контекста; Three Pillars — три таблицы; Related Concepts — [[wikilinks]] с одной строкой про каждую связь; Context Bundle for LLM — нумерованный список минимальных файлов; Open Questions.

Шесть правил навыка, из которых Алина выделила три главных: страница ссылается на источник, а не копирует его — единственный синтезированный текст на ней — TL;DR; TL;DR атомарен — никаких «как сказано выше»; отсутствие кита помечается, а не прячется.

И одна ловушка из таблицы анти-паттернов: страница длиннее 100 строк теряет атомарность. Лечение — разбить на два концепта или вынести детали в кит. Второй анти-паттерн — скопировать решение из ADR на страницу: при изменении ADR страница разойдётся с ним.

Компромисс: три критерия жёсткие — многие полезные понятия в них не проходят, и вики получается меньше, чем хотелось бы. Зато каждая страница в ней читается за минуту и не устаревает вместе с источником, потому что не дублирует его.

Остановись на секунду и вспомни, как ты собирал контекст для вопроса «что мы знаем про ценообразование?» до этого курса. Алина отвечала честно: «открывала папки и читала, пока не надоест». Теперь сравни с тем, что появилось на диске после генерации.

Граф и context bundle — это вторая половина плагина, которая лечит потерю навигации. Три артефакта:

1. wiki/graph.json. Узлы четырёх типов: concept, adr, methodology, research — у каждого id, заголовок и путь к файлу. Рёбра четырёх типов: supported-by-adr, supported-by-methodology, supported-by-research и related-concept. И секция integrity — машинный отчёт о покрытии: сколько концептов с полными тремя китами и списки тех, у кого не хватает исследования, методики или решения.
2. wiki/INDEX.md. Каноническая карта всех узлов с таблицей покрытия китов — то, что читает человек.
3. Обратные ссылки в самих источниках: секция «Связано с (wiki)» между маркерами, со списком концептов и подписью, что правки между маркерами будут перезаписаны. Без них граф был бы направленным, но не связным: от концепта к решению дойти можно, а обратно — нет.

Зачем это модели. На каждой концепт-странице есть раздел Context Bundle for LLM — нумерованный список минимальных файлов, которые нужно подать в контекст, чтобы ответить про этот концепт: сама страница, её решение, её методика, ещё один-два якоря. Резолвер — или ты сам — подтягивает по любому концепту ровно этот набор, не перечитывая весь корпус. README формулирует результат так: граф, по которому достаётся ровно нужный контекст, даже когда исследование выросло до сотни документов.

Честно про будущее: MCP-резолвер /concept <slug>, который вернёт bundle одной командой, и векторный индекс для семантического поиска в README стоят в Roadmap с пустыми галочками. Сегодня bundle читаешь со страницы глазами или просишь ассистента собрать его по graph.json.

Компромисс: граф и индекс регенерируются целиком на шаге 7, поэтому всегда согласованы между собой — но ровно поэтому их нельзя править руками: следующая генерация перепишет. Правки идут в источники и концепт-страницы, а граф пересобирается.

Последний вопрос, который задала Алина, был практическим: «Мне теперь ставить ещё пять навыков, чтобы это работало?» README отвечает одной фразой: короткий ответ — нет. evidence-wiki — самодостаточный плагин, и это доказуемо, а не декларативно:

• в plugin.json в списке навыков только встроенный concept-wiki-generator;
• команды /wiki-generate и /triple-check не вызывают ничего внешнего;
• explore, goap-research-ed25519, problem-solver-enhanced, keysarium, keysarium-core не нужны — ни как зависимость, ни для установки;
• governance-протокол исторически пришёл из keysarium-core, но его спецификация вшита в плагин (governance/triple-pillar.governance.md).

Важнее список того, чего плагин не делает: он не проводит исследование. Это слой дисциплины и навигации *над* твоими каталогами. Как ты производишь исходные документы — твоё дело: обычных диалогов с Claude Code достаточно; навыки для сбора источников — например, goap-research-ed25519 с верификацией источников — README называет напарником, а не зависимостью. Близок по духу, но отдельный инструмент.

Перенастройка под чужой домен. Плагин домен-агностичен: вместо решений, методик и исследований можно объявить decision / model / experiment или standard / regulation / case-study — любые два и больше типов источников. Governance-документ добавляет к этому политику уровней доверия для внешних ссылок: от A (рецензируемые работы, официальные отчёты) до D (форумы — только для триангуляции, никогда как основной источник).

Происхождение. README сообщает, что плагин извлечён из проекта GenAI-Bundle-GTM и там провалидирован на 20 концептах, 21 решении, 13 методиках и 13 исследованиях, причём все 20 концептов — с полными тремя китами. Это цифры README, а не этого курса: проверить их можно по HARNESS_MANIFEST.md корневого репозитория, на который README ссылается.

Что ещё не сделано — и README не скрывает: /wiki-link-check (проверка всех вики-ссылок), векторный индекс, MCP-резолвер и перенос остальных модулей keysarium-core стоят в Roadmap с пустыми галочками. Одна честная нестыковка: таблица анти-паттернов в SKILL.md советует «перед коммитом запустить /wiki-link-check», хотя команды ещё нет. Читай это как план, а не как инструкцию.

Компромисс: самодостаточность означает, что плагин делает ровно две вещи и не пытается заменить ни исследователя, ни конвейер. Хочешь помощь в сборе источников — ставь напарника отдельно; хочешь проверку ссылок — пока руками.