メインコンテンツまでスキップ

既知の驚き

This file tracks repository-specific confusion points that caused agent mistakes.

参加基準​

すべてが true の場合にのみエントリを追加します。

  • It is specific to this repository (not generic advice).
  • 今後のエージェントでも再発する可能性があります。
  • It has a concrete mitigation that can be followed.

If uncertain, ask the developer before adding an entry.

エントリーテンプレート​

### [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

エントリー​

ポートレスは正規のローカル アプリ URL を変更します​

  • 日付: 2026-03-18
  • 観察者: コーデックス
  • コンテキスト: ブラウザの検証とスモーク フロー
  • 驚いたこと: デフォルトのローカル URL は通常の Vite ポートではありません。リポジトリはポートレス経由で https://bitsocial.localhost を期待しているため、localhost:3000 または localhost:5173 をチェックすると、間違ったアプリがヒットするか、まったくヒットしない可能性があります。
  • 影響: 開発サーバーが正常な場合でも、ブラウザー チェックが失敗したり、間違ったターゲットを検証したりする場合があります。
  • 軽減策: 最初に https://bitsocial.localhost を使用してください。直接 Vite ポートが明示的に必要な場合にのみ、PORTLESS=0 corepack yarn start を使用してバイパスしてください。
  • ステータス: 確認済み

コミットフックは非対話型コミットをブロックします​

  • 日付: 2026-03-18
  • 観察者: コーデックス
  • コンテキスト: エージェント主導のコミット ワークフロー
  • 驚いたこと: git commit は、Husky を通じて Commitizen をトリガーし、対話型 TTY 入力を待機します。これにより、非対話型エージェント シェルがハングします。
  • 影響: 通常のコミット中にエージェントが無期限に停止する可能性があります。
  • 軽減策: エージェントが作成したコミットには git commit --no-verify -m "message" を使用します。人間は引き続き corepack yarn commit または corepack yarn exec cz を使用できます。
  • ステータス: 確認済み

Yarn classic を回避するには Corepack が必要です​

  • 日付: 2026-03-19
  • 観察者: コーデックス
  • コンテキスト: パッケージマネージャーの Yarn 4 への移行
  • 驚いたこと: マシンには PATH にグローバル Yarn クラシック インストールがまだあるため、プレーン yarn を実行すると、固定された Yarn 4 バージョンではなく v1 に解決される可能性があります。
  • 影響: 開発者が誤ってリポジトリのパッケージ マネージャーの固定をバイパスし、異なるインストール動作やロックファイル出力が得られる可能性があります。
  • 軽減策: シェル コマンドには corepack yarn ... を使用するか、最初に corepack enable を実行して、プレーンな yarn が固定された Yarn 4 バージョンに解決されるようにします。
  • ステータス: 確認済み

Bitsocial Web ワークツリー間でポートレス アプリ名が衝突する問題を修正​

  • 日付: 2026-03-30
  • 観察者: コーデックス
  • コンテキスト: 別のワークツリーがすでにポートレス経由で提供されているときに、ある Bitsocial Web ワークツリーで yarn start を開始しています
  • 驚いたこと: すべてのワークツリーでリテラルのポートレス アプリ名 bitsocial を使用すると、バッキング ポートが異なる場合でもルート自体が衝突するため、bitsocial.localhost がすでに登録されているために 2 番目のプロセスが失敗します。
  • 影響: 並列 Bitsocial Web ブランチは、ポートレスが安全に共存できるようにすることを目的としているにもかかわらず、互いにブロックする可能性があります。
  • 緩和策: ポートレスの起動を scripts/start-dev.mjs の背後に維持します。これにより、標準ケース外のブランチ スコープの *.bitsocial.localhost ルートが使用され、ベア bitsocial.localhost 名がすでに占有されている場合はブランチ スコープのルートにフォールバックします。
  • ステータス: 確認済み

ポート 3001 をハードコーディングするために使用されるドキュメント プレビュー​

  • 日付: 2026-03-30
  • 観察者: コーデックス
  • コンテキスト: 他のローカル リポジトリおよびエージェントと一緒に yarn start を実行する
  • 驚いたこと: root dev コマンドは docusaurus start --port 3001 を使用して docs ワークスペースを実行したため、メイン アプリがすでにポートレスを使用していても、別のプロセスがすでに 3001 を所有している場合は常に開発セッション全体が失敗しました。
  • 影響: yarn start は、起動直後に Web プロセスを強制終了し、ドキュメント ポートの衝突により無関係なローカル作業を中断する可能性があります。
  • 緩和策: ドキュメントの起動を yarn start:docs の背後で行います。これにより、ポートレスと scripts/start-docs.mjs が使用され、挿入された空きポートが優先されるか、直接実行時に次の利用可能なポートにフォールバックされます。
  • ステータス: 確認済み

ポートレスホスト名がハードコーディングされていたドキュメントを修正しました​

  • 日付: 2026-04-03
  • 観察者: コーデックス
  • コンテキスト: 別のワークツリーがすでにポートレス経由でドキュメントを提供している間に、セカンダリ Bitsocial Web ワークツリーで yarn start を実行しています。
  • 驚いたこと: start:docs は依然としてリテラルの docs.bitsocial.localhost ホスト名を登録しているため、About アプリが独自のホスト名のポートレス ルート衝突を回避する方法をすでに知っていたにもかかわらず、yarn start が失敗する可能性がありました。
  • 影響: ドキュメント プロセスが最初に終了し、その後 concurrently が残りのセッションを強制終了したため、並列ワークツリーでは root dev コマンドを確実に使用できませんでした。
  • 緩和策: ドキュメントの起動を scripts/start-docs.mjs の背後で維持します。これにより、about アプリと同じブランチ スコープのポートレス ホスト名が派生し、その共有パブリック URL が /docs 開発プロキシ ターゲットに挿入されます。
  • ステータス: 確認済み

Worktree シェルはリポジトリの固定されたノードのバージョンを見逃す可能性があります​

  • 日付: 2026-04-03
  • 観察者: コーデックス
  • コンテキスト: .claude/worktrees/* または兄弟ワークツリー チェックアウトなどの Git ワークツリーで yarn start を実行する
  • 驚いたこと: リポジトリが 22.12.0 を .nvmrc に固定しているにもかかわらず、一部のワークツリー シェルは node と yarn node を Homebrew ノード 25.2.1 に解決するため、yarn start が間違ったランタイムで開発ランチャーをサイレント実行する可能性があります。
  • 影響: 開発サーバーの動作がメイン チェックアウトとワークツリーの間で変動する可能性があり、バグの再現が困難になり、リポジトリの予期される Node 22 ツールチェーンに違反します。
  • 緩和策: 開発ランチャーを scripts/start-dev.mjs および scripts/start-docs.mjs の背後に保持します。現在のシェルが間違ったバージョンである場合、これらは .nvmrc ノード バイナリで再実行されるようになりました。シェルセットアップでは依然として nvm use を優先する必要があります。
  • ステータス: 確認済み

docs-site/ の残り物は、リファクタリング後に欠落しているドキュメント ソースを隠すことができます​

  • 日付: 2026-04-01
  • 観察者: コーデックス
  • コンテキスト: Docusaurus プロジェクトを docs-site/ から docs/ に移動した後のマージ後のモノリポジトリのクリーンアップ
  • 驚いたこと: 追跡されたリポジトリが docs/ に移動した後でも、古い docs-site/ フォルダーは、i18n/ などの古くても重要なファイルとともにディスク上に残ることがあります。これにより、リファクタリングがローカルで重複しているように見え、追跡されたドキュメントの翻訳が実際には docs/ に移動されなかったという事実が隠蔽される可能性があります。
  • 影響: エージェントは古いフォルダーを「ジャンク」として削除し、ドキュメント翻訳の唯一のローカル コピーを誤って失ったり、無効な docs-site/ パスを指したままスクリプトを編集し続けたりする可能性があります。
  • 緩和策: docs/ を唯一の正規ドキュメント プロジェクトとして扱います。ローカルの docs-site/ の残り物を削除する前に、docs/i18n/ などの追跡されたソースを復元し、スクリプトとフックを更新して docs-site の参照を停止します。
  • ステータス: 確認済み

マルチロケールのドキュメント プレビューでは、検証中に RAM が急増する可能性があります​

  • 日付: 2026-04-01
  • 観察者: コーデックス
  • コンテキスト: yarn start:docs と Playwright を使用したドキュメント i18n、ロケール ルーティング、および Pagefind の動作の修正
  • 驚いたこと: デフォルトのドキュメント プレビュー モードでは、配信前に完全なマルチロケール ドキュメントのビルドと Pagefind インデックス作成が実行されるようになりました。そのプロセスを複数の Playwright または Chrome セッションと並行して維持すると、通常の Vite または単一ロケールの Docusaurus 開発ループよりもはるかに多くの RAM を消費する可能性があります。
  • 影響: マシンがメモリの制約を受け、ブラウザ セッションがクラッシュし、実行が中断されると、メモリを消費し続ける古いドキュメント サーバーやヘッドレス ブラウザが残される可能性があります。
  • 緩和策: locale-route または Pagefind 検証を必要としないドキュメント作業の場合は、DOCS_START_MODE=live yarn start:docs を推奨します。デフォルトのマルチロケール プレビューは、翻訳されたルートまたは Pagefind を検証する必要がある場合にのみ使用してください。単一の Playwright セッションを保持し、新しいブラウザ セッションを開く前に古いブラウザ セッションを閉じ、検証後に不要になった場合はドキュメント サーバーを停止します。
  • ステータス: 確認済み