AnswersPublished14 sources
Порядок у репозиторії: що зберігати в тестах, специфікаціях і планах
Зберігайте тести централізовано за замовчуванням, але залишайте Go тести поруч із пакетом, якщо їм потрібен доступ до неекспортованих елементів. Специфікації фіксують чинні вимоги, ADR пояснюють важливі рішення, а тести перевіряють поведінку — одне не замінює іншого.
ОпублікувавЗображення створено за допомогою GPT Image 2
Research answer
Key takeaways
- Зберігайте тести централізовано за замовчуванням, але залишайте 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)
AI Prompt
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
Упорядкована структура репозиторію має полегшувати пошук і підтримку, а не змушувати команду створювати нові файли заради самого порядку. Тому централізовані тести, окрема директорія для архітектурних рішень і простіший каталог планів — цілком робочий напрям. Але важливо розрізняти зручну домовленість і правило, яке не можна порушувати.
1. Централізуйте тести, але залиште винятки для мови й пакета
Каталог на кшталт tests/ може бути стандартним місцем для тестів, особливо в Python-проєктах. Під час перенесення перевірте імпорти, виявлення тестів, фікстури й CI. У цьому репозиторії CI вже використовує централізований шлях до тестів.
Для Go безумовне перенесення всіх тестів із каталогів пакетів може зашкодити. Тести в тому самому пакеті можуть звертатися до неекспортованих ідентифікаторів; файли з суфіксом _test натомість компілюються як окремий пакет.14
16 Тож тести, яким потрібен доступ до внутрішнього стану, доцільно залишати поруч із кодом. Чорні, міжкомпонентні та наскрізні перевірки зазвичай можна зібрати окремо.
Також не варто плутати обмеження імпорту внутрішніх пакетів Go з доступом до неекспортованих елементів: це різні правила.10
16 Не потрібно відкривати внутрішній стан або дублювати реалізацію лише заради однорідної структури каталогів.
Мета — прибрати зайві фрагменти й дублювання перевірок, а не заборонити окремі тестові файли. Регресійні тести, потрібні для майбутніх змін, варто зберігати у версійному контролі; одноразові діагностичні скрипти можуть бути тимчасовими.
2. Специфікація, ADR і правила проєкту — різні речі
Каталог specs/ не варто перетворювати на скорочений переказ усіх ADR. Ці документи відповідають на різні запитання:
| Рівень | На яке запитання відповідає | Що містить |
|---|---|---|
| Загальна методологія | Як аналізувати, перевіряти й передавати результат? | Загальні робочі підходи |
AGENTS.md |
Як працювати саме в цьому проєкті? | Підтверджені обмеження й робочі інструкції |
Специфікації в specs/ |
Яку поведінку та контракти має забезпечувати система? | Чинні вимоги й узгоджені правила |
ADR у docs/adr/ |
Чому обрали саме цей підхід? | Важливі рішення, компроміси й альтернативи |
| Тести | Чи виконується очікувана поведінка? | Виконувані перевірки |
Документація Cline описує правила, які зберігають інструкції між розмовами.4 Однак це саме по собі не означає, що Cline автоматично створює або оновлює специфікації в каталозі проєкту. Таку процедуру слід визначити як внутрішню домовленість, а не як гарантовану можливість інструмента.
На практиці помічник може запропонувати проєктну специфікацію на основі запиту й наявних у репозиторії доказів. Невідоме має залишатися невідомим, доки його не підтверджено. Для нових важливих компромісів можна підготувати ADR; якщо вже є чинне рішення, достатньо послатися на нього, а не створювати копію для кожного плану. Результати тестів допомагають перевірити реалізацію, але самі собою не дають дозволу змінити вимоги.
Коротко: специфікація описує чинний контракт, ADR — підстави для рішення, а тест — спосіб перевірити поведінку. Це пов’язані, але не взаємозамінні документи.
3. Перенесіть нові ADR до одного каталогу, не переписуючи історію
Для нових записів можна встановити docs/adr/ як стандартне місце. Це домовленість конкретного проєкту, а не вимога, яку слід видавати за універсальний стандарт.
Варто зберігати не лише прийняті рішення: пропозиції, відхилені варіанти й рішення, які згодом замінили, теж можуть бути важливими для розуміння історії. Якщо попереднє рішення втратило чинність, зафіксуйте зв’язок із новим, але не переписуйте заднім числом його початкові підстави. Під час перенесення оновіть посилання, маршрути й обмеження доступу — одного переміщення файлів недостатньо.
4. Розрізняйте завершений і заморожений план
Плоска структура plans/ може бути достатньою, якщо планів небагато. Як можливий варіант назв:
| Призначення | Приклад шляху | Значення |
|---|---|---|
| Активний план | pending_implementation_plan.md |
Основний вхід до поточної роботи |
| Завершений план | plan-20261022-example-id.md |
Роботу виконано й архівування дозволено |
| Заморожений план | plan-20261022-example-id-frozen.md |
Роботу призупинено, частина завдань лишається невиконаною |
Це приклади запропонованих шляхів, а не твердження, що такі файли вже створено.
Заморожування означає, що план більше не є типовою активною точкою входу. У ньому слід зазначити причину паузи, невиконані завдання й умови відновлення. Завершений план, навпаки, має пройти необхідні перевірки й отримати дозвіл на архівування. Якщо роботу вирішили остаточно не виконувати, це потрібно пояснити окремо, а не називати тимчасовою паузою.
Відповідно до наявних правил життєвого циклу (документ), відновлення замороженого плану потребує нового дозволу й повторної перевірки. Старий успішний результат не слід автоматично вважати чинним для нового запуску. Так само перейменування файла — лише операція збереження, а не доказ того, що всі критерії приймання виконано.
5. Пов’язуйте тести з модулями й контрактами, а не один до одного
Не потрібно вимагати, щоб для кожного файла коду існував рівно один тестовий файл. Один тест може охоплювати кілька компонентів, а один компонент — мати модульні, інтеграційні й інші перевірки.
Почніть із структурування тестів у tests/ за модулями або функціями. У відповідних специфікаціях зазначайте ключові інваріанти, потрібні тестові сценарії та обмежені за обсягом команди перевірки. Якщо зв’язки важко знайти, можна додати окрему мапу — наприклад, tests/test-map.yaml. У ній достатньо зберігати ідентифікатор модуля чи контракту, ділянку коду, ділянку тестів і команду перевірки.
Мапа допомагає знайти перевірки, але не доводить повноту покриття й не є свідченням успішного запуску. Її варто додавати лише тоді, коли вона справді розв’язує проблему навігації.
6. Прибирайте чернетки, не втрачаючи доказів
Одноразові чернетки, тимчасові скрипти й пошукові нотатки можна збирати в .scratch/. Але розташування файла саме по собі не визначає, наскільки він надійний, і не означає, що його завжди можна видалити.
Наприклад, переказ дослідження — це вторинне пояснення, яке не повинно автоматично ставати фактом. Водночас оригінальний вивід тесту чи діагностичний запис може бути первинним доказом, навіть якщо тимчасово зберігається в такому каталозі. Важливі походження матеріалу, середовище, час і повнота.
Перед очищенням перевірте, чи не є файл єдиним підтвердженням для плану, рішення або висновку про приймання. Якщо на нього спираються, збережіть потрібний оригінал або перегляньте висновок, який від нього залежить. Корисні результати дослідження варто переносити до відповідної документації разом із посиланням на докази, межами застосування й невідомими.
Старі матеріали в docs/ теж не обов’язково одразу видаляти. Чинні документи слід переглядати разом зі змінами відповідних контрактів; старі схеми й пропозиції — позначати як історичні, застарілі або замінені. Матеріали без довгострокової цінності та залежних посилань можна прибрати після перевірки й дозволу.
Зберігання історії не означає, що її потрібно завантажувати в кожне робоче обговорення. Зайвий контекст краще обмежувати цільовим читанням і позначенням чинності, а не видаленням потрібних доказів.
Підсумок
Цю структуру можна взяти за основу з чотирма застереженнями: централізуйте тести, але враховуйте особливості мов; не змішуйте специфікації з ADR; не прирівнюйте заморожений план до завершеного; не видаляйте тимчасові матеріали, якщо вони містять єдині потрібні докази.
У репозиторії вже є правила, прив’язані до поточних шляхів активних планів і дозволених каталогів (скрипт перевірки), а також до меж редагування в режимі аналізу (налаштування режимів). Тому впровадження змін має охопити правила, шаблони, посилання, перевірки й адаптацію інструментів — не лише перейменування каталогів. У вихідному контексті йдеться про аналіз пропозицій; змін, перенесень або очищення файлів не виконано.
Studio Global AI
Continue your research
This page includes a source-backed answer you can continue inside Studio Global.
People also ask
What is the short answer to "Порядок у репозиторії: що зберігати в тестах, специфікаціях і планах"?
Зберігайте тести централізовано за замовчуванням, але залишайте Go тести поруч із пакетом, якщо їм потрібен доступ до неекспортованих елементів.
What are the key points to validate first?
Зберігайте тести централізовано за замовчуванням, але залишайте Go тести поруч із пакетом, якщо їм потрібен доступ до неекспортованих елементів. Специфікації фіксують чинні вимоги, ADR пояснюють важливі рішення, а тести перевіряють поведінку — одне не замінює іншого.
What should I do next in practice?
Заморожений план не є завершеним: у ньому мають залишитися невиконані завдання та умови відновлення.