디바이스 자동화 도구의 코드를 고치고 실기기에서 동작 확인하기

## 요청 종류를 먼저 나누고 바꿀 코드만 읽기 먼저 요청을 분류한다. 편집이나 실행을 명시적으로 요청하지 않았다면 정보 제공만을 위한 검토, 분류, 질문은 읽기 전용이다. 코드 변경 요청은 최소한의 구현과 해당 영역에 필요한 검사를 허용한다. 편집 전에 가정을 밝히고 관찰 가능한 성공 기준을 정의한다. 오래 유지되는 도메인 용어, 적용되는 아키텍처 결정, 해당 기능을 소유한 구성이나 계약을 읽는다. 기본적으로 저장소 전체를 읽지 않는다. 범위가 제한된 검색부터 시작한다. - 빠른 텍스트 검색으로 심볼, 명령, 플래그, 오류를 찾는다. - 해당 기능을 소유한 모듈, 공유 헬퍼 하나, 하위 호출자나 어댑터 하나를 읽는다. - 큰 파일에서는 범위가 제한된 구간을 열기 전에 관련 타입이나 함수를 찾는다. - 근거가 필요할 때만 import와 테스트를 따라 바깥으로 추적한다. 작업에서 경계를 명시적으로 넘지 않는 한 변경을 하나의 명령 계열, 플랫폼 접점, 모듈 그룹 안에 한정한다. 두 플랫폼 구현이 모두 존재한다는 이유만으로 둘 다 검사하지 않는다. 범위를 넓혀야 한다면 멈추고 새 경계를 확인한다. 코딩 전에 문서, 도움말, 스키마, 스킬에 미치는 영향을 판단한다. 시간이 지나면 부정확해지는 파일 목록보다 오래 유지되는 단일 사실 출처의 위치를 우선한다. ## 명령의 이름과 옵션을 하나의 레지스트리에 모으기 각 명령에 식별성, 기능, 타임아웃 정책, 배치 정책, 공개 투영을 소유하는 하나의 표준 설명자를 둔다. 데몬이나 서비스 라우팅은 라우트 레지스트리에, 상호작용 경로 보장은 타입이 지정된 매트릭스에, 명령 이름은 단일 카탈로그에 둔다. 핸들러 안에 문자열 집합을 다시 만들지 않는다. 최상위 라우터는 가볍게 유지하고 오케스트레이션만 담당하게 한다. 해당 기능을 소유한 핸들러 계열로 라우팅하며, 진입점에 명령 로직을 쌓지 않는다. 기능 판단은 흩어진 조건문이 아니라 기능의 단일 사실 출처에 둔다. 각 공개 옵션은 그 의미를 이해하는 계층만 통과하게 한다. 1. 공개 플래그와 문법을 정의한다. 2. 해당 명령을 소유한 메타데이터와 스키마에 추가한다. 3. 명령 입력으로 파싱한다. 4. 런타임 실행에 필요할 때만 서비스 요청으로 투영한다. 5. 해당 인터페이스가 옵션을 노출할 때만 타입이 지정된 클라이언트와 정규화기를 확장한다. 6. 공개 계약에서 해당 옵션이 디스패치와 플랫폼 모듈에 속함을 입증한 뒤에만 그 계층까지 전달한다. 7. 아키텍처 진행 모델이나 커버리지 모델에서 모든 공개 옵션을 분류한다. 선택자 파싱, 일치 확인, 해석, 조건자 평가를 중앙화한다. 요소를 대상으로 하는 작업은 안정적인 선택자나 기록된 참조를 받아들이고 선택자 체인을 보존하며, 재생 차이를 사용자 상태를 조용히 다시 쓰는 대신 제안으로 표시해야 한다. ## 빠른 경로와 캐시 경로도 기본 경로와 똑같이 동작하는지 확인하기 경로 경계에서는 보장이 약해진다고 가정한다. 빠른 경로, 위임 경로, 캐시 경로, 플랫폼별 경로를 추가할 때는 동등성을 주장하기 전에 영향을 받는 모든 명령 및 경로 셀을 분류한다. 레지스트리 항목은 의미론적 증거가 아니다. 구현을 읽고 보장의 정의를 충족하는지 확인한다. 오류가 난 뒤에만 위임하는 폴백으로는 성공 경로의 동등성을 입증할 수 없다. 빠른 경로가 공유 경로에서는 거부할 입력을 받아들일 수 있기 때문이다. 실험을 측정하기 전에 각 실험군을 실행할 수 있는지 입증한다. 변경된 분기가 한 번도 실행되지 않았다면 두 차례의 성공 실행은 아무 의미가 없다. 어느 구현이 요청을 처리했는지 보여 주는 데 필요한 경로, 백엔드, 이유 코드, 기타 타입이 지정된 근거를 기록한다. 사람이 읽는 메시지를 파싱하지 말고 구조화된 신호를 사용한다. 이유 코드, 타입이 지정된 세부 정보, 명시적 타임아웃 값을 기준으로 분기하며, 오류 텍스트 감지 로직을 복제하지 않는다. 피할 수 없는 메시지 일치는 결정 지점에 문서화된 기술 부채로 남긴다. 이전 경고를 덮어쓰지 말고 공유 응답 빌더를 통해 경고를 조합한다. 모든 노드나 항목에 같은 바이트를 반복하지 말고 응답 전체 메타데이터를 한 번만 저장한다. 호환 필드를 유지하기 전에 실제로 출시되었는지 확인한다. 출시되지 않은 영역은 깔끔하게 제거할 수 있지만, 출시된 영역에는 마이그레이션과 호환성 처리가 필요하다. ## 파일은 작게, 테스트는 소스 구성에 맞춰 두기 파싱한 입력, 런타임 페이로드, 잡힌 오류, 범용 I/O 같은 신뢰 경계에서만 `unknown`을 사용한다. 한 번 검증한 뒤 도메인 타입이나 전용 파서로 좁히고, 불확실성을 내부 헬퍼와 포매터까지 끌고 가지 않는다. 언어가 누락된 경우를 불가능하게 만들 수 있다면 타입 수준의 완전성 검사를 우선한다. 기계가 읽을 수 있는 주장과 이를 설명하는 코드를 같은 곳에 둔다. 레지스트리 셀은 적용 위치를 가리키는 포인터 옆에, 커버리지 매니페스트는 계약 테스트 옆에, 결정 주석은 그 근거가 되는 분기 지점에 둔다. 각 모듈은 하나의 질문만 담당하게 한다. 실용적인 경계선으로 구현 파일은 대략 300줄을 목표로 하고, 500줄을 넘으면 동작을 추가하기 전에 국소성을 개선하며, 1,000줄을 넘으면 생성 데이터나 픽스처 스냅샷이 아닌 한 아키텍처 부채로 취급한다. 파일이 답하는 도메인 개념에 따라 이름을 짓는다. 배럴 파일은 패키지 경계에서만 사용한다. 내부 배럴 파일은 탐색 단계를 늘린다. 줄 수만 줄이기 위해서가 아니라 개념적 소유권을 개선할 때 심층 모듈을 분리한다. 테스트에서 소스 구조를 그대로 반영한다. 소스 모듈을 분리하면 같은 변경에서 테스트도 분리한다. 큰 인라인 객체를 중복하지 말고 재사용 가능한 픽스처를 이름 있는 인접 픽스처 모듈에 둔다. 비공개 세부 사항을 쉽게 테스트하려는 목적으로 프로덕션 export를 추가하지 않는다. 마무리하기 전에 변경한 코드와 바로 인접한 코드를 다듬는다. 오래된 분기, 중복 테스트, 사용하지 않는 import, 낡은 픽스처, 변경으로 불필요해진 중복을 제거한다. 관련 없는 정리는 피한다. ## 디바이스 세션을 꼭 닫고 로그와 진단을 나눠 남기기 공유 프로세스 추상화를 통해 프로세스 실행을 라우팅한다. 기능이 부족하면 코드베이스 곳곳에서 저수준 프로세스 프리미티브를 import하지 말고 해당 추상화를 확장한다. 수동으로 연 모든 디바이스 세션을 리소스로 취급한다. 세션 이름, 플랫폼, 디바이스 식별자, 상태 디렉터리를 기록하고, 실험이 실패하더라도 마치기 전에 같은 값으로 세션을 닫는다. 이번 검증 실행에 속한 것으로 정확히 식별된 잔존 프로세스만 중지하며, 추측으로 광범위한 프로세스 그룹을 종료해서는 안 된다. 애플리케이션 로그, 러너 출력, 요청 진단을 구분한다. 애플리케이션 로그 캡처는 하나의 백엔드에서 담당한다. 요청 진단은 확정된 세션과 요청 식별자 아래에 저장하고, 최상위 데몬 로그는 세션 해석 전에 발생한 수명 주기와 실패에만 사용한다. 진단 범위, 타이머, 이벤트 전송, 민감 정보 가림, 산출물 경로 생성을 중앙화한다. 진단 서비스가 해당 데이터를 소유할 때는 로그 경로를 직접 만들거나 임의 파일을 추가하지 않는다. 사용자에게 표시되는 실패를 코드, 간결한 메시지, 복구 안내, 진단 식별자, 로그 경로, 타입이 지정된 세부 정보를 포함한 안정적인 페이로드로 정규화한다. 오류를 감쌀 때 해당 필드를 보존한다. 무엇이 실패했는지, 알고 있다면 이유가 무엇인지, 다음 복구 조치는 무엇인지 밝힌다. 선택적 프로브, 캐시 검사, 사전 검사는 기능 계약에서 필수로 정하지 않는 한 최선 노력 방식으로 취급한다. 필수 작업보다 짧은 타임아웃을 부여하고, 실패하거나 사용할 수 없는 형태를 반환하면 기존 경로로 폴백한다. ## 바뀐 부분에 맞춰 돌릴 테스트 고르기 저장소에 영향 검사 플래너가 있다면 먼저 사용한다. 손으로 작성한 목록이 아니라 표준 메타데이터에서 집중 테스트와 남은 게이트를 도출해야 한다. 검사를 변경 영역에 매핑한다. - 타입이 지정된 소스를 변경하면 타입 검사와 포매팅이 필요하다. - 도구 체인이나 컴파일러 구성을 변경하면 도구 게이트와 선언 파일 빌드가 필요하다. - 공유 서비스나 핸들러를 변경하면 집중 단위 테스트 묶음이 필요하다. - 응답 형태나 제공자 경계를 변경하면 제공자 통합 및 커버리지 검사가 필요하다. - 네이티브 러너를 변경하면 네이티브 테스트 산출물을 다시 빌드해야 한다. - 크로스 플랫폼 동작에는 크로스 플랫폼 통합 테스트 스위트가 필요하다. - 문서만 변경하는 작업은 더 구체적인 계약에서 요구할 때만 런타임 테스트가 필요하다. 집중된 근거가 충분하다면 기본적으로 광범위한 통합 테스트를 실행하지 않는다. 반대로 디바이스를 다루는 변경을 단위 테스트만으로 준비 완료라고 판단하지 않는다. 테스트는 동작을 검증해야 한다. 정적 타입이 이미 입증한 것을 어서션으로 확인하지 않는다. 단위 테스트에서 실제 시간을 기다려서는 안 된다. 시간 예산을 주입하거나, 예산에서 주기를 도출하거나, 예산이 올바르게 연결되었는지 확인한다. 적용 게이트에서 분류되지 않은 플래그, 누락된 보장 셀, 커버되지 않은 시나리오, 응답 생성 우회, 규칙 동등성 격차를 발견하면 새 동작을 분류하거나 커버한다. 게이트를 억제하거나 설명 없는 허용 목록 항목을 추가해서는 안 된다. ## 다시 빌드한 뒤 실기기나 시뮬레이터에서 동작 확인하기 수동 검증 전에 런타임이 실제로 사용하는 모든 산출물을 다시 빌드하고, 핫 리로드하지 않는 서비스를 재시작하며, 이전 네이티브 바이너리를 계속 제공할 수 있는 채택된 러너를 무효화하거나 교체한다. 오래된 출력을 대상으로 한 테스트는 제품 근거가 아니라 위음성이다. 어느 백엔드가 실행을 처리했는지 입증한다. 기계가 읽을 수 있는 스냅샷이나 상태 응답을 캡처하고 현재 패키지를 기준으로 백엔드 식별자와 헬퍼 버전을 확인한다. 폴백 동작 자체가 테스트 대상 기능인 경우에만 조용한 폴백을 유효한 근거로 인정한다. 격리된 데몬 상태가 물리적 대상을 분리해 주지는 않으므로 동시 작업 트리에는 서로 다른 디바이스, 시뮬레이터, 에뮬레이터를 사용한다. 테스트 애플리케이션 자체의 설정 가이드를 따른다. 빌드, 개발 서버, 대상 영역 검사를 통해 의도한 버전이 실행 중임을 입증하지 못하면 애플리케이션 설치만으로는 충분하지 않다. 제품 코드를 디버깅하기 전에 환경 노이즈를 분류한다. 경합 실패를 격리 환경과 동일한 부하의 변경되지 않은 기준 버전에서 재현한다. 단독으로는 통과하지만 실패 집합이 계속 달라진다면 경합일 가능성이 크다. 변경 경로에서 안정적으로 나타나는 실패는 회귀를 뒷받침하는 더 강한 근거다. 샌드박스가 필요한 로컬 리스너, 디바이스 브리지, 네이티브 도구를 막는다면 샌드박스 거부를 제품 버그로 진단하지 말고 승인된 권한 상승 경로로 다시 실행한다. 라이브 검증이 계속 막히면 필요한 정확한 디바이스, 권한, 명령, 서비스를 보고하고 잔여 위험을 남긴다. ## 실제 명령 경로를 따라 검토하고 실기기 결과와 함께 보고하기 차이만 보지 말고 변경을 촉발한 이슈와 승인된 아키텍처 결정을 기준으로 검토한다. 명령 영역에서 요청 라우팅을 거쳐 플랫폼 백엔드까지 프로덕션 경로를 추적한다. 라우터를 우회하거나 핵심 접점을 모의하는 테스트는 배포된 동작을 입증하지 못한다. 각 주요 회귀 테스트에서 어떤 이전 구현, 삭제, 되돌리기가 테스트를 실패하게 해야 하는지 확인한다. 버그가 다시 나타나도 테스트가 통과한다면 무의미한 테스트이므로 강화해야 한다. 의도한 리팩터링과 출력 형태, 경고 전파, 오류 세부 정보, 산출물 경로, 재시도 단계, 폴백에서 생기는 숨은 동작 변경을 구분한다. 구현이 다른 변경에 의존한다면 관련 변경과 분기 순서를 확인한다. 외부 공개나 푸시를 하나의 성공 체인 뒤에 두어 포매팅, 타입, 린트, 테스트 명령이 실패한 뒤에는 실행될 수 없게 한다. 커밋과 풀 리퀘스트의 범위를 한정하고, 프로젝트의 관례적인 제목 형식을 사용하며, 작업이 완료된 경우에만 기본적으로 검토 준비 상태로 연다. 사용자에게 보이는 동작, 의미 있는 검증, 실제 디바이스 근거, 실제 절충점을 요약한다. 로컬 단위 테스트 실행만으로 CI가 통과했다고 말하지 않으며, 최신 라이브 근거 없이 플랫폼 변경을 병합 준비 완료라고 말하지 않는다. 문서나 도움말 영향, 변경 범위, 검증하지 못한 경로, 정확한 장애 요인을 밝힌다. 인계 전에 모든 세션을 닫고 검증 중 연 모든 리소스를 확인한다. 정리하지 못한 세션, 프로세스, 상태 디렉터리, 산출물이 있다면 보고한다.