ОтветыОпубликовано15 источники
Как навести порядок в тестах и документации V4, не потеряв качество
Не стоит убирать из репозитория все тесты: долгосрочные регрессионные и контрактные проверки — часть контроля качества. Разовые диагностики и их результаты лучше отделить от исходников и каталогов, содержимое которых попадает в установку.
ОпубликовалИзображения созданы с помощью GPT Image 2
Ответ на исследование
Ключевые выводы
- Не стоит убирать из репозитория все тесты: долгосрочные регрессионные и контрактные проверки — часть контроля качества.
- Разовые диагностики и их результаты лучше отделить от исходников и каталогов, содержимое которых попадает в установку.
- Документам полезнее чёткое разделение ролей и чтение по необходимости, чем погоня за минимальным числом файлов.
- Это предварительные рекомендации по статическим данным: часть внешнего исследования не завершена, тесты не запускались и изменения не вносились.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/oBMfTzLzQzYo7VcXQdEGj2yQgAw1/images/73E9D63489E02AC46209/BEDABC175BE8FCADFC63.png)
Промпт ИИ
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"两个痛点都适合纳入 V4 的“产物生命周期背压”，但不应简化成“测试全部不提交”或“文档全部合并”。建议保留长期质量资产，隔离一次性验证材料，并分别控制仓库维护、安装分发和模型上下文。\n\n本次交付为阶段性调研：仓库静态证据、Geoffrey Huntley 的作者资料及部分学术资料已取得；Python 官方布. Topic tags: general web, openai, llm, agents, ai. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts with fa
Упорядочить тесты и документацию в V4 — не значит удалить всё лишнее на глаз или сложить все файлы в одну папку. Важнее управлять их жизненным циклом: зачем материал создан, нужно ли его хранить, должен ли он попадать в установку и обязан ли его читать ИИ-агент.
Тесты: отделить временные проверки, но сохранить долгосрочные
В текущем V4 CI настроен на централизованный каталог tests/: там находятся проверки конфигурации, установки и защиты ресурсов (.github/workflows/ci.yml:55). Поэтому считать все тесты временным шумом только из-за их расположения было бы неправильно. При этом в ходе этой оценки тесты не запускались и ценность каждого из них отдельно не проверялась.
Файл .gitignore исключает некоторые песочницы, кеши и временные данные, но не перечисляет каталоги черновиков и результатов проверки, в частности _bmad-output/scratch/ и _bmad-output/verification/ (.gitignore:1). Само наличие этих каталогов не доказывает, что их содержимое уже отслеживается Git; индекс в рамках этой проверки не изучался.
Важно также различать обновление репозитория и установку. Скрипт обновления работает с репозиторием (bs.sh:298), а сборщик источников развёртывания читает выбранный набор файлов (scripts/deployment_source.py:64). Сборщик рекурсивно обходит файлы внутри набора и формирует входные данные для развёртывания (scripts/deployment_source.py:47, scripts/deployment_source.py:81). Это значит, что временный файл, случайно помещённый внутрь такого набора, может попасть в дистрибутив. Данных о том, что это уже произошло, нет.
Практичное разделение может выглядеть так:
| Материалы | Рекомендация |
|---|---|
| Долгосрочные регрессионные, контрактные и необходимые интеграционные тесты | Хранить и поддерживать вместе с проектом; по умолчанию не включать в пакет для запуска |
| Разовые диагностики, экспериментальные входные данные и проверочные скрипты | Оставлять в разрешённой временной области; не помещать в каталоги ресурсов для установки |
| Логи, отчёты о покрытии и результаты запусков | Не добавлять в исходники по умолчанию; сохранять отдельно, если это нужно для доказательств или разбора ошибок |
Это предложения, а не уже внедрённые правила. Размещение тестов зависит и от языка: руководство Go показывает тестовый файл рядом с тестируемым пакетом. Поэтому переносить все Go-тесты в единый внешний каталог как универсальное правило оснований нет (15). В V4 уже используется отдельный каталог тестов, но достаточных официальных данных, чтобы объявить такой подход лучшим для Python во всех проектах, здесь нет.
Если главная цель — чтобы установленная версия была компактной, стоит прежде всего определить границы пакета и список устанавливаемых файлов. Если нужно сделать удобнее дерево исходников для разработчиков, тогда имеет смысл выбирать расположение с учётом языка. Перемещение тестов само по себе не решает обе задачи.
Документация: меньше дублирования, яснее назначение
Правила V4 уже разделяют анализ, ADR (записи об архитектурных решениях), планы и контракты и предписывают уточнять назначение, если оно неясно (bmad-suite-v4/rules/bmad-core.md:129). При этом для черновиков существует отдельное соглашение о расположении (bmad-suite-v4/rules/bmad-core.md:117). Эти статические данные указывают на неполное описание жизненного цикла материалов, но не объясняют, почему в отдельных случаях появляются новые каталоги.
Вместо добавления новых уровней папок полезнее чётче разделить обязанности существующих документов:
- Анализ — доказательства, сравнение вариантов, возражения и неизвестные. Обычный ответ можно оставить в диалоге, если сохранять его не требуется.
- ADR — существенное решение, его причины и ограничения. Не нужно дублировать в нём весь анализ или журнал выполнения.
- План работ — утверждённый объём, зависимости и критерии приёмки; он может ссылаться на решение, не переписывая исследование.
- Временные материалы — черновики, диагностические входные данные и необработанные результаты в разрешённой временной области, а не в официальном разделе анализа только потому, что в названии есть слово «черновик».
- Постоянная эксплуатационная документация — только если материал действительно служит повторно используемой инструкцией. Один раз выполненное развёртывание не должно автоматически порождать новый каталог документации.
Количество файлов, включение в Git, попадание в установочный пакет и чтение моделью — четыре отдельных решения. Сведение всего в одну папку не заменяет этих правил.
Что из подхода Geoffrey Huntley применимо к V4
В статье о «обратном давлении» Geoffrey Huntley говорит о создании вокруг агента автоматизированной обратной связи, которая помогает ему проверять качество и корректность работы (12). Это аргумент в пользу полезной проверки, а не призыв удалять тесты.
В описании переноса программного обеспечения Huntley предлагает сначала свести поведение тестов в спецификации, а затем использовать её при переносе кода (14). Это конкретный приём для миграции между языками, а не доказательство того, что документация должна заменять тесты во всех проектах.
Для V4 разумный вывод такой: сохранить исполняемую проверку корректности, но уменьшить количество дублирующих и разовых материалов. Спецификация описывает ожидаемое поведение, а тест может проверить его на практике. Без отдельной оценки одно не следует считать заменой другого.
Достаточно ли у Huntley единой публичной политики по коммитам тестов, черновикам и исключению файлов из сборок? Недостаточно данных. Также недостаточно данных, чтобы утверждать, будто форумы и обсуждения пришли к единому мнению: не изученные в рамках этой оценки сообщения нельзя использовать как подтверждение.
Длинные документы: важнее управлять чтением, а не числом папок
Исследования длинного контекста описывают, как модели могут хуже использовать сведения, расположенные в середине входного текста (3). Работа HELMET подчёркивает, что способности к работе с длинным контекстом нужно оценивать на разных типах задач, а не только на простых тестах поиска нужного фрагмента (
4). Эти результаты не означают, что файл определённой длины автоматически вызывает галлюцинации, и не измеряют риск конкретно для V4.
Для рабочих материалов можно придерживаться нескольких простых принципов:
- Делить документы по теме и границам решений, а не бесконечно наращивать один общий файл.
- По умолчанию читать разделы, нужные для текущей задачи; старые материалы находить по мере необходимости.
- В кратком резюме сохранять ссылки на доказательства, неизвестные и незакрытые обязательства, а исходные данные оставлять для проверки.
- Использовать индекс для навигации, а не как вторую копию основного текста.
- Не передавать модели целиком журналы и архивные отчёты без необходимости.
Минимальные изменения для V4
Вместо громоздкого процесса можно добавить одно правило для всего жизненного цикла материалов:
- Перед созданием определить назначение и проверить, можно ли дополнить существующий тест или документ, а не заводить новый автоматически.
- Перед сохранением выбрать разрешённый путь, определить, временный ли это материал, нужно ли его версионировать и должен ли он попадать в установку. Если назначение неясно — не создавать каталог самовольно.
- Перед коммитом проверить временные результаты, чувствительные данные, дублирующие тесты и повторяющиеся документы. Не включать все тесты в исключения ради чистоты репозитория.
- Перед сборкой определить состав устанавливаемых ресурсов и не допускать туда временные материалы. Упрощение не должно отменять имеющиеся проверки идентичности и защиты ресурсов.
- Перед удалением проверить, нужны ли ещё доказательства ошибки, активной задаче или историческим ссылкам. Завершение задачи само по себе не означает разрешения на удаление.
Итог: сначала стоит прояснить правила для временных материалов и границу установки, затем — роли документов и загрузку по необходимости. Оснований переносить все Go-тесты, прекращать коммиты долгосрочных проверок или объединять всю документацию в один файл нет. Если изменения будут отдельно одобрены, их стоит принимать только после проверки, что тесты по-прежнему обнаруживаются, CI работает, временные файлы не попадают в установку, а ссылки на историю и незакрытые обязательства сохраняются.
Это предварительная оценка по статическим материалам. Исследование официальных рекомендаций по Python и публикаций на X, Reddit, Hacker News и Lobsters не завершено. Тесты и команды не запускались, файлы не изменялись, очистка не проводилась.
Studio Global AI
Продолжайте свое исследование
На этой странице есть ответ, подтвержденный источником, который вы можете продолжить внутри Studio Global.
Люди также спрашивают
Каков краткий ответ на вопрос «Как навести порядок в тестах и документации V4, не потеряв качество»?
Не стоит убирать из репозитория все тесты: долгосрочные регрессионные и контрактные проверки — часть контроля качества.
Какие ключевые моменты необходимо проверить в первую очередь?
Не стоит убирать из репозитория все тесты: долгосрочные регрессионные и контрактные проверки — часть контроля качества. Разовые диагностики и их результаты лучше отделить от исходников и каталогов, содержимое которых попадает в установку.
Что мне делать дальше на практике?
Документам полезнее чёткое разделение ролей и чтение по необходимости, чем погоня за минимальным числом файлов.
Источники
go.devAdd a test
ghuntley.comdon't waste your back pressure
doi.orgFound in the Middle: How Language Models Use Long Contexts Better via Plug-and-Play Positional Encoding