Перейти до основного вмісту

Відомі сюрпризи

У цьому файлі відстежуються проблеми, пов’язані зі сховищем, які викликали помилки агента.

Критерії вступу​

Додайте запис, лише якщо всі вірні:

  • Це специфічно для цього сховища (не загальна порада).
  • Ймовірно, це повториться для майбутніх агентів.
  • Він має конкретне пом’якшення, яке можна дотримуватися.

Якщо ви не впевнені, запитайте розробника, перш ніж додавати запис.

Шаблон запису​

### [Short title]

- **Date:** YYYY-MM-DD
- **Observed by:** agent name or contributor
- **Context:** where/when it happened
- **What was surprising:** concrete unexpected behavior
- **Impact:** what went wrong or could go wrong
- **Mitigation:** exact step future agents should take
- **Status:** confirmed | superseded

Записи​

Portless змінює канонічну URL-адресу локальної програми​

  • Дата: 2026-03-18
  • Дотримується: Кодекс
  • Контекст: Перевірка веб-переглядача та потоки диму
  • Що здивувало: Локальна URL-адреса за умовчанням не є звичайним портом Vite. Репо очікує https://bitsocial.localhost через Portless, тому перевірка localhost:3000 або localhost:5173 може потрапити на неправильну програму або взагалі нічого.
  • Вплив: перевірки веб-переглядача можуть бути невдалими або підтверджувати неправильну ціль, навіть якщо сервер розробника справний.
  • Пом’якшення: Спочатку використовуйте https://bitsocial.localhost. Лише обходьте його за допомогою PORTLESS=0 corepack yarn start, коли вам явно потрібен прямий порт Vite.
  • Статус: підтверджено

Хуки Commitizen блокують неінтерактивні коміти​

  • Дата: 2026-03-18
  • Дотримується: Кодекс
  • Контекст: Робочі процеси фіксації, керовані агентом
  • Що здивувало: git commit запускає Commitizen через Husky та очікує інтерактивного введення TTY, який зависає неінтерактивні оболонки агента.
  • Вплив: Агенти можуть зупинятися на невизначений час під час того, що має бути звичайним комітом.
  • Пом’якшення: Використовуйте git commit --no-verify -m "message" для комітів, створених агентом. Люди все ще можуть використовувати corepack yarn commit або corepack yarn exec cz.
  • Статус: підтверджено

Corepack необхідний, щоб уникнути класичної пряжі​

  • Дата: 2026-03-19
  • Дотримується: Кодекс
  • Контекст: Перехід менеджера пакетів на Yarn 4
  • Що здивувало: машина все ще має глобальну класичну установку Yarn на PATH, тому запущений звичайний yarn може перейти до v1 замість закріпленої версії Yarn 4.
  • Вплив: розробники можуть випадково обійти закріплення диспетчера пакунків сховища та отримати іншу поведінку встановлення або вихід файлу блокування.
  • Пом’якшення: Використовуйте corepack yarn ... для команд оболонки або спочатку запустіть corepack enable, щоб звичайний yarn перейшов у закріплену версію Yarn 4.
  • Статус: підтверджено

Виправлені назви програм без портів збігаються в робочих деревах Bitsocial Web​

  • Дата: 2026-03-30
  • Дотримується: Кодекс
  • Контекст: Запуск yarn start в одному робочому дереві Bitsocial Web, коли інше робоче дерево вже обслуговується через Portless
  • Що було несподіваним: використання буквального імені додатка без портів bitsocial у кожному робочому дереві призводить до конфлікту самого маршруту, навіть якщо резервні порти різні, тому другий процес не вдається, оскільки bitsocial.localhost уже зареєстровано.
  • Вплив: Паралельні гілки Bitsocial Web можуть блокувати одна одну, навіть якщо Portless призначений для безпечного співіснування.
  • Пом’якшення: Тримайте безпортовий запуск позаду scripts/start-dev.mjs, який тепер використовує маршрут *.bitsocial.localhost із областю гілки за межами канонічного випадку та повертається до маршруту з областю гілки, коли голе ім’я bitsocial.localhost уже зайнято.
  • Статус: підтверджено

Попередній перегляд документів використовується для жорсткого кодування порту 3001​

  • Дата: 2026-03-30
  • Дотримується: Кодекс
  • Контекст: Запуск yarn start разом з іншими локальними репозиторіями та агентами
  • Що було несподіваним: Команда root dev запускала робочий простір документів із docusaurus start --port 3001, тому весь сеанс розробника не вдавався щоразу, коли інший процес уже володів 3001, навіть якщо основна програма вже використовувала Portless.
  • Вплив: yarn start міг зупинити веб-процес одразу після його завантаження, перервавши непов’язану локальну роботу через конфлікт документів-порту.
  • Пом’якшення: Зберігайте запуск документів позаду yarn start:docs, який тепер використовує Portless плюс scripts/start-docs.mjs для врахування введеного вільного порту або повернення до наступного доступного порту під час безпосереднього запуску.
  • Статус: підтверджено