AI Audit Project

ai-audit-project

Если результат аудита ведёт к существенной правке источника истины, сначала получи ai-work-control/full; сам аудит не повторяет этот контроль. Если соседний навык недоступен, выполни его полный контрольный набор по доступному контексту внутри текущей работы и продолжай. Не останавливай исправление только из-за невозможности отдельно загрузить ai-work-control.

Проверяй правила проекта как рабочую систему управления агентом: они должны помогать агенту действовать точнее, не конфликтовать между собой и не тратить контекст без пользы.

Назначение

Навык нужен для глубокого аудита набора правил, которые управляют поведением агента в репозитории. Он шире, чем проверка одного AGENTS.md: учитывает несколько форматов инструкций, локальные и глобальные навыки, символические ссылки, документацию для человека как контекст и проектные правила, которые могут конфликтовать между собой. README, docs/** и похожие файлы не становятся прямыми инструкциями для агента только из-за расположения или имени: как правила учитывай только явные обращения к ИИ, агенту, помощнику или инструменту автоматизации.

Контрольные маршруты проекта проверяй по рабочим навыкам:

• ai-work-control;
• ai-rule-failure-analysis;
• ai-work-result-evaluation.

Проверка поставляемой автоматизации

Для публичных команд и скриптов навыков проверяй не только наличие контракта, но и поведение на значимых вариантах входа.

1. Для Python-скриптов выполни доступный run-skill-script-contract-tests.py и дождись терминального результата. Инструмент выполняет сценарии evals/script-contract-tests.json, отклоняет вырожденные объявленные входы, считает ошибкой функцию скрипта, не выполненную ни одним сценарием и не объявленную в unexercised_functions с причиной, и печатает по каждому скрипту очередь невыполненных исполняемых строк. Успешный код возврата без разбора этой очереди не доказывает работоспособность автоматизации.
2. Ошибку о вырожденном входе или невыполненной функции устраняй только новым успешным сценарием, который доказуемо исполняет целевую ветвь: после правки фикстуры повтори запуск и убедись, что целевые строки исчезли из очереди, а функция — из ошибок. Данные, при которых проверка проходит, но целевая ветвь не исполняется, не являются исправлением. Пустая коллекция не покрывает обработку элементов, одна запись — взаимодействие записей. Не добавляй ещё одну пустую фикстуру и не заменяй существующий сценарий другого класса входа без доказательства эквивалентности.
3. Запись в unexercised_functions допустима только для защитного отказа или ветви, которую нельзя воспроизвести в переносимой фикстуре из-за внешней среды. Ветвь обработки данных обязана получить активирующий сценарий с проверкой значимых данных результата повторным чтением созданного файла, а не только кода возврата, stdout или наличия файла. Существующие записи unexercised_functions — предмет аудита: запись, скрывающая обработку данных, является находкой. Каждый оставшийся диапазон невыполненных строк классифицируй в текущем аудите: обработка данных получает сценарий, защитный отказ и внешняя среда — короткое обоснование в отчёте. Не переноси разбор очереди в остаточные риски, следующий аудит или бэклог. Вспомогательный тест вне контракта не заменяет контрактный сценарий.
4. Считай operations[].inputs путями или настройками внутри фикстуры, а не аргументами команды, если контракт явно не задаёт иное; интерфейс команды бери из процедуры навыка. Само присутствие пути в inputs или фикстуре не является покрытием: доказательство — данные результата, производные от входа. Если эффект не виден напрямую, сравни два запуска с минимально различающимися входами.
5. Не меняй исправную автоматизацию по предположению о назначении поля или команды. Если все документированные эффекты подтверждены, зафиксируй отсутствие находки и не расширяй контракт гипотетическими требованиями. Дефект сначала воспроизведи на копии фикстуры: сохрани команду, код возврата и неверные данные до правки, затем повтори тот же сценарий после правки. Исправление трассировщика или декларации входов не заменяет поведенческую проверку.

Проверка автоматизации не завершена, пока инструмент не завершился терминально, его ошибки не устранены доказуемо исполняющими сценариями или допустимыми записями unexercised_functions, а каждый диапазон невыполненных строк не получил активирующий сценарий либо названное в отчёте обоснование. Итог со словами «остаточный риск» вместо этого разбора — незавершённый аудит.

Когда применять

Применяй навык, если нужно:

• проверить правила проекта для агента глубже, чем обычный обзор одного файла;
• найти дубли, противоречия, неоднозначности, устаревшие места и лишнюю стоимость контекста;
• сравнить несколько источников инструкций для ИИ;
• упорядочить правила между AGENTS.md, другими файлами инструкций, навыками и явно адресованными агенту фрагментами документации;
• подготовить достаточные правки правил после найденных проблем;
• сопровождать набор правил в разных репозиториях.

Если задача ограничена только качеством одного или нескольких AGENTS.md без широкого аудита правил, применяй ai-audit-agents-md. Если нужно создать, изменить, сократить или разделить AGENTS.md, применяй ai-agents-md-maintenance. Если задача меняет сам навык, применяй ai-skill-development.

Обязательный порядок

1. Проверь, какой экземпляр этого навыка выполняется: каталог загрузки показан при запуске. Найди одноимённые копии навыка в остальных корнях навыков — пользовательском каталоге навыков, проектных каталогах и установленных коллекциях — и сравни их содержимое. Если загруженная копия отстаёт от сопровождаемой, сообщи об этом первой строкой, продолжай работу по процедуре самой свежей копии и зафиксируй расхождение как первую находку «устаревшая затеняющая копия навыка».
2. Уточни цель проверки, только если без этого нельзя безопасно продолжить: найти проблемы, предложить правки, внести изменения, сравнить текущее состояние с предыдущим или выдать полный отчёт.
3. Найди источники правил. Начни с AGENTS.md и известных файлов инструкций для агентов, затем ищи локальные правила по словам agent, AI, assistant, ИИ, instructions, rules, prompt, policy, guidelines. Если проект использует навыки, учитывай локальные, глобальные и подключённые символическими ссылками навыки, доступные агенту или явно упомянутые в проекте. Если проект является коллекцией навыков, публикуемой через APM или аналогичный механизм распространения, считай все публикуемые навыки частью источников правил проекта. В аудит входят .apm/skills/** или skills/**: SKILL.md, references/**, evals/**, agents/**, scripts/** и связи между ними. README.md и другая документация внутри дерева навыков тоже проверяются, но как контекст для человека, описание интерфейса навыка и место, где могут быть ошибочно размещены правила для агента. Не используй такую документацию как прямую инструкцию для агента, если в ней нет явного адресата или формулировки для ИИ.
4. Построй карту правил: файл, область действия, адресат, приоритет, повторяемые темы, обязательность, срок жизни и связь с инструментами.
5. Проверь проблемы: дубли, противоречия, неоднозначности, непроверяемые требования, устаревшие сведения, слишком широкие запреты, разрастание, смешение проектных и переносимых правил, локальные копии глобальных правил или правил из символических ссылок, устаревшие затеняющие копии навыков в других корнях, лишнюю нагрузку на контекст. Если проект объявляет команду проверки, выполни её как часть аудита. Успешным доказательством служат только терминальный код возврата и полный вывод команды. Если среда сообщает, что команда ещё выполняется, дождись результата штатным ожиданием или опросом. До терминального результата пометь проверку незавершённой и не называй аудит успешным. В APM-коллекции проверь объявленную scripts.tests. Если доступна оснастка ai-setup-apm, проверь найденные навыки по критерию исполнимого контракта выше. Отсутствие контракта — отдельная находка, а не причина пропустить её из-за успешного apm audit или ранних этапов другой команды.
6. Самостоятельно перепроверь выводы: для каждого существенного замечания найди подтверждение в текущем содержимом файлов или явно пометь его как предположение. Не используй в доказательствах строки из памяти, старых выводов или уже изменённых версий файлов.
7. По умолчанию исправляй подтверждённые проблемы, а не откладывай их. Собери контекст, ранжируй находки по влиянию, затем для каждой внеси правку, проверь результат и зафиксируй, что сделано. Откладывай исправление только в двух случаях: пользователь явно ограничил задачу диагностикой или прямо попросил отложить, либо конкретное исправление требует решения владельца — меняет смысл или область правил, конфликтует с более высоким приоритетом правил или труднообратимо. Во втором случае остановись только по этой проблеме, покажи варианты и рекомендацию, а остальные найденные проблемы продолжай исправлять. После отработки последней найденной проблемы явно сообщи, что все найденные проблемы отработаны. Для дефекта исполнимого контракта направление исправления не считается результатом: измени скрипт, контракт и фикстуру в доступной области, воспроизведи исходный отказ и выполни тот же сценарий после правки. Ответ в будущем времени без различия файлов и терминального результата проверки означает незавершённую работу. До первой правки сохрани в рабочем результате команду, код возврата и наблюдаемые неверные данные исходного запуска. Если расхождение не воспроизводится, не вноси предполагаемое исправление: продолжи аудит или назови ограничение доказательства.
8. Масштаб каждого исправления выбирай по причине проблемы и проверяемому эффекту. Сравни локальное уточнение, переработку структуры, удаление или объединение правил, перенос деталей в справку и обновление проверок. Меньший размер изменения не является преимуществом, если он оставляет тот же риск повторения.
9. После правок проверь результат: перечитай изменённые места, убедись, что новые формулировки не создают новых конфликтов, и назови остаточные риски. Перед итогом проверь барьер завершения: инструмент контрактных проверок завершился терминально без ошибок; каждый диапазон невыполненных строк получил активирующий сценарий либо обоснование в отчёте; исходный дефект воспроизведён; тот же сценарий после правки завершился терминально и подтвердил ожидаемые данные. Отсутствие любого свидетельства запрещает заявлять, что аудит или исправление завершены.
10. Не создавай запись в бэклоге, задачу, отчёт или другой отслеживающий артефакт вместо недоступного исправления, если пользователь прямо не попросил зафиксировать проблему или более приоритетное правило однозначно не разрешает автоматическую запись. Правило о месте хранения открытых задач определяет путь только после получения такого разрешения. Если исправление лежит вне разрешённой области проекта, сообщи точный блокер и необходимое внешнее изменение без записи в чужой проект.

Что читать дополнительно

• references/audit-checklist.md — полный проверочный список и формат отчёта.

Границы

• Не превращай аудит в переписывание всех правил с нуля, если цель — диагностика.
• Не удаляй правило только потому, что оно повторяется: сначала проверь, не задаёт ли повтор приоритет, область действия или важное усиление.
• Удаляй локальный дубль глобального или подключённого через символическую ссылку навыка только после проверки, что внешний источник реально доступен и локальная копия не добавляет проектной области действия.
• Не объединяй проектные правила с переносимыми без явного основания.
• Не цитируй и не пересказывай правило как доказательство, пока не проверил, что оно дословно или по смыслу присутствует в текущем снимке указанного файла. Если строка исчезла после правок, перечитай файл и обнови вывод.
• Не считай найденный конфликт доказанным, пока не указаны обе конфликтующие формулировки или их точные места.
• Не добавляй новые правила «для полноты», если они не закрывают найденный риск или реальную ошибку агента.
• Не откладывай подтверждённое исправление без явного указания пользователя или необходимости решения владельца.
• Не считай правило «открытые задачи хранятся в бэклоге» разрешением создать новую запись. Для записи нужно отдельное явное полномочие.

Вывод

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

Проблемы, отложенные по явному указанию пользователя или ожидающие решения владельца, перечисли отдельно: та же понятная формулировка, варианты решения и рекомендация. Если пользователь явно ограничил задачу диагностикой, используй тот же формат, но вместо «что сделано» указывай одно конкретное действие. В конце сообщи, что все найденные проблемы отработаны, и назови остаточные риски.