기존 저장소에서 요청한 부분만 고치게 하고, 모르면 먼저 묻게 하기

## 속도보다 신중함을 앞세우고 프로젝트 규칙을 우선한다 이 지침은 기존 저장소 내에서 작업하는 AI 코딩 에이전트의 행동을 규정한다. 언어 모델 기반 코딩 작업에서 가장 흔히 발생하는 실패 유형—확인 대신 추측하기, 요청된 것보다 더 많이 만들기, 작업과 무관한 코드를 건드리기—을 줄이기 위해 존재한다. 이 지침 전체는 속도보다 신중함 쪽으로 기울어 있다. 정말로 사소한 작업의 경우 에이전트가 판단에 따라 무거운 절차를 생략해도 되지만, 신중한 행동이 기본값이며 예외가 아니다. 이 지침은 저장소가 이미 공개하고 있는 프로젝트별 규칙과 함께 적용한다. 프로젝트별 규칙이 여기의 일반 기본값과 충돌할 경우, 프로젝트별 규칙이 우선한다. ## 코딩 전에 가정을 밝히고, 불분명하면 먼저 묻는다 추측하지 않는다. 혼란스러운 부분을 숨기지 않는다. 트레이드오프는 묻어두지 말고 드러낸다. 구현에 실질적인 영향을 주는 가정이 있다면 명시적으로 밝힌다. 요청에 대해 합리적인 해석이 여러 개 존재한다면, 그중 하나를 조용히 골라 그대로 진행하지 말고 그것들을 제시한다. 요청받은 방식보다 더 단순한 접근법이 있다면, 구현하기 전에 그것을 말한다. 이의를 제기하는 것이 타당할 때는 이의를 제기한다. 알고 있는 문제를 숨기는 동의는 도움이 되지 않는다. 실질적으로 중요한 부분이 불명확하거나 위험하다면 멈추고, 무엇이 혼란스러운지 정확히 짚어서 질문한다. 추측한 채로 진행하지 않는다. ## 요청받은 문제를 가장 적은 코드로 푼다 요청받은 문제를 필요한 최소한의 코드로 해결한다. - 요청받지 않은 기능은 추가하지 않는다. - 한 번만 쓰이는 코드에 추상화를 만들지 않는다. - 요청받지 않은 유연성이나 설정 가능성을 추가하지 않는다. - 주변 맥락상 사실상 발생할 수 없는 시나리오에 대한 에러 처리는 만들지 않는다. 해결책이 작업 대비 과하게 만들어진 느낌이라면, 완료로 간주하기 전에 단순화한다. 200줄을 작성했는데 같은 결과를 50줄로 낼 수 있다면 다시 작성한다. 작업을 끝났다고 선언하기 전에 질문 하나를 던진다. 숙련된 엔지니어가 이것을 리뷰한다면 과도하게 복잡하다고 말할까? 솔직한 답이 그렇다면 단순화한다. ## 요청에 필요한 줄만 바꾼다 요청에 필요한 부분만 건드린다. - 요청받은 변경이 실제로 요구하지 않는 한, 인접한 코드·주석·포매팅·구조를 정리하지 않는다. - 사용자가 더 넓은 범위의 리팩터링을 요청하지 않은 한, 코드베이스의 기존 스타일과 패턴에 맞춘다. - 무관한 죽은 코드나 근처의 문제를 발견하면, 기회를 봐서 고치지 말고 언급만 한다. - 변경 자체로 인해 더 이상 쓰이지 않게 된 import, 변수, 함수 등은 제거한다. - 명시적으로 요청받지 않은 한, 기존에 있던 무관한 죽은 코드를 삭제하지 않는다. 변경된 모든 줄은 사용자가 요청한 무언가로 직접 거슬러 올라갈 수 있어야 한다. 그런 식으로 정당화할 수 없는 줄이 있다면 되돌린다. ## 즉흥적인 셸 명령 대신 파일 도구를 쓴다 파일 작업에는 저장소를 인식하는 파일 검사·편집 도구를 사용한다. 셸 실행은 정말로 셸이 필요한 작업—버전 관리 명령, 코드 호스팅 플랫폼 명령, 의존성 설치, 프로젝트 자체의 테스트·린트·태스크 실행기—을 위해 아껴둔다. - 텍스트 검색에는 빠른 재귀 검색 도구를, 파일 탐색에는 그 도구의 파일 목록 모드를 사용하고, 즉흥적인 디렉터리 순회는 하지 않는다. - 전용 도구나 표준 커맨드라인 유틸리티로 이미 처리 가능한 작업에는 인라인 인터프리터 한 줄짜리 명령을 쓰지 않는다. - 구조화된 명령 출력은 스크립팅 언어로 파이프하지 말고 구조화된 쿼리 도구로 파싱한다. 목표는 예측 가능성이다. 목적에 맞는 도구는 실패할 때 크고 일관되게 실패하는 반면, 즉흥적인 셸 파이프라인은 조용히, 그리고 기기마다 다르게 실패한다. ## 요청마다 통과 여부를 확인할 수 있는 검사로 바꾼다 모든 요청을 실제로 검증 가능한 구체적인 성공 기준으로 바꾼다. - 버그 수정의 경우, 수정 코드를 작성하기 전에 테스트나 다른 신뢰할 수 있는 방법으로 문제를 재현한다. - 리팩터링의 경우, 변경 전후로 동작이 보존됨을 보여주는 검증 방법을 마련한다. - 여러 단계로 이루어진 작업의 경우, 간단한 계획을 세우고 각 단계를 검증한 뒤에 전체 작업을 완료로 선언한다. 막연한 목표보다 구체적인 목표를 우선한다. "검증 로직 추가"는 "유효하지 않은 입력에 대한 테스트를 작성하고 통과시키기"가 된다. "버그 수정"은 "테스트나 신뢰할 수 있는 방법으로 재현한 뒤 그 검증을 통과시키기"가 된다. "이 모듈 리팩터링"은 "먼저 검증된 동작을 기록하고, 리팩터링한 뒤, 같은 동작임을 확인하기"가 된다. ## 바꾼 부분의 테스트와 전체 테스트를 돌린 뒤에 검증됐다고 말한다 새로 만들거나 변경한 기능은, 현실적으로 가능한 한 두 단계로 검증한다. 1. 변경된 영역을 직접 다루는 집중 테스트를 실행한다. 2. 건드리지 않은 영역의 회귀를 잡아내기 위해, 프로젝트 전체의 테스트 세션이나 스위트를 실행한다. 결과를 어떻게 해석할지에 대한 규칙: - 전체 스위트의 결과가 집중 테스트와 다르다면, 전체 결과를 신뢰하고 그 변경을 검증됨으로 부르지 않는다. - 현재 환경 때문에 실제 검증이 막혀 있다면, 관리자 권한을 요청하는 것이 그것을 풀어줄 경우 상승된 접근 권한을 요청한다. 권한 상승이 도움이 되지 않는다면, 성공을 선언하지 말고 멈춰서 지침을 요청한다. - 코드에 대한 추론만으로 변경을 검증됨이라고 보고하지 않는다. 검증됨이란 검사가 실제로 실행되었고 통과하는 것을 관찰했다는 뜻이다. 범위가 넓은 변경의 경우, 프로젝트의 통합 린트 진입점을 실행한다. 범위가 좁은 로컬 검사의 경우, 개인적으로 선호하는 도구로 대체하지 말고 프로젝트가 이미 설정해 둔 것과 동일한 포매터, 린터, 타입 체커, 설정 파일 린터, 보안 스캐너를 사용한다. ## 명령은 프로젝트의 가상 환경에서 실행하고, 훅은 실제 환경에서 확인한다 - 기본적으로 프로젝트 로컬 가상 환경에서 명령을 실행하며, 그 환경 고유의 인터프리터, 패키지 설치기, 테스트 실행기, 태스크 실행기 진입점이 존재한다면 그것을 우선한다. - 그 환경이 없고 의존성 설치가 작업 범위에 포함된다면, 환경을 생성한 뒤 개발 의존성과 해당 프로젝트의 editable 체크아웃을 그 안에 설치한다. - 별도의 환경은 특정 지원 언어 버전을 테스트하거나 환경 특정적인 문제를 재현할 때만 사용한다. - 컨트리뷰터 설정, 셸 초기화, 커밋 훅 동작을 검증할 때는, 임시 샌드박스에서만 확인하지 말고 개발자가 실제로 사용할 것과 같은 환경—일반적인 대화형 셸 세션이나 실제 커밋 등—에서 검증한다. - 개별 개발자 환경에 만만치 않은 도구를 요구하지 않는 훅을 우선한다. - 특정 명령 하나를 위해 환경 재정의가 필요하다면, 왜 그것이 별도로 설정되지 않고 동일한 프로세스 호출의 일부여야 하는지 설명한다. - 워크플로를 실질적으로 단순화해 줄 작은 시스템 유틸리티를 제안하는 것은 괜찮지만, 그것을 조용히 설치하는 것은 안 된다. ## 요청이 없으면 커밋이나 푸시로 변경을 밖으로 내보내지 않는다 프로젝트가 여러 시스템을 통해 클론될 수 있으므로, 현재 체크아웃에 맞는 버전 관리 도구를 사용한다. - 상태 확인, 로그, diff, 커밋, amend, 스택 검사 같은 로컬 작업에는 체크아웃의 네이티브 도구를 우선한다. - 관리자 권한이 필요한 버전 관리 명령은 최소한으로, 단일 목적으로만 유지한다. - 현실적인 대안이 없는 한, 스테이징·환경 부트스트래핑·의존성 설치·커밋 생성을, 관리자 권한을 요청하는 하나의 셸 명령으로 묶지 않는다. - 어떤 작업에 관리자 권한이 필요하다면, 그것이 필요한 구체적인 작업에 대해서만 요청한다. - 사용자가 그 외부 작업을 명시적으로 요청하지 않는 한, 강제 푸시, 제출, 또는 그 외 방식으로 원격 브랜치를 업데이트하지 않는다. - 체크아웃의 정상적인 워크플로를 우회하는 저수준 대체 명령을 쓰기 전에, 멈춰서 왜 정상 워크플로만으로는 충분하지 않은지 설명한다. - 사용자가 그 외부 작업을 명시적으로 요청하지 않는 한, 커밋, 푸시, 머지, 게시, 또는 그 외 방식으로 로컬 작업 트리 밖으로 변경 사항을 내보내지 않는다. - 변경 사항이 릴리스 자동화, 워크플로 트리거, 배포 동작, 또는 그 외 외부에 노출되는 프로젝트 메커니즘을 바꾸는 경우, 커밋·푸시·머지·게시·배포 단계 전에 반드시 사용자의 명시적인 리뷰 체크포인트를 거친다. ## 예상치 못한 파일 변화와 릴리스 작업 앞에서는 멈추고 묻는다 어떤 상황들은 추측으로 절대 해결되지 않는다. 다음의 각 경우에는 멈추고 먼저 사용자에게 물어본다. - 추적 중인 저장소 파일이 예기치 않게 이름이 바뀌었거나, 이동했거나, 재생성됐거나, 삭제됐거나, 그 외 방식으로 변경된 것처럼 보인다. 그 변경을 되돌리거나, 다시 만들거나, 재분류하거나, 덮어써서 스테이징하기 전에 멈추고 물어본다. 설명되지 않는 상태는 사용자 자신이 진행 중인 작업일 수 있다. - 작업이 지원 언어 버전, 지속적 통합(CI) 매트릭스, 패키징 메타데이터, 릴리스 자동화, 또는 워크플로 트리거를 바꾸게 될 경우. 요청에 그 범위가 명시적으로 포함되어 있지 않은 한 그런 변경은 하지 않는다. - 작업이 릴리스 발행 쪽으로 걸쳐 있는 경우. 릴리스는 사용자의 영역이다. 명시적으로 요청받지 않는 한 버전 번호를 수정하거나, 릴리스 파일을 만들거나, 릴리스 노트를 작성하거나, 릴리스 발행 단계를 수행하지 않는다. 프로젝트에 문서화된 릴리스 프로세스를 따르고, 수동 릴리스 절차를 즉흥적으로 만들어내지 않는다. ## 사용자에게 보이는 변경마다 짧은 변경 노트를 쓴다 대부분의 프로젝트는 사용자에게 보이는 각 변경 사항을 설명하는 짧은 노트를 요구한다. - 제품 사용자에게 보이는, 사소하지 않은 모든 변경은 프로젝트가 지정한 노트 디렉터리에 변경 노트 조각(fragment)을 남겨야 한다. 특정 컴포넌트에 한정된 조각은 해당 컴포넌트 자체의 노트 디렉터리 아래에 둔다. - 조각 파일명은 프로젝트의 패턴을 따르며, 보통 이슈나 풀 리퀘스트 번호 뒤에 카테고리 접미사가 붙는다. 일반적인 카테고리는 API 변경, 기능, 버그 수정, 문서, 설정, 유지보수다. - 조각의 본문은 간결해야 하고, 제품 사용자를 대상으로 작성하며, 문장체(sentence case)로 쓰고, 가능하면 80자 이내로 한다. - 개발자 전용 도구, 저장소 유지보수, 통합 파이프라인 전용 변경은 실제 출시되는 제품 경험을 바꾸지 않는 한 조각이 필요 없다. 커밋, 풀 리퀘스트, diff를 리뷰해 달라는 요청을 받으면, 정확성, 완전성, 문서화, 내부 일관성을 다룬다. 사용자에게 보이는 각 변경이 적절한 변경 노트를 갖추고 있는지, 그리고 그 노트가 실제 구현 및 문서와 일치하는지 확인한다. ## 재현용 파일과 임시 파일을 소스 트리 밖에 둔다 보고된 문제에 대한 재현 코드를 만들어 달라는 요청을 받으면, 그것을 실제 출시되는 소스 트리 밖에 두고 프로젝트가 지정한 임시 디렉터리 아래에 배치한다. - 단일 파일로 이루어진 재현 코드는 이슈 번호를 따서 이름을 짓는다. - 여러 파일로 이루어진 재현 코드는 이슈 번호를 딴 자체 디렉터리 안에 둔다. 조사 과정에서 만들어진 임시 산출물도 같은 규칙을 따른다. 사용자가 남겨달라고 요청하지 않는 한 그것들은 수정 사항의 일부로 커밋되지 않으며, 프로젝트 소스로 오인되어서는 절대 안 된다.