brainstorm 실행 스크립트의 심링크가 커밋에 섞이는 문제 수정

brainstorm 모듈의 실행 스크립트에서 node_modules 심링크가 실제 코드 변경과 함께 commit 되는 문제를 발견하고 수정했다. 작아 보이는 이슈지만, 이런 환경 파일들이 코드 변경 커밋에 포함되기 시작하면 리뷰 노이즈도 많아지고 머지 충돌도 잦아진다.

왜 심링크가 문제가 되는가

개발 환경에서 node 의존성을 관리할 때 symlink 를 활용하는 경우가 있다. 특히 monorepo 구조나 로컬 패키지 연결에서 유용하다. 하지만 이런 심링크는 개발 환경의 설정 일 뿐, 실제 코드 로직의 변경 이 아니다.

문제는:
- Symlink 는 OS/머신마다 다르게 해석될 수 있음
- Windows/Mac/Linux 환경에서 경로 표현이 다름
- PR 리뷰어 입장에서는 실제 변경사항 구분이 어려워짐
- 협업하는 팀원이 checkout 했을 때 자신의 환경과 맞지 않을 가능성

특히 code_change 를 추적하는 커밋이라면, 의도는 "내가 실제로 고쳤거나 추가한 로직"을 명확히 하는 것이다. 그런데 심링크까지 섞여 있으면 무엇이 본질적인 변경인지 헷갈린다.

문제의 발원지: brainstorm_exec.py

scripts/brainstorm_exec.py 는 아마도 brainstorm 모듈을 실제로 구동하고 프로세스를 관리하는 스크립트일 것 같다. 실행 중에 의존성을 동적으로 링크하거나, 환경 설정을 초기화하는 과정에서 node_modules 심링크를 만드는 부분이 있었던 것 같다.

문제 패턴:

brainstorm_exec.py 실행 
  ↓
node_modules symlink 생성 (로컬 환경 구성)
  ↓
git 스테이징 시 실수로 포함
  ↓
code_change commit에 섞임 (의도하지 않음)

이것은 흔한 패턴이다. 개발자가 스크립트를 돌리고, 로컬 테스트 후 바로 커밋하다 보면, working directory 에 생긴 심링크들이 tracking 되기 시작한다.

수정 방향: git 추적 분리

fix 의 핵심은 brainstorm_exec.py 실행 시 생기는 환경 파일들을 의도적으로 버전 컨트롤에서 제외 하는 것이다. 일반적으로 두 가지 방법이 있다:

스크립트 차원에서 symlink 생성 부분을 review 하면서, 그 심링크들이 불필요하게 git staging area 에 들어가지 않도록 명확히 하는 방식으로 진행했을 것이다.

회고: 환경 추적과 코드 추적의 경계

팀이 커질수록 "어떤 것을 버전 컨트롤에서 추적할 것인가"는 중요한 결정이다:

• 추적해야 할 것: 소스 코드, 설정 파일 (서버 config), 문서, 테스트
• 추적하면 안 될 것: 빌드 산출물, 환경 변수, 로컬 심링크, 임시 파일

이번 fix 를 팀과 함께 리뷰할 때, "왜 이런 일이 반복되는가"를 생각해 볼 필요가 있다:
- 개발 환경 스크립트가 cleanup 을 안 하고 있는가?
- Pre-commit hook 에서 심링크 같은 파일을 감지하고 경고할 수 있는가?
- CI/CD 에서 symlink 처리가 적절한가?

특히 개발자가 로컬에서 자주 돌리는 스크립트 라면, 그 스크립트가 남기는 artifact 를 명확히 문서화하고, 자동으로 무시하도록 설정하는 것이 팀의 인지 부하를 줄인다.

# brainstorm_exec.py 같은 스크립트에서 권장하는 패턴
# 1. 심링크를 만들 때 .gitignore 확인
# 2. 또는 임시 디렉토리 사용 (예: /tmp 또는 .cache/)
# 3. 또는 cleanup 함수 추가 (스크립트 종료 시 자동 제거)

이런 작은 수정들이 쌓이면, commit history 가 깔끔 해지고, PR 리뷰가 빨라 지고, 팀의 협업 friction 이 줄어든다. 코드 퀄리티만큼 commit 위생도 중요한 이유다.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 노트북 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.