# Audit > Шаг 3 пайплайна разработки приложений: проверяет документы в docs/ на полноту, согласованность, трассируемость BR → FR → компоненты → changes/задачи и соответствие EARS, выносит вердикт READY / READY WITH CONDITIONS / NOT READY в docs/06-audit-report.md. Триггеры: /audit, «проверь документацию», «готовы ли мы к разработке», «проверь спеки на EARS». - Skill: `oastashev/audit` (Agent Skill) - Install (CLI): `npx skillmds@latest add oastashev/audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/oastashev/audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: oastashev (https://skillmd.com/u/oastashev) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/oastashev/audit --- # /audit — проверка готовности документации к разработке Задача — ответить на один вопрос: можно ли по этим документам запустить `/kickoff` и отдать проект Claude Code так, чтобы разработка не упёрлась в отсутствующее решение на второй день. Аудит читает всё, ничего не придумывает и не переписывает документы без разрешения. Результат — `docs/06-audit-report.md` с вердиктом и списком находок. ## Правило остановки После отчёта (и, если пользователь согласился, исправления мелких находок) шаг закончен. Не запускай `/kickoff`, не пересобирай документы с крупными проблемами сам — для этого есть `/assemble ` и `/explore`, и решение о пересборке принимает пользователь. ## Как задавать вопросы Любой вопрос пользователю — только через `AskUserQuestion`, с готовыми вариантами ответа: 2–4 конкретных варианта, рекомендуемый — первым с пометкой «(Recommended)». Вопрос обычным текстом в ответе — нарушение: пользователь ждёт кликабельные варианты. В этом скиле развилок немного (выбор папки, что делать с Minor-находками, приложить ли недостающие файлы), но все они идут через этот инструмент. ## Где живут файлы Как у остальных шагов: подключённая папка проекта (`docs/`, при наличии — `openspec/`) → `AskUserQuestion` «Подключу папку сейчас (Recommended)» / «Работать в документах Project» → документы claude.ai Project под теми же путями (`project_read` / `project_write`) + `SendUserFile`. Состояние — `docs/STATUS.md`. В режиме Project-документов `openspec/`, `AGENTS.md` и `CLAUDE.md` недоступны — их создаёт init-kickoff уже в репозитории; повторный аудит спецификаций возможен только в подключённой папке репозитория или по файлам, которые пользователь приложит. Скажи об этом в отчёте, а не пропускай молча. ## Что проверяем ### 0. Состав и состояние Прочитай `docs/STATUS.md` и все документы `00`–`05` целиком, а также `docs/07-kickoff.md`, `openspec/` и `AGENTS.md`, если они уже есть (повторный аудит после `/kickoff` или init-kickoff). Документ отсутствует или в статусе `draft`/`stale` — это уже находка уровня Blocker/Major, но аудит всё равно доводи до конца: пользователю нужен полный список, а не первая ошибка. Исключение — exploration, пропущенный по решению пользователя (BRD §1 об этом говорит явно): тогда проверяй, что BRD §5–§7 содержат то, чего не хватает, — карту capabilities с ID и описаниями (их возьмёт init-kickoff для `## Purpose`), non-goals, выбранное направление, — и ставь Major, а не Blocker, если чего-то из этого нет. Для больших комплектов (суммарно больше ~60 КБ — это уже около 25 000 токенов кириллицы в одном контексте) распараллель чтение: по одному субагенту (`Agent`) на документ с чек-листом ниже и просьбой вернуть находки в формате таблицы находок; сводить и выносить вердикт — самому. Субагенту передавай пути к файлам и чек-лист, а не свои выводы, чтобы получить независимый взгляд. ### 1. Полнота каждого документа Сверь с шаблонами `/assemble`: все разделы присутствуют и содержат содержимое, а не заглушки. Особые точки: - exploration: выбранное направление, карта capabilities с ID, non-goals; - BRD: измеримые KPI, приоритеты MoSCoW у всех BR, критерии приёмки; - TRD: каждая CAP-xx покрыта хотя бы одним FR; NFR по всем категориям (развёртываемость, производительность, надёжность, безопасность, масштабируемость, доступность, локализация, наблюдаемость, сопровождаемость) — либо явное «не применимо, потому что…»; требования к данным и ПДн; - SAD: ADR-01 фиксирует Clean Architecture с привязкой слоёв к компонентам; ADR для каждого нетривиального выбора (БД, хостинг, фреймворк, auth); §4 называет линтер и форматтер для языка; таблица «NFR → как обеспечивается → как проверяется»; §7 называет целевое окружение для walking skeleton и путь доставки сборки в него; - SDD: реестр интерфейсов IF-xx с привязкой к модулям и FR (полные контракты должны быть в DDD §4, а не продублированы здесь), модель данных с инвариантами, обработка граничных случаев, стратегия тестирования; - DDD: план изменений CH-xx с нулевым change walking skeleton (CH-00) и каркасом CH-01; детальный дизайн модулей, контракты API и задачи T-xxx с критериями готовности — для CH-00–CH-02 (их отсутствие у дальних changes — норма, а не находка: их достроит Claude Code по актуальному коду); структура репозитория, разложенная по слоям Clean Architecture; DoD; соглашения для AGENTS.md с правилами слоёв и линтером (их отсутствие — Major: без них init-kickoff не соберёт AGENTS.md, а `001` останется без задач на линтер). ### 2. Согласованность и трассируемость - Цепочка `BR → FR/NFR → C → M/IF/E → CH → T` замкнута в обе стороны: нет BR без FR, FR без компонента, Must/Should FR/NFR без change в DDD §7, задач без FR («осиротевшие» задачи часто означают невысказанное требование). Задачи T-xxx проверяй только для FR/NFR из CH-00–CH-02: у дальних changes их по замыслу нет, хвост цепочки для них заканчивается на CH-xx. - Версии в шапках: каждый документ основан на актуальной версии предыдущих (STATUS `stale` или расхождение версий — Major). - Противоречия между документами: стек в exploration vs SAD, границы MVP в BRD vs план изменений в DDD, NFR-значения в TRD vs SAD. - Терминология: одни и те же сущности называются одинаково во всех документах и в глоссарии. - Дублирование: контракт API описан только в DDD §4, требование — только в TRD §3. Дубль — Minor; разошедшийся дубль (две несовпадающие версии одного контракта или требования) — Major. ### 3. Качество требований (EARS) Для каждого FR/NFR в TRD проверь: - формулировка соответствует ровно одному шаблону EARS (`The … SHALL`, `WHEN …, the … SHALL`, `WHILE …`, `IF …, THEN …`, `WHERE …`, комбинация `WHILE … WHEN …`) и написана по-английски; - ровно один `SHALL` и одно действие; нет `and`/`or`, склеивающих два поведения; - нет слов-маркеров неоднозначности: `should`, `may`, `might`, `could`, `appropriate`, `adequate`, `user-friendly`, `fast`, `easy`, `etc.`, `and/or`, `as needed`, `if possible`, `TBD` внутри требования; - проверяемость: есть число, состояние или наблюдаемый результат; для NFR — конкретная величина и условия измерения; - есть хотя бы один сценарий приёмки `WHEN … THEN …`, и он не повторяет требование дословно; - у требования есть приоритет и источник BR-xx. Считай долю требований, прошедших проверку, и приводи её в отчёте — это самая наглядная метрика зрелости TRD. ### 4. Готовность к OpenSpec и Claude Code - Capabilities названы в kebab-case по-английски и пригодны как имена `openspec/specs//`. - Нулевой change в DDD — walking skeleton: минимальное приложение, запускаемое в целевом окружении из SAD §7, без БД, auth и CI, с NFR развёртываемости; первый — каркас проекта (CI, БД, тесты), к нему привязаны остальные сквозные NFR (оба станут спецификацией capability `platform`); остальные — вертикальные срезы с проверяемым результатом, зависимости указаны и не образуют цикла. Каждое Must/Should FR/NFR отнесено ровно к одному change. - Каждая задача T-xxx из CH-00–CH-02 выполнима за одну сессию Claude Code (ориентир — меньше дня работы) и имеет критерий готовности. - Есть всё для AGENTS.md: стек, команды сборки/тестов/линтера/деплоя, слои Clean Architecture с каталогами, соглашения, DoD. - Все `Must`-требования не содержат `[TBD]`/`[ДОПУЩЕНИЕ]` без решения; открытые Q-xx, помеченные «нужен к /kickoff» или раньше, закрыты. Если `docs/07-kickoff.md` уже существует — проверь волны выполнения так же строго, как отсутствие цикла: волна каждого change больше волны любой его зависимости; внутри волны модули M-xx (по SDD §1 «Реализует FR») попарно не пересекаются; волны 0 и 1 содержат только `000` и `001`; номера `NNN` не убывают по волнам, `002` соответствует CH-02; числа §2а (последовательно, параллельно, экономия) пересчитываются из таблицы. Ошибка в волнах — Major: параллельные агенты столкнутся в одних файлах. Если есть и `openspec/` — строка `- Wave: N` в каждом `proposal.md` совпадает с дорожной картой. Если `openspec/` уже существует — дополнительно проверь, что спецификации следуют формату `### Requirement:` / `#### Scenario:` (ровно четыре решётки) с EARS-формулировками и `SHALL`, что новые capabilities имеют `## Purpose`, что `openspec/config.yaml` парсится как YAML и содержит правила EARS (CLI молча игнорирует нечитаемый config), и что каждое Must/Should-требование TRD встречается ровно в одном change. При наличии CLI (`openspec --version`; можно установить `npm install -g @fission-ai/openspec@latest`) запусти `openspec validate --all --strict` и включи вывод в отчёт. Помни, что валидатор проверяет только структуру и наличие `SHALL`/`MUST` — соответствие EARS-паттернам и качество сценариев проверяешь ты. ## Классификация находок | Уровень | Смысл | Что делать | |---|---|---| | Blocker | Без этого разработка остановится или пойдёт не туда: нет документа, нерешённый Must, противоречие в стеке, разорванная трассируемость целой capability | Пересобрать документ (`/assemble `) или вернуться к `/explore` | | Major | Документ есть, но существенно неполон: нет ADR, NFR без чисел, много FR не по EARS, задачи без критериев | Пересобрать раздел через `/assemble ` | | Minor | Локальная правка: одна формулировка, пропущенная ссылка, опечатка в ID, отсутствующая строка в матрице | Можно исправить прямо сейчас | Вердикт: - **READY** — нет Blocker и Major; Minor допустимы. - **READY WITH CONDITIONS** — нет Blocker, есть Major, которые можно закрыть до конца каркаса (CH-01) или не затрагивают CH-00–CH-02; условия перечислены явно. - **NOT READY** — есть хотя бы один Blocker. ## Отчёт `docs/06-audit-report.md` ```markdown # Audit report: <название проекта> Версия: N · Дата: YYYY-MM-DD · Проверенные версии: exploration v1, BRD v2, TRD v1, SAD v1, SDD v1, DDD v1 ## 1. Вердикт READY | READY WITH CONDITIONS | NOT READY — одним абзацем почему. ## 2. Сводка | Документ | Статус в STATUS | Blocker | Major | Minor | Доля FR/NFR, соответствующих EARS: NN % (X из Y). Трассируемость: BR без FR — n; Must/Should FR/NFR без change — n; FR из CH-00–CH-02 без задач — n; задачи без FR — n. ## 3. Находки | ID | Уровень | Документ / раздел | Что не так | Почему важно | Что сделать | Куда возвращаться | | F-01 | Blocker | TRD §3 CAP-04 | … | … | … | /assemble TRD | ## 4. Условия (для READY WITH CONDITIONS) | Условие | До какого change должно быть закрыто | Кто | ## 5. Проверка EARS — детали | FR | Проблема | Предложенная формулировка | ## 6. Что проверено и признано хорошим Коротко — чтобы пользователь видел, что аудит был полным, а не только список претензий. ``` ## После отчёта 1. Запиши отчёт, обнови `docs/STATUS.md` (строка `audit`: вердикт и дата). 2. Покажи вердикт и 3–5 самых важных находок в чате. 3. Если есть Minor-находки — `AskUserQuestion`: «Исправить Minor прямо в документах сейчас» / «Не трогать, исправлю сам» / «Показать список правок до применения». При согласии вноси правки точечно (`Edit`, не перезапись), поднимай версию документа, добавляй строку в его журнал изменений (последний раздел документа, см. шаблоны `/assemble`), помечай находку в отчёте как `fixed`. После правок обнови в шапке отчёта «Проверенные версии» на новые версии документов и дату аудита — именно по ним `/kickoff` решает, актуален ли аудит; статус `approved` у исправленных документов сохраняется. Blocker и Major в документах не правь: покажи, какой шаг перезапустить, и остановись. 4. Если вердикт READY / READY WITH CONDITIONS — скажи, что следующий шаг `/kickoff`, и остановись. Не запускай его. ## Чего не делать - Не смягчать вердикт, потому что «в целом неплохо»: NOT READY при одном Blocker — это и есть польза аудита. - Не раздувать отчёт стилистическими замечаниями — они уместны только как Minor и только если мешают пониманию. - Не переписывать требования за автора в документах без согласия; в отчёте предложить формулировку можно и нужно. - Не задавать вопросы обычным текстом — только `AskUserQuestion` с вариантами. - Не переходить к `/kickoff`.