API는 그대로 두고 클라이언트 라이브러리의 동기·비동기 버전 함께 수정하기

## 수정 전에 바꾸면 안 되는 공개 동작 정리하기 편집하기 전에 외부에 공개된 동작, 지원하는 런타임 버전, 관련 아키텍처, 변경을 담당하는 최소 파일 집합을 파악한다. - 공개 시그니처, 인수 이름, 기본값, 반환 형식, 예외, 경계 사례의 동작을 호환성 계약으로 취급한다. - 동기 클라이언트와 비동기 클라이언트처럼 동일한 동작을 담당하는 모든 병렬 구현을 찾는다. - 해당 동작에 관여할 수 있는 라우팅, 구문 분석, 정책, 연결, 응답 형식화 계층을 파악한다. - 패턴을 선택하기 전에 주변 구현, 테스트, 형식 오버로드를 읽는다. - 요청된 변경이 명시적으로 다른 동작을 요구하지 않는 한 기존 프로토콜과 서버의 의미 체계를 보존한다. - 관련 없는 정리 작업으로 범위를 확대하지 않는다. 요청된 동작이 문서화된 불변 조건과 충돌하면 계약을 몰래 다시 정의하지 말고 작업을 중단한 뒤 충돌을 명확히 알린다. ## 동기 클라이언트와 비동기 클라이언트에 같은 변경 적용하기 라이브러리가 동등한 클라이언트 스택을 제공한다면 양쪽의 동등성을 필수 속성으로 취급한다. 1. 변경한 동기 심벌을 비동기 대응 요소에 연결하거나 그 반대로 연결한다. 2. 시그니처, 오버로드, 형식 힌트, 기본값, 반환 구조, 오류, 부작용을 비교한다. 3. 문서화된 런타임 차이 때문에 불가능한 경우가 아니라면 두 스택에 동등한 동작을 적용한다. 4. 공유 명령 인터페이스, 라우팅 표, 구문 분석기 콜백, 정책 메타데이터를 일관되게 유지한다. 5. 두 스택 모두 해당 동작을 제공한다면 서로 대응하는 테스트를 추가한다. 코드베이스에서 확립된 형식 구문과 오버로드 규칙을 사용한다. 한쪽만 변경해야 한다면 구체적인 아키텍처상 이유를 기록하고 그 비대칭이 의도된 것인지 검증한다. ## 담당 계층만 고치고 기존 헬퍼 재사용하기 기존 보조 기능과 규칙을 재사용하는 정밀한 변경을 우선한다. - 해당 동작을 담당하는 계층만 변경한다. - 공개 인터페이스와 오류의 의미 체계를 보존한다. - 기존 기능으로 요구 사항을 충족할 수 없는 경우가 아니라면 새 의존성을 추가하지 않는다. - 현재 보조 기능이나 패턴으로 충분하다면 새 추상화를 도입하지 않는다. - 지연 가져오기가 기술적으로 필요한 경우가 아니라면 가져오기를 최소화하고 모듈 범위에 둔다. - 동작이 변경되면 문서화 문자열을 갱신하고 형식과 일치시킨다. 정확성을 최우선으로 한다. 동작이 정확해진 뒤에만 최적화하며, 메모리 할당량 절감이나 실행 속도 향상과 정확성을 절대 맞바꾸지 않는다. ## 자주 실행되는 경로를 느리게 하지 않고 프로토콜 동작도 바꾸지 않기 자주 실행되는 경로의 변경에서 피할 수 있는 메모리 할당, 반복 분석, 중복 작업, 큰 임시 구조가 생기지 않았는지 검토한다. - 확립된 보조 기능과 캐시된 메타데이터를 재사용한다. - 통신 프로토콜 선택을 사용자에게 보이는 응답 형식화와 독립적으로 유지한다. - 라우팅 및 집계 정책을 명령의 의미 체계와 일치시킨다. - 관련이 있다면 리디렉션, 재시도, 토폴로지 차이, 오류 전파를 명시적으로 처리한다. - 기반 서비스가 명확히 구분하여 제공하는 경계 사례를 몰래 정규화하지 않는다. 성능 변경은 외부에서 관찰할 수 있는 동작을 동일하게 유지해야 한다. 최적화가 정확성이나 동등성을 복잡하게 만든다면 더 단순하고 정확한 구현을 선택한다. ## 실패하는 테스트 하나부터 전체 테스트 매트릭스까지 넓혀 테스트하기 범위를 점진적으로 넓히며 근거를 쌓는다. 1. 수정 전에는 실패하는 결정론적 테스트를 추가하거나 갱신한다. 2. 관련된 최소 테스트 또는 테스트 모음을 실행한다. 3. 미러 구조의 동기 및 비동기 테스트 범위를 실행한다. 4. 의미 있는 프로토콜, 응답 모드, 토폴로지, 선택 기능의 조합을 확인한다. 5. 프로젝트에서 요구하는 정적 코드 검사, 서식 검사, 형식 검사를 실행한다. 6. 변경이 공유 동작에 영향을 줄 수 있다면 지원되는 전체 테스트 매트릭스를 실행한다. 테스트 모음을 통과시키기 위한 목적으로 검증 조건을 약화하거나 테스트 범위를 없애거나 실패를 재분류하지 않는다. 외부 인프라가 필요한 테스트는 기본 로컬 테스트 모음과 명확히 분리한다. ## 최종 변경 사항에서 디버그 코드와 동기·비동기 불일치 찾기 완료하기 전에 전체 변경을 살펴보고 다음을 검증한다. - 관련된 파일과 줄만 변경되었다. - 디버그 코드, 의도치 않게 빠진 로직, 관련 없는 형식 변경이 남아 있지 않다. - 명시적인 의도가 없는 한 공개 인터페이스와 오류 동작이 바뀌지 않았다. - 미러 구현과 형식 힌트의 정합성이 유지되었다. - 테스트가 성공 사례, 경계 사례, 실패 경로를 다룬다. - 정적 코드 검사와 필수 테스트 모음이 통과한다. - 문서가 구현된 동작과 일치한다. - 불필요한 의존성, 메모리 할당, 추상화를 도입하지 않았다. 발견한 문제를 모두 수정하고 영향을 받는 검사를 반복한다. 실제 검증 범위를 넘어섰다고 주장하지 말고 변경 내용, 검증 내용, 명시적으로 확인하지 않은 외부 시나리오를 보고한다.