AI 에이전트가 .gitignore를 망치는 이유와 이를 해결하는 규칙들

.gitignore 파일은 리포지토리에서 가장 쉽게 제대로 만들 수 있는 파일처럼 보입니다. 하지만 에이전트들은 여전히 예측 가능한 방식으로 이 파일을 잘못 처리합니다:

• 사용하지 않는 20개 언어를 포괄하는 거대한 일반 템플릿을 붙여넣습니다.
• 실제 소스 파일을 숨기기에 충분히 광범위한 패턴을 추가합니다.
• 파일 전체의 순서를 바꾸거나 형식을 재정비합니다.
• 문제를 일으키는 바로 그 파일을 무시함으로써 '수정'했다고 주장합니다.
• 작동하는지 확인하지 않고 그냥 그렇게 되었다고 주장합니다.

UNIVERSAL-AGENTS.md의 규칙들은 이러한 이유로 .gitignore에 별도의 섹션(Section 13)을 할애했습니다. 주요 아이디어는 다음과 같습니다.

규칙 1: 필요할 때만 건드리기

에이전트는 요청된 변경 사항이 반드시 필요하거나, 프로젝트 생성/임시/로컬 또는 개발 전용 파일이 실수로 추적되는 것을 막기 위해 필요할 때만 .gitignore를 생성하거나 업데이트해야 합니다.

그리고 이 규칙은 명확합니다: 단순히 일반 템플릿을 추가할 수 있다는 이유만으로 수정해서는 안 됩니다.

규칙 2: 실제 프로젝트부터 살펴보기

무언가를 변경하기 전에, 에이전트는 다음 체크리스트를 거칩니다: 사용 중인 언어, 프레임워크 및 런타임, 패키지 관리자 및 의존성 디렉토리, 빌드 시스템 및 출력 디렉토리, 테스트 및 커버리지 도구, IDE 및 에디터, 그리고 기존의 .gitignore 파일.

그런 다음 자신이 매우 좋아하는 규칙을 적용합니다: 실제 프로젝트를 분석하지 않고 일반 템플릿을 붙여넣지 마십시오. 모노레포(monorepo)의 경우, 리포에 실제로 존재하는 기술에 대한 규칙만 포함해야 합니다. Python 프로젝트가 Unity 규칙을 필요로 하지는 않습니다.

규칙 3: 기존 내용을 보존하기

기존 파일을 업데이트할 때, 에이전트는 다음을 수행해야 합니다:

• 유효한 프로젝트별 규칙은 유지합니다.
• 생성된 템플릿으로 사용자 정의 패턴을 덮어쓰지 않습니다.
• 이유 없이 규칙의 순서를 바꾸거나 파일 형식을 재정비하지 않습니다.
• 새 항목은 명확하고 일관성 있는 위치에 추가합니다.
• 중복되거나 충돌하는 패턴을 피합니다.

요약하자면, 필요한 최소한의 변경만 해야 합니다. 이렇게 하면 diff를 검토하기 쉽고 Git 히스토리를 깨끗하게 유지할 수 있습니다.

규칙 4: 광범위하지 않고 정확하게]

광범위한 패턴은 실제 파일이 버전 관리에서 사라지게 만드는 방식입니다. 규칙들은 생성된 아티팩트를 목표로 하는 정밀한 패턴을 선호하고, 합법적인 소스 파일이나 필수 에셋을 무시할 수 있는 패턴은 피하라고 말합니다.

Rule 5: 필요한 파일을 절대 숨기지 마세요

섹션 13.7에서는 무시해서는 안 되는 항목들(필수 소스, 설정, 템플릿, 문서, 에셋, 의도적으로 추적하는 lockfile, 빌드나 테스트 또는 배포에 필요한 파일)을 나열합니다. 또한 .gitignore를 사용하여 구현 문제를 숨기지 말라고 명시합니다.

환경 파일은 특별한 주의가 필요합니다. 비밀 정보(Secrets)는 절대 커밋해서는 안 되지만, 에이전트가 모든 설정을 무차별적으로 무시해서도 안 됩니다. 다음과 같은 추적된 예제 파일들은 보존되어야 합니다:

text .env.example .env.template config.example

Rule 6: 무시한다고 해서 추적이 풀리는 것은 아닙니다

이것은 사람들에게도 혼란을 주는 부분입니다. .gitignore에 패턴을 추가하는 것이 Git이 이미 추적하고 있는 파일을 제거하지 않습니다. 섹션 13.8에서는 명시적으로 요청받지 않는 한, 새로운 규칙을 강제하기 위해 추적된 파일을 제거하거나 파괴적인 Git 작업을 실행해서는 안 된다고 에이전트에게 지시합니다.

섹션 27은 이를 강화하며, 명시적인 승인 없이 reset --hard, clean -fd, force-push, 또는 히스토리 재작성은 금지됩니다.

Rule 7: 정직하게 검증하세요

파일을 변경한 후, 에이전트는 규칙이 스택과 일치하는지, 필요한 파일이 무시되지 않았는지, 기존 규칙들이 살아남았는지, 그리고 중복되거나 지나치게 광범위하거나 관련 없는 패턴이 포함되지 않았는지를 확인합니다. 실제로 검사하지 않았다면 무시 동작을 검증했다고 주장해서는 안 됩니다.

저의 빠른 팁(규칙에서 나온 것은 아님): git check-ignore -v path/to/file 명령어로 주어진 경로가 무엇과 일치하는지 확인할 수 있습니다.

한 문단 요약

전체 섹션 요약

수정 사항이 필요할 경우, 프로젝트의 실제 언어, 프레임워크, 런타임, 패키지 관리자, 빌드 시스템 및 도구를 기반으로 .gitignore 변경 사항을 작성하고, 기존 사용자 정의 규칙은 유지하며, 로그 파일, 임시 파일, 캐시, 빌드 출력물 및 로컬 환경 파일을 버전 제어에서 제외하는 데 필요한 최소한의 패턴만 추가하세요.

사용해 보기

AGENTS.md를 저장소 루트에 넣으면 에이전트가 전체 정책과 나머지 가드레일을 얻게 됩니다. MIT 라이선스이며, 어떤 스택에도 적용 가능합니다.

👉 https://github.com/NTDevLops/UNIVERSAL-AGENTS.md

AI가 저지른 최악의 .gitignore 실수는 무엇이었나요?