Перейти к основному содержанию

Известные сюрпризы

Этот файл отслеживает моменты путаницы, связанные с конкретным репозиторием, которые вызвали ошибки агента.

Критерии входа​

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

  • Это специфично для этого репозитория (а не общий совет).
  • Вероятно, это повторится для будущих агентов.
  • У него есть конкретные меры по смягчению последствий, которым можно следовать.

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

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

### [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-адрес локального приложения​

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

Перехватчики Commitizen блокируют неинтерактивные коммиты​

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

Corepack необходим, чтобы избежать Yarn classic.​

  • Дата: 19 марта 2026 г.
  • Наблюдается: Кодексом
  • Контекст: Миграция менеджера пакетов на Yarn 4
  • Что было удивительно: На машине все еще установлена ​​глобальная классическая установка Yarn на PATH, поэтому запуск простого yarn может разрешить версию v1 вместо закрепленной версии Yarn 4.
  • Воздействие. Разработчики могут случайно обойти закрепление диспетчера пакетов репозитория и получить другое поведение при установке или вывод файла блокировки.
  • Средство устранения: Используйте corepack yarn ... для команд оболочки или сначала запустите corepack enable, чтобы простой yarn разрешался в закрепленную версию Yarn 4.
  • Статус: подтверждено

Исправлены конфликты имен приложений без портов в рабочих деревьях Bitsocial Web.​

  • Дата: 30 марта 2026 г.
  • Наблюдается: Кодексом
  • Контекст: Запуск yarn start в одном рабочем дереве Bitsocial Web, в то время как другое рабочее дерево уже обслуживалось через Portless.
  • Что было удивительно: Использование буквального имени Portless-приложения bitsocial в каждом рабочем дереве приводит к коллизии самого маршрута, даже если резервные порты различаются, поэтому второй процесс завершается сбоем, поскольку bitsocial.localhost уже зарегистрирован.
  • Воздействие. Параллельные ветки Bitsocial Web могут блокировать друг друга, хотя Portless предназначен для обеспечения их безопасного сосуществования.
  • Минимизация: Оставьте запуск Portless за scripts/start-dev.mjs, который теперь использует маршрут *.bitsocial.localhost с областью действия ветки вне канонического случая и возвращается к маршруту с областью действия ветки, когда пустое имя bitsocial.localhost уже занято.
  • Статус: подтверждено

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

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