본문으로 건너뛰기

알려진 놀라움

이 파일은 에이전트 실수를 일으킨 저장소별 혼동 지점을 추적합니다.

입학기준​

모두 참인 경우에만 항목을 추가하십시오.

  • 이는 이 저장소에만 해당됩니다(일반적인 조언이 아님).
  • 향후 상담원에게도 이러한 현상이 반복될 가능성이 높습니다.
  • 따라야 할 구체적인 완화 방법이 있습니다.

확실하지 않은 경우 항목을 추가하기 전에 개발자에게 문의하세요.

출품 템플릿​

### [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
  • 관찰자: Codex
  • 컨텍스트: 브라우저 확인 및 연기 흐름
  • 놀랐던 점: 기본 로컬 URL은 일반적인 Vite 포트가 아닙니다. 저장소는 Portless를 통해 https://bitsocial.localhost를 예상하므로 localhost:3000 또는 localhost:5173를 확인하면 잘못된 앱이 실행되거나 전혀 실행되지 않을 수 있습니다.
  • 영향: 개발 서버가 정상인 경우에도 브라우저 검사가 실패하거나 잘못된 대상의 유효성을 검사할 수 있습니다.
  • 완화: 먼저 https://bitsocial.localhost를 사용하세요. 직접 Vite 포트가 명시적으로 필요한 경우에만 PORTLESS=0 corepack yarn start를 사용하여 이를 우회하세요.
  • 상태: 확인됨

Commitizen 후크는 비대화형 커밋을 차단합니다.​

  • 날짜: 2026-03-18
  • 관찰자: Codex
  • 컨텍스트: 에이전트 기반 커밋 워크플로
  • 놀라운 점: git commit는 Husky를 통해 Commitizen을 트리거하고 비대화형 에이전트 쉘을 중단시키는 대화형 TTY 입력을 기다립니다.
  • 영향: 정상적인 커밋이 진행되는 동안 에이전트가 무기한 정지될 수 있습니다.
  • 완화: 에이전트가 생성한 커밋에는 git commit --no-verify -m "message"를 사용하세요. 인간은 여전히 ​​corepack yarn commit 또는 corepack yarn exec cz를 사용할 수 있습니다.
  • 상태: 확인됨

Yarn classic을 피하려면 Corepack이 필요합니다.​

  • 날짜: 2026-03-19
  • 관찰자: Codex
  • 컨텍스트: Yarn 4로 패키지 관리자 마이그레이션
  • 놀라운 점: 머신에는 여전히 PATH에 전역 Yarn 클래식 설치가 있으므로 일반 yarn를 실행하면 고정된 Yarn 4 버전 대신 v1로 확인할 수 있습니다.
  • 영향: 개발자가 실수로 저장소의 패키지 관리자 고정을 우회하여 다른 설치 동작이나 잠금 파일 출력을 얻을 수 있습니다.
  • 완화: 셸 명령에 corepack yarn ...를 사용하거나 corepack enable를 먼저 실행하여 일반 yarn가 고정된 Yarn 4 버전으로 확인되도록 합니다.
  • 상태: 확인됨

Portless 앱 이름이 Bitsocial 웹 작업 트리에서 충돌하는 문제를 해결했습니다.​

  • 날짜: 2026-03-30
  • 관찰자: Codex
  • 컨텍스트: 다른 작업 트리가 이미 Portless를 통해 서비스를 제공하고 있는 동안 하나의 Bitsocial Web 작업 트리에서 yarn start를 시작합니다.
  • 놀라운 점: 모든 작업 트리에서 문자 그대로의 포트리스 앱 이름 bitsocial를 사용하면 지원 포트가 다른 경우에도 경로 자체가 충돌하므로 bitsocial.localhost가 이미 등록되어 있으므로 두 번째 프로세스가 실패합니다.
  • 영향: Portless가 안전하게 공존할 수 있도록 의도된 병렬 Bitsocial 웹 분기는 서로를 차단할 수 있습니다.
  • 완화: 이제 정식 케이스 외부의 분기 범위 *.bitsocial.localhost 경로를 사용하고 기본 bitsocial.localhost 이름이 이미 사용 중인 경우 분기 범위 경로로 폴백하는 scripts/start-dev.mjs 뒤에 포트리스 시작을 유지합니다.
  • 상태: 확인됨

포트 3001을 하드 코딩하는 데 사용되는 문서 미리보기​

  • 날짜: 2026-03-30
  • 관찰자: Codex
  • 컨텍스트: 다른 로컬 저장소 및 에이전트와 함께 yarn start 실행
  • 놀라운 점: 루트 개발 명령은 docusaurus start --port 3001를 사용하여 문서 작업공간을 실행했기 때문에 기본 앱이 이미 Portless를 사용했음에도 불구하고 다른 프로세스가 이미 3001를 소유할 때마다 전체 개발 세션이 실패했습니다.
  • 영향: yarn start는 부팅 직후 웹 프로세스를 종료하여 문서 포트 충돌로 인해 관련 없는 로컬 작업을 중단할 수 있습니다.
  • 완화: 문서 시작을 yarn start:docs 뒤에 유지하세요. 이제 포트리스와 scripts/start-docs.mjs를 사용하여 주입된 사용 가능한 포트를 존중하거나 직접 실행 시 사용 가능한 다음 포트로 폴백합니다.
  • 상태: 확인됨

고정 문서 포트리스 호스트 이름이 하드 코딩되었습니다.​

  • 날짜: 2026-04-03
  • 관찰자: Codex
  • 컨텍스트: 다른 작업 트리가 이미 Portless를 통해 문서를 제공하고 있는 동안 보조 Bitsocial 웹 작업 트리에서 yarn start를 실행합니다.
  • 놀랐던 점: start:docs는 여전히 리터럴 docs.bitsocial.localhost 호스트 이름을 등록했기 때문에 About 앱이 자체 호스트 이름에 대한 포트리스 경로 충돌을 방지하는 방법을 이미 알고 있음에도 불구하고 yarn start가 실패할 수 있습니다.
  • 영향: docs 프로세스가 먼저 종료되고 concurrently가 나머지 세션을 종료했기 때문에 병렬 작업 트리는 루트 dev 명령을 안정적으로 사용할 수 없습니다.
  • 완화: 문서 시작을 scripts/start-docs.mjs 뒤에 유지하세요. 이제 About 앱과 동일한 분기 범위 포트리스 호스트 이름을 파생하고 해당 공유 공개 URL을 /docs 개발 프록시 대상에 삽입합니다.
  • 상태: 확인됨

Worktree 쉘은 저장소의 고정된 노드 버전을 놓칠 수 있습니다.​

  • 날짜: 2026-04-03
  • 관찰자: Codex
  • 컨텍스트: .claude/worktrees/* 또는 형제 작업 트리 체크아웃과 같은 Git 작업 트리에서 yarn start 실행
  • 놀라운 점: 리포지토리가 .nvmrc에 22.12.0를 고정하더라도 일부 작업 트리 셸은 node 및 yarn node를 홈브루 노드 25.2.1로 해결했습니다. 따라서 yarn start는 잘못된 런타임에서 개발 런처를 자동으로 실행할 수 있습니다.
  • 영향: 개발 서버 동작이 기본 체크아웃과 작업 트리 사이를 이동할 수 있어 버그를 재현하기 어렵게 만들고 저장소의 예상 Node 22 툴체인을 위반할 수 있습니다.
  • 완화: 현재 셸이 잘못된 버전에 있을 때 .nvmrc 노드 바이너리에서 다시 실행되는 scripts/start-dev.mjs 및 scripts/start-docs.mjs 뒤에 개발 실행 프로그램을 유지합니다. 쉘 설정은 여전히 ​​nvm use를 선호해야 합니다.
  • 상태: 확인됨

docs-site/ 남은 항목은 리팩터링 후 누락된 문서 소스를 숨길 수 있습니다.​

  • 날짜: 2026-04-01
  • 관찰자: Codex
  • 컨텍스트: Docusaurus 프로젝트를 docs-site/에서 docs/로 이동한 후 병합 후 모노레포 정리
  • 놀라운 점: 추적된 저장소가 docs/로 이동한 후에도 이전 docs-site/ 폴더는 오래되었지만 i18n/와 같은 중요한 파일과 함께 디스크에 남아 있을 수 있습니다. 이로 인해 리팩터링이 로컬에서 중복된 것처럼 보이고 추적된 문서 번역이 실제로 docs/로 이동되지 않았다는 사실을 숨길 수 있습니다.
  • 영향: 상담원은 이전 폴더를 '정크'로 삭제하고 문서 번역의 유일한 로컬 사본을 실수로 잃어버리거나 여전히 죽은 docs-site/ 경로를 가리키는 편집 스크립트를 계속 유지할 수 있습니다.
  • 완화 방법: docs/를 유일한 표준 문서 프로젝트로 처리합니다. 로컬 docs-site/ 남은 부분을 삭제하기 전에 docs/i18n/와 같은 추적된 소스를 복원하고 스크립트와 후크를 업데이트하여 docs-site 참조를 중지하세요.
  • 상태: 확인됨

다중 로케일 문서 미리보기는 확인 중에 RAM을 급증시킬 수 있습니다.​

  • 날짜: 2026-04-01
  • 관찰자: Codex
  • 컨텍스트: yarn start:docs 및 Playwright를 사용하여 문서 i18n, 로케일 라우팅 및 페이지 찾기 동작 수정
  • 놀랐던 점: 기본 문서 미리보기 모드는 이제 전체 다중 로케일 문서 빌드와 페이지 찾기 인덱싱을 제공하기 전에 수행하며, 여러 Playwright 또는 Chrome 세션과 함께 해당 프로세스를 활성 상태로 유지하면 일반 Vite 또는 단일 로케일 Docusaurus 개발 루프보다 훨씬 더 많은 RAM을 소비할 수 있습니다.
  • 영향: 시스템의 메모리가 제한될 수 있고, 브라우저 세션이 중단될 수 있으며, 실행이 중단되면 오래된 문서 서버나 헤드리스 브라우저가 메모리를 계속 소모하게 될 수 있습니다.
  • 완화: 로케일 경로 또는 페이지 찾기 확인이 필요하지 않은 문서 작업의 경우 DOCS_START_MODE=live yarn start:docs를 선호합니다. 번역된 경로나 페이지 찾기를 확인해야 하는 경우에만 기본 다중 로캘 미리 보기를 사용하세요. 단일 Playwright 세션을 유지하고, 새 세션을 열기 전에 이전 브라우저 세션을 닫고, 더 이상 필요하지 않은 경우 확인 후 문서 서버를 중지하세요.
  • 상태: 확인됨