ОтветыОпубликовано14 источники
Как навести порядок в тестах, документации и планах проекта
Держать тесты в общем каталоге удобно, но для тестов белого ящика в Go может понадобиться оставить файлы рядом с кодом. Спецификация описывает действующие требования, а ADR фиксирует причины выбора решения.
ОпубликовалИзображения созданы с помощью GPT Image 2
Ответ на исследование
Ключевые выводы
- Держать тесты в общем каталоге удобно, но для тестов белого ящика в Go может понадобиться оставить файлы рядом с кодом.
- Спецификация описывает действующие требования, а ADR фиксирует причины выбора решения.
- Замороженный план остаётся незавершённым: его нельзя выдавать за выполненный или автоматически считать проверенным.
- Временные материалы можно чистить, но не за счёт единственных доказательств, на которых держатся решения или проверки.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/L2Q8zxg7UqZZOsMb8CmQKOfK9IR2/images/53D2DD20E6A8C8FDDC17/74C3321FB646B5554586.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":"这套布局可以作为收敛方向，但需要纠正三个等同关系：所有测试不能无条件迁出业务包，规范不是全部 ADR 的摘要，冻结也不是完成归档。以下是六项建议的明确边界；涉及的新路径均为候选，尚未创建或迁移。\n\n 1.. Topic tags: general web, openai, automation, workflow, code. 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 fake numbers, clickbait thumbnails, icons, a
Предлагаемую структуру можно взять за основу, но важно не приравнивать друг к другу три разные вещи: все тесты и код в одном каталоге, спецификации и ADR, заморозку и завершение работ. Ниже — шесть принципов, которые помогают навести порядок, не создавая новых проблем. Указанные пути — варианты для обсуждения: в рамках этого разбора файлы не создавались и не перемещались.
1. Тесты — по возможности в одном месте, но не любой ценой
Централизованный каталог тестов может быть правилом по умолчанию, но не обязательно строгим требованием для всех языков и типов тестирования.
- Python: обычно удобно хранить тесты в
tests/. При переносе нужно проверить импорты, обнаружение тестов, фикстуры и настройки CI. В рассматриваемом репозитории CI уже использует централизованный каталог тестов. - Go: тестам белого ящика, которым нужен доступ к неэкспортируемым членам пакета, может потребоваться остаться рядом с проверяемым кодом. Тесты чёрного ящика, межкомпонентные и сквозные тесты можно размещать централизованно. Go собирает тесты отдельно для каждого пакета и поддерживает как тесты в том же пакете, так и тесты во внешнем пакете с суффиксом
_test.14
Не стоит путать ограничения на импорт из каталога internal с доступом к неэкспортируемым членам пакета: это разные правила.10
16 Поэтому требование «перенести все тесты Go из каталогов исходного кода, сохранив при этом тестирование белого ящика» нельзя вводить без оговорок. Не нужно экспортировать внутреннее состояние или дублировать логику только ради аккуратного дерева каталогов.
При этом важно отделять полезные тесты от мелких разовых проверок. Регрессионные тесты, к которым нужно возвращаться, следует хранить в репозитории. Одноразовые диагностические скрипты можно помещать во временный каталог.
2. Спецификации, ADR и общие правила решают разные задачи
Каталог specs/ не стоит превращать в сборник пересказов всех ADR. Разумнее распределить документы по их назначению:
| Уровень | На какой вопрос отвечает | Что содержит |
|---|---|---|
| Общая методология | Как анализировать, проверять и сдавать работу? | Принципы, общие для разных проектов |
Проектный файл AGENTS.md |
Как работать именно в этом проекте? | Подтверждённые ограничения и основные инструкции |
Спецификации проекта в specs/ |
Какое поведение и какие контракты должны соблюдаться сейчас? | Требования, принятые решения и согласованные изменения |
ADR в docs/adr/ |
Почему выбрали именно этот вариант? | Важные архитектурные решения, компромиссы и альтернативы |
Cline поддерживает постоянные правила, которые помогают сохранять инструкции между сессиями.4 Однако имеющиеся материалы не подтверждают, что Cline сам по себе автоматически записывает в каталог спецификаций документы определённого типа. Такое поведение следует считать договорённостью проекта, а не гарантией инструмента.
Работа со спецификациями не обязана целиком выполняться вручную и не должна начинаться только после возникновения проблем. Возможен такой порядок:
- При настройке проекта помощник предлагает черновик спецификации на основе требований и данных репозитория, а неизвестное помечает как неизвестное.
- Перед работой команда изучает относящиеся к задаче спецификации и решения, а затем уточняет критерии приёмки и проверки.
- Новый ADR нужен для существенного выбора между вариантами. Если подходящее решение уже принято, достаточно сослаться на него.
- Проверка может показать, что реализация соответствует требованиям, или выявить проблему в самой спецификации. Но результат теста не должен автоматически подменять требования.
- После согласованного принятия решения обновляют действующую спецификацию и при необходимости связывают её с ADR. Переписывать всю историю решений в спецификации не нужно.
Коротко: спецификация фиксирует текущий контракт, ADR объясняет принятое решение, а тесты проверяют поведение. Эти документы дополняют друг друга, но не заменяют. Частные выводы одного проекта также не следует автоматически превращать в глобальные правила.
3. ADR можно хранить в одном каталоге, не меняя правила принятия решений
Для новых документов можно установить единый путь по умолчанию — docs/adr/. Это удобное соглашение внутри проекта, а не утверждение о едином отраслевом стандарте.
При этом стоит сохранить существующую практику:
- записывать не только принятые, но и предложенные, отклонённые или заменённые решения;
- использовать уже действующие ADR, а не создавать дубликат для каждой задачи;
- связывать новое решение с тем, которое оно заменяет, не переписывая задним числом его первоначальное обоснование;
- не считать успешные тесты автоматическим разрешением на принятие ADR.
При переносе нужно обновить реальные ссылки, маршруты и ограничения доступа. Одного перемещения файлов недостаточно.
4. Планы можно хранить плоско — но заморозка не означает завершение
Каталог plans/ можно оставить без дополнительных уровней вложенности. Для небольшого числа исторических планов отдельные подкаталоги могут быть излишними. Например, можно рассмотреть такие имена:
| Назначение | Возможный файл | Значение |
|---|---|---|
| Текущий план | plans/pending_implementation_plan.md |
Основная точка входа для активной работы |
| Выполненный план | plans/plan-20261022-example-id.md |
Работа завершена и архивирование разрешено |
| Замороженный план | plans/plan-20261022-example-id-frozen.md |
Работа не завершена, но больше не считается активной по умолчанию |
Заморозка не требует нового каталога и не обязательно означает, что нужно немедленно вводить отдельный статус. В рассматриваемом валидаторе уже есть поддержка приостановленного состояния; сначала можно использовать её и указать причину паузы, оставшиеся пункты и условия возобновления.
Важно различать три ситуации:
- Завершение и архивирование: все обязательные критерии приёмки выполнены, архивирование разрешено.
- Заморозка: план исключён из активной работы, но задачи в нём остаются незавершёнными. Непроверенные предположения нельзя объявлять фактами.
- Отказ от выполнения: зафиксировано, что работу выполнять не будут, и описаны последствия. Это не то же самое, что временная пауза. Отдельный статус «отменён» потребует согласованного изменения правил.
По умолчанию следует открывать активный план, а не искать все файлы в каталоге. Историю стоит поднимать адресно — например, по запросу о восстановлении. Возобновление замороженного плана требует нового разрешения, отдельного экземпляра с сохранением ссылки на исходный план и повторной проверки. Старый статус успешной проверки нельзя переносить автоматически; это соответствует действующим правилам жизненного цикла.
Переименование файла — это операция с документом, а не доказательство выполнения работ. Нужно предотвращать перезапись, сохранять незавершённые задачи и обновлять ссылки. Создавать пустой план только ради постоянного файла в активной точке входа не требуется.
5. Связь тестов с кодом — многие ко многим
Правило «один файл с кодом — один файл с тестами» слишком жёсткое. Один тест может проверять несколько компонентов, а одному компоненту могут требоваться модульные, интеграционные и другие проверки.
Для начала достаточно:
- группировать тесты в
tests/по модулям или назначению; - в соответствующей спецификации перечислять ключевые инварианты, относящиеся к ним тесты и ограниченные по объёму команды проверки;
- добавлять отдельную карту, например
tests/test-map.yaml, только если связи и без неё трудно находить.
В такой карте нужны лишь полезные сведения: идентификатор модуля или контракта, диапазон исходного кода, расположение тестов и команда проверки. Не нужно копировать в неё всё дерево каталогов или дублировать результаты прогона тестов.
Поддерживать актуальность следует прежде всего у путей и команд. Наличие карты само по себе не доказывает ни полноту покрытия, ни успешный запуск тестов. Иначе попытка уменьшить беспорядок обернётся ещё одним ручным реестром, который легко устаревает.
6. Черновики можно чистить, но доверие к материалу не определяется каталогом
Разовые черновики, временные скрипты и отчёты для исследования удобно собирать в .scratch/. Но из этого не следует, что всё внутри каталога — источник вторичной информации или что его содержимое можно без проверки удалить.
- Краткое изложение исследования, созданное моделью, — интерпретация, а не доказательство факта.
- Исходный вывод теста или диагностическая запись могут быть первичным свидетельством и во временном каталоге. Их надёжность зависит от источника, окружения, времени и полноты записи.
- Если на материал ссылаются план, решение или критерий приёмки и это единственное доступное свидетельство, его нельзя просто удалить. Сначала нужно сохранить необходимый оригинал или отказаться от выводов, которые от него зависят.
- При переносе ключевых наблюдений нужно сохранять ссылку на доказательство, границы применимости и неизвестные. Сжатое изложение не должно превращать гипотезу в установленный факт.
Старые отчёты и архитектурные диаграммы в docs/ тоже не обязательно удалять только потому, что они устарели. Их можно разделить на текущую документацию, исторические материалы и сведения, требующие проверки. Для действующих документов стоит обозначать область применимости и пересматривать их при изменении связанных контрактов. Старые схемы и решения следует помечать как исторические, устаревшие или заменённые, чтобы они не воспринимались как текущая основа. Материалы без долгосрочной ценности и ссылок можно перенести во временный каталог или удалить после согласования.
Хранение и автоматическая загрузка контекста — не одно и то же. Не нужно читать всю историю на каждой итерации: достаточно обращаться к нужным документам и явно указывать, какие из них актуальны. Удалять доказательства ради уменьшения объёма контекста не следует.
Итог
Такую структуру можно принять как направление работы с четырьмя оговорками: тесты централизуются с учётом особенностей языка; спецификации описывают действующий контракт, а не пересказывают все ADR; замороженные планы остаются незавершёнными; временные материалы не очищают, пока на них держатся необходимые доказательства.
В текущем репозитории настройки путей плана и списка разрешённых путей в scripts/validate-roo-contracts.py, а также область редактирования в режиме анализа в bmad-suite-v4/roo/settings/custom_modes.yaml пока привязаны к прежней структуре. Перед миграцией нужно согласованно обновить правила, шаблоны, ссылки, валидаторы и адаптацию под среду выполнения. Переименование каталогов само по себе не вводит новую структуру в действие. Этот разбор ограничен анализом: в его рамках файлы не изменялись, не переносились, не замораживались и не удалялись.
Studio Global AI
Продолжайте свое исследование
На этой странице есть ответ, подтвержденный источником, который вы можете продолжить внутри Studio Global.
Люди также спрашивают
Каков краткий ответ на вопрос «Как навести порядок в тестах, документации и планах проекта»?
Держать тесты в общем каталоге удобно, но для тестов белого ящика в Go может понадобиться оставить файлы рядом с кодом.
Какие ключевые моменты необходимо проверить в первую очередь?
Держать тесты в общем каталоге удобно, но для тестов белого ящика в Go может понадобиться оставить файлы рядом с кодом. Спецификация описывает действующие требования, а ADR фиксирует причины выбора решения.
Что мне делать дальше на практике?
Замороженный план остаётся незавершённым: его нельзя выдавать за выполненный или автоматически считать проверенным.