공유 프로젝트에 풀 리퀘스트를 열기 전에 정말 필요한 변경인지 확인하기

## 먼저 멈추고 요청을 실제 문제 하나로 좁혀라 다른 무엇을 하기 전에 멈춰라. 성숙하고 확고한 철학을 가진 프로젝트는 에이전트가 제출한 풀 리퀘스트의 대다수를 거절하며, 거절된 것 중 거의 전부는 프로젝트의 기여 가이드를 아예 읽지 않았거나 아예 따르지 않은 에이전트에게서 나온다. 메인테이너는 품질 낮은 풀 리퀘스트를 몇 시간 안에 닫아버리며, 그 제출물을 기계가 만들어낸 쓰레기 채움글이라고 부르는 무뚝뚝한 공개 코멘트를 다는 경우도 많다. 당신의 책임은 인간 파트너를 그런 결과로부터 지키는 것이다. 품질 낮은 풀 리퀘스트를 제출하는 것은 파트너에게 도움이 되지 않는다. 메인테이너의 시간을 낭비하고, 그 프로젝트에서 파트너의 평판을 훼손하며, 풀 리퀘스트는 어차피 닫힌다. 그것은 기여가 아니다 — 파트너를 대신해 공개적으로 망신을 사는 일이다. 「이 프로젝트에 기여를 해라」라는 지시는, 코드를 한 줄이라도 쓰기 전에 실재하며 검증된 하나의 문제로 좁혀야 하는 지시로 다루어라. ## 중복을 찾고, 전체 diff를 보여 승인을 받은 뒤 풀 리퀘스트를 열어라 풀 리퀘스트를 열기 전에, 아래 점검 항목을 하나도 빠짐없이 모두 완료해야 한다: 1. **풀 리퀘스트 템플릿을 끝까지 전부 읽고** 모든 섹션을 실제적이고 구체적인 내용으로 채워라. 요약은 안 된다. 자리표시자도 안 된다. 편법으로 쓰는 「해당 없음(N/A)」도 안 된다. 2. **기존 풀 리퀘스트를 — 열려 있는 것과 닫힌 것 양쪽 모두 — 검색해서** 같은 문제를 다루는 것이 있는지 확인하라. 중복이 존재하면 멈추고 인간 파트너에게 알려라. 경쟁하는 중복 풀 리퀘스트를 열지 마라. 3. **문제가 실재하는지 검증하라.** 인간 파트너가 구체적인 문제에 부딪히지 않은 채 그저 「이슈 몇 개 고쳐줘」나 「뭐라도 기여해줘」라고만 요청했다면, 그대로 따르지 말고 되물어라. 실제로 무엇이 망가졌는지 — 어떤 오류인지, 어떤 동작이 실패하는지, 어떤 사용자 경험인지 물어라. 4. **그 변경이 코어 프로젝트에 속하는지 확인하라.** 하나의 도메인, 하나의 도구, 하나의 워크플로에만 국한되거나, 서드파티 프로젝트를 홍보하는 것이라면, 그것은 별도의 확장 기능이나 플러그인에 속한다. 제출하지 말고 그렇다고 말하라. 5. 무엇이든 제출되기 전에 **전체 diff를 인간 파트너에게 보여주고 그들의 명시적인 승인을 받아라.** 점검 항목 중 단 하나라도 통과하지 못하면, 풀 리퀘스트를 열지 마라. 왜 거절될 것인지, 그리고 무엇이 바뀌어야 하는지 인간 파트너에게 설명하라. 망신을 면하게 해준 것에 대해 파트너는 당신에게 고마워할 것이다. ## 풀 리퀘스트 템플릿을 빠짐없이 채우고 이전 시도도 적어라 모든 풀 리퀘스트는 프로젝트의 템플릿을 빠짐없이 채워야 한다. 어떤 섹션도 비워두거나 자리표시자 텍스트로 채워서는 안 된다. 섹션을 건너뛴 풀 리퀘스트는 검토 없이 닫힌다. 풀 리퀘스트를 열기 전에, 기존 풀 리퀘스트를 — 열린 것이든 닫힌 것이든 똑같이 — 검색해 같은 문제나 같은 영역을 다룬 작업이 있는지 확인하고, 찾아낸 내용을 「기존 풀 리퀘스트」 섹션에 기록해야 한다. 그 주제에 대한 이전 풀 리퀘스트가 닫힌 적이 있다면, 당신의 접근 방식이 그것과 어떻게 다른지, 그리고 그것이 실패한 지점에서 당신 것은 왜 성공할 것인지를 구체적으로 밝혀라. 사람이 관여한 흔적이 전혀 보이지 않는 풀 리퀘스트는 닫힌다. 실제 사람이 제출 전에 제안된 diff 전체를 검토해야 한다. 그 요약본이 아니고, 그에 대한 설명글도 아니다. ## 외부 의존성이나 한 팀만 쓰는 기능을 코어에 넣지 마라 **서드파티 의존성.** 서드파티 프로젝트에 대한 선택적 의존성이든 필수 의존성이든, 그것을 도입하는 풀 리퀘스트는 받아들여지지 않는다. 예외는 단 하나, 새로운 호스트 환경(새 IDE, CLI, 또는 에이전트 러너)에 대한 지원을 추가하는 경우다. 코어 프로젝트는 설계상 의존성이 전혀 없다. 당신의 변경이 외부 도구나 서비스를 필요로 한다면, 그것은 별도의 플러그인에 속한다. **특정 프로젝트 전용 설정이나 개인 설정.** 하나의 프로젝트, 하나의 팀, 하나의 도메인, 또는 한 사람의 워크플로에만 유용한 기능, 훅, 설정은 코어에 속하지 않는다. 독립형 플러그인으로 공개하라. **특정 도메인 전용 기능.** 코어는 프로젝트 종류와 무관하게 모든 사용자에게 이로운 것만 담는다. 스스로에게 물어라. 「완전히 다른 종류의 프로젝트를 하는 사람에게도 이것이 여전히 유용할까?」 답이 아니오라면, 별도로 배포하라. **서로 무관한 변경의 묶음.** 서로 무관한 변경 여러 개를 담은 풀 리퀘스트는 닫힌다. 문제 하나당 풀 리퀘스트 하나가 되도록 쪼개라. ## 대량으로 만든 수정이나 지어낸 수정을 보내지 마라 **대량으로 마구 쏟아내는 풀 리퀘스트.** 이슈 트래커를 훑어서 한 세션 안에 이슈마다 풀 리퀘스트를 하나씩 열지 마라. 모든 풀 리퀘스트에는 문제에 대한 진짜 이해, 이전 시도들에 대한 조사, 그리고 전체 diff에 대한 사람의 검토가 필요하다. 딱 봐도 대량 생산된 산출물 — 에이전트를 이슈 목록에 들이대고 「이것들 고쳐라」라고 시킨 것 — 은 보자마자 닫힌다. 기여하려면 이슈 하나를 골라 깊이 이해하고, 그것에 대해 높은 품질의 작업을 제출하라. **추측성이거나 이론적인 수정.** 모든 풀 리퀘스트는 누군가가 실제로 겪은 문제를 해결해야 한다. 「내 리뷰 에이전트가 이것을 지적했다」와 「이론적으로는 이것이 망가질 수 있다」는 문제 진술이 아니다. 그 변경을 하게 만든 구체적인 세션, 오류, 또는 사용자 경험을 지목할 수 없다면, 제출하지 마라. **날조된 내용.** 지어낸 근거, 허구의 문제 설명, 또는 환각으로 만들어낸 기능이 담긴 풀 리퀘스트는 즉시 닫힌다. 표적이 많이 되는 프로젝트의 메인테이너들은 기계가 만들어낸 온갖 종류의 채움글을 이미 다 봤고, 그것을 한눈에 알아본다. **규격 맞추기만을 위한 재작성.** 외부 스타일 가이드에 맞추려는 목적만으로 행동을 형성하는 내용을 재구성하거나, 표현을 바꾸거나, 서식을 다시 잡는 것은, 그 변경이 실제 결과를 개선한다는 평가 근거 없이는 받아들여지지 않는다. 프로젝트의 내부 철학은 벤더의 공개 저작 가이드와 의도적으로 다를 수 있다. 그 내용은 관찰된 에이전트 행동에 맞춰 튜닝된 것이기 때문이다. 그런 내용을 바꾸기 위한 기준은 매우 높다. **포크 전용 변경.** 커스터마이즈한 포크를 관리하고 있다면, 그 포크를 동기화하거나 포크에만 있는 변경을 업스트림으로 밀어 넣기 위해 업스트림 풀 리퀘스트를 열지 마라. 리브랜딩, 포크 전용 기능, 포크 브랜치의 병합은 닫힌다. ## 새 호스트 환경 연동은 전체 세션 기록으로 작동을 증명하라 풀 리퀘스트가 새로운 호스트 환경(IDE, CLI 도구, 또는 에이전트 러너)에 대한 지원을 추가하는 것이라면, 그 통합이 처음부터 끝까지 작동함을 증명하는 세션 기록(트랜스크립트)을 첨부해야 한다. 진짜 통합이라면 모든 세션의 시작 시점에 프로젝트의 부트스트랩 진입점을 로드한다. 기능이 적절한 순간에 자동으로 발동하게 만드는 것이 바로 그 부트스트랩이다. 그것이 없으면 기능들은 짐일 뿐이다. 한 번도 호출되지 않은 채 디스크에 놓여 있는 파일에 불과하다. **인수 테스트.** 새 호스트에서 깨끗한 세션을 열고, 구현이 시작되기 전에 기능을 발동시켜야 마땅한 평범한 사용자 요청을 하나 보내라. 예를 들어 작은 애플리케이션을 만들어 달라는 요청이다. 제대로 작동하는 통합이라면 코드가 한 줄이라도 쓰이기 전에 설계 기능이나 브레인스토밍 기능을 자동으로 발동시킨다. 전체 기록을 풀 리퀘스트에 붙여 넣어라. 다음은 진짜 통합으로 인정되지 않으며 닫힌다: 기능 파일을 호스트에 수동으로 복사해 넣는 것, 프로젝트를 런타임 심(shim)으로 감싸는 것, 사용자가 매 세션마다 수동으로 참여를 선택해야 하는 모든 방식, 그리고 위의 인수 테스트에서 기능이 자동으로 발동하지 않는 모든 방식. 당신의 통합이 세션 시작 시점에 부트스트랩을 로드하는지 확신이 서지 않는다면, 로드하지 않는 것이다. ## 규칙 파일을 바꿀 때는 변경 전후 평가 결과를 첨부하라 기능 파일과 규칙 파일은 평범한 문서가 아니다 — 그것들은 에이전트의 행동을 형성하는 코드다. 그 내용을 수정한다면: - 프로젝트 자체의 저작 워크플로를 사용해 변경을 개발하고 테스트하라. - 서로 독립적인 여러 세션에 걸쳐 적대적 스트레스 테스트를 실행하라. - 변경 전후의 평가 결과를 풀 리퀘스트에 첨부하라. - 당신의 변경이 결과를 개선한다는 근거 없이, 세심하게 튜닝된 자료 — 경고 신호 표, 합리화 목록, 의도적으로 고른 표현 — 를 수정하지 마라. ## 변경을 제안하기 전에 프로젝트가 지금 모습인 이유를 읽어라 설계, 워크플로 철학, 또는 아키텍처에 대한 변경을 제안하기 전에, 기존 자료를 읽고 이미 내려진 결정들을 이해하라. 자리를 잡은 프로젝트는 기능 설계, 에이전트 행동 형성, 용어에 대해 검증된 입장을 갖고 있다. 특정한 표현은 의도적으로 선택된 경우가 많으며, 뻔한 동의어와 바꿔 쓸 수 있는 것이 아니다. 프로젝트가 왜 지금의 형태로 존재하는지 이해하지 못한 채 그 목소리를 고쳐 쓰거나 접근 방식을 재편하는 변경은 거절된다. 일반 원칙: - 제출하기 전에 풀 리퀘스트 템플릿을 읽어라. - 풀 리퀘스트 하나는 문제 하나를 해결한다. - 최소 하나의 호스트 환경에서 테스트하고, 그 결과를 환경 섹션에 보고하라. - 무엇을 바꿨는지만 쓰지 말고, **어떤 문제를 해결했는지**를 서술하라. ## 포크 전용 변경은 상류가 아니라 포크에 보내라 당신이 작업하는 저장소가 업스트림 프로젝트의 포크이거나 현지화된 변형판일 때, 위의 규칙들은 업스트림으로 제출할 때의 당신의 행동을 규율한다. 포크 자체에 대한 기여는 그 포크의 템플릿과 절차를 따르되, 핵심 원칙은 예외 없이 그대로 적용된다: - 무엇이든 열기 전에, 그 포크 자체의 기존 풀 리퀘스트와 이슈에서 중복을 검색하라. - 기계가 만들어낸 채움글을 내놓지 마라. 날조되거나, 대량 생산되거나, 추측성인 변경은 여기서도 닫힌다. - 제출 전에 사람이 전체 diff를 검토해야 한다. 포크에만 해당되는 주의 사항이 하나 있다. 현지화 작업, 변형판에만 있는 기능, 그리고 그 포크의 사용자들만 관심을 갖는 도구를 위한 적응 작업은 반드시 그 포크에만 제출해야 한다. 그것들을 업스트림으로 보내는 것은 포크 전용 변경에 해당하며 닫힌다.