로컬 백그라운드 서비스(데몬) 위에서 도는 앱의 코드를 작게 고친다

## 코드를 바꾸기 전에 설계 문서를 읽고 폴더마다 맡은 일을 파악한다 변경은 작게 유지하고, 저장소가 현재 지향하는 아키텍처에 맞추며, 대체 중인 예전 구현에서 물려받은 동작보다 문서화된 데몬/API 경계를 우선하라. 파일 이름이 아니라 역할을 기준으로 구조를 익혀라. - 백엔드에는 명령줄 클라이언트, 루프백 HTTP 데몬, 서비스, 임베디드 데이터베이스 저장소, 라이프사이클/리퍼 로직, 런타임 및 워크스페이스 어댑터, 그리고 그것들의 테스트가 들어 있다. - 데스크톱 또는 웹 프런트엔드는 생성된 타입 지정 클라이언트를 통해 데몬에 연결된 얇은 감독자이자 UI 표면이다. 데몬 로직을 그쪽으로 옮기지 마라. - 문서 디렉터리에는 현재의 아키텍처 및 상태 노트가 들어 있다. 라이프사이클, 클라이언트, 에이전트, 저장소, 데몬 동작을 변경하기 전에 그것들을 읽어라. - 별도의 테스트 디렉터리에는 신규 설치 컨테이너 점검을 포함한 외부 스모크 및 엔드투엔드 자산이 들어 있다. - CI 워크플로 정의는 무엇이 통과해야 하는지에 대한 기준이다. 가능하면 그 명령들을 로컬에서 그대로 재현하라. 사소하지 않은 변경 전에는 다음 순서로 읽어라. 퀵스타트 README, 문서 색인, 아키텍처 문서(멘탈 모델, 패키지 구조, 라이프사이클/세션/서비스 경계, 그리고 하중을 지탱하는 규칙), 상태 문서(오늘 메인 브랜치에 실제로 반영된 것 대 아직 진행 중인 것), 그리고 클라이언트 문서(그것이 의도하는 형태). 저장소가 다른 에이전트 도구용 호환성 포인터 파일도 함께 담고 있다면, 그것들은 별개의 규칙 집합이 아니라 하나의 정본 가이드로 향하는 리다이렉트로 취급하라. 무작정 검색하지 말고 책임을 기준으로 진입점을 찾아라. 명령 구현, HTTP 컨트롤러와 DTO, 서비스 읽기/쓰기 경계, 도메인 어휘, 포트 계약, 데이터베이스 쿼리와 마이그레이션, 그리고 생성된 데이터베이스 코드는 각각 자기 패키지에 들어 있다. 새로운 스타일을 도입하기 전에 인근의 명령 및 테스트 패턴을 따르라. ## 프로젝트 자체 검사를 돌리고, 화면 변경은 실제로 띄워서 본다 임시로 만들어 낸 명령 대신 저장소 자체의 통합 명령을 사용하라. 저장소 루트에서 이 명령들은 보통 다음을 포괄한다. 린트(백엔드 테스트와 버전이 고정된 린터), 프런트엔드 타입 검사, 쿼리와 스키마로부터 데이터베이스 접근 코드 재생성, API 명세와 프런트엔드 타입 재생성, 그리고 CI 정의를 검증하는 로컬 워크플로 러너(컨테이너 소켓이 필요할 수 있다). 반복 작업 중에는 컴포넌트 수준 검사도 직접 실행할 가치가 있다. 백엔드는 빌드, 테스트, 레이스 검출을 켠 테스트, 정적 분석(vet), 서비스 기동이고, 프런트엔드는 타입 검사와 빌드다. 변경이 UI에 드러나는 경우에는 프로젝트의 미리보기 명령을 사용해 세션 안에서 실제로 렌더링해 보고 결과를 눈으로 확인하라. 변경이 어떻게 보일지 말로만 설명하지 마라. ## 설치 안내는 자동 업데이트되는 데스크톱 앱 하나로만 한다 프로젝트에 설치 경로가 둘 이상 있을 때 정본은 하나뿐이며, 안내는 그쪽을 가리켜야 한다. - 릴리스를 통해 배포되는 자동 업데이트 데스크톱 빌드가 정본 설치 경로다. 사용자를 먼저 그쪽으로 안내하라. - 레거시 패키지 관리자 채널은 더 이상 권장되지 않으면서도 여전히 동작할 수 있다. 최종 버전이 게시되어 패키지가 동결되었다면 그것은 더 이상 업데이트를 받지 않는다. 그것은 이미 해당 명령을 PATH에 가지고 있는 사용자를 위한 진입로로만 남으며, 그 명령을 실행하면 정본 빌드를 내려받아 실행한다. - 동결된 레거시 채널을 제품 설치의 의도된 방식으로 취급하는 기능, 문서, 흐름을 추가하지 마라. ## 과제에 필요한 것만 바꾸고, 지금의 코드 구분을 따른다 - 모든 변경을 과제와 직접 연결된 상태로 유지하라. 과제가 명시적으로 요구하지 않는 한 지나가는 김에 하는 정리, 광범위한 이름 변경, 포매팅 잡음, 추측성 추상화, 아키텍처 리팩터링을 피하라. - 기존 패키지 경계를 따르라. 클라이언트 코드는 공유 클라이언트 헬퍼를 통해 데몬 HTTP 라우트를 호출한다. 클라이언트 코드가 데이터베이스를 직접 열거나, 런타임을 직접 띄우거나, 어댑터를 직접 호출해서는 안 된다. - 각 명령은 해당하는 명령 파일 안에 두고, 인접한 명령 테스트의 방식대로 테이블 테스트를 작성하라. - 서버 컨트롤러 패키지를 클라이언트 코드로 임포트하는 대신, 그 의존성이 이미 해당 패키지에 확립되어 있지 않은 한 요청 및 응답 DTO를 클라이언트 쪽에 그대로 미러링하라. - 사용 오류는 전용 사용 오류 타입을 통해 반환하여, 클라이언트 오용은 자체 상태 코드(예: 2)로 종료되고 런타임 및 데몬 실패는 일반 실패 코드(예: 1)로 종료되게 하라. - 데몬 오류를 표면화할 때 평범한 문자열로 뭉개지 말고 API 오류 봉투와 요청 ID를 보존하라. - I/O나 블로킹 작업을 수행하는 함수에는 취소/데드라인 컨텍스트를 첫 번째 인자로 전달하라. - 일회성 사용 사례를 위해 추상화를 추가하지 마라. 헬퍼는 실제 호출 지점들 사이의 중복을 제거할 때만 도입하라. - 테스트는 사용자에게 보이는 동작과 변경 대상 경계를 다뤄야 한다. 즉 정상 경로, 검증과 인자 누락, 데몬 오류 봉투, 그리고 파괴적 작업의 확인 경로가 있다면 그것까지 포함한다. ## 데몬의 네트워크 입구를 바꾸거나 늘리지 않는다 - 데몬의 기본 리스너는 루프백 주소에 바인딩된 상태로, 그리고 인증 없는 상태로 유지된다. 그 바인드 호스트를 바꾸지 말고 거기에 인증을 추가하지도 마라. - 데몬은 로컬 네트워크 접근을 위해 모든 인터페이스에 바인딩하는, 옵트인 방식의 두 번째 리스너를 실행할 수 있다. 다만 명시적으로 활성화된 동안에만, 베어러 비밀번호 인증 미들웨어 뒤에서만, 그리고 애플리케이션 API만 제공하는 형태로만 가능하다. 그 리스너는 종료, 텔레메트리, 원격 제어처럼 루프백으로 제한된 제어 라우트를 절대 제공해서는 안 된다. - 그런 리스너가 평문이고 신뢰할 수 있는 가정 네트워크만을 대상으로 한 경우, 그것은 아키텍처 결정 기록에 남겨진 의도적이고 문서화된 결정이다. 그것을 건드리기 전에 그 기록을 읽어라. - 그 밖의 어떤 네트워크 노출 바인드도 추가하지 마라. - 명령줄 클라이언트는 얇은 클라이언트로 유지된다. 데몬의 HTTP 라우트를 우회하는 예전의 인프로세스 동작을 이식하지 마라. ## 저장된 데이터를 지키고, 자동 생성된 데이터베이스 코드는 손으로 고치지 않는다 - 파생된 상태나 표시용 상태를 저장하지 마라. 상태는 서비스가 읽는 시점에 내구성 있는 사실(활동 상태, 종료 플래그, 풀 리퀘스트/체크/코멘트 관련 사실)로부터 도출하라. - 실패했거나 결과를 알 수 없는 런타임 프로브를 세션이 죽었다는 증거로 취급하지 마라. - 커밋되지 않은 변경이 남아 있는, 등록된 워크트리를 강제 삭제하지 마라. - 이미 병합된 마이그레이션을 수정하지 마라. 대신 새 마이그레이션을 추가하라. - 생성된 데이터베이스 코드를 손으로 편집하지 마라. 쿼리나 마이그레이션을 바꾸고 생성기를 다시 실행하라. - 변경 이벤트는 데이터베이스 트리거에서 변경 로그로 흘러간다. 아키텍처가 명시적으로 바뀌지 않는 한, 스토어 메서드에서 변경을 수동으로 내보내는 병렬 경로를 추가하지 마라. - 생성된 API 산출물과 손으로 작성한 DTO 사이의 드리프트를 주시하라. 컨트롤러 응답 형태는 하나의 DTO 파일에 들어 있으며, 테스트가 클라이언트와 HTTP 계층 사이의 와이어 호환성을 단언할 수 있다. - 해당 패키지에 이미 통합 테스트나 엔드투엔드 패턴이 있는 경우가 아니라면 테스트에 네트워크 호출을 추가하지 마라. 인프로세스 테스트 서버, 페이크, 주입된 의존성을 우선하라. - 로컬 실행 상태, 데몬 데이터, 임시 워크트리, 빌드 산출물, 자격 증명을 커밋하지 마라. - 모든 애플리케이션 상태는 문서화된 환경 변수로 재정의할 수 있는 단일 전용 상태 디렉터리 아래에 두어라. 데몬 데이터 디렉터리, 실행 중 프로세스 파일, 워크트리, 그리고 데스크톱 셸의 사용자 데이터(브라우저 캐시, 쿠키, 로컬 및 세션 스토리지, 크래시 덤프)가 모두 그 아래로 해석되어야 한다. 운영체제의 기본 애플리케이션 데이터 위치에서 읽거나 그곳에 쓰는 일을 절대 하지 마라. 데스크톱 진입점은 셸의 사용자 데이터 경로를 그 디렉터리로 고정한다. 그 재정의를 제거하지 말고 기본 경로에 의존하지도 마라. ## API는 손으로 쓰는 파일에서 바꾸고, 설명 문서를 다시 생성한다 데몬 API는 코드 우선이다. OpenAPI 명세와 프런트엔드 타입은 생성된 산출물이므로, 출력물을 편집하지 말고 소스를 편집한 뒤 재생성하라. - 요청 및 응답 형태를 정의하는 DTO 파일을 편집하라. - 명세 빌더의 오퍼레이션 레지스트리를 편집하고, 새로 이름 붙인 타입이 있다면 스키마 이름 항목을 추가하라. - 저장소의 통합 API 명령으로 재생성하라. 이 명령은 명세 생성과 타입 생성을 순서대로 실행한다. - 서버 HTTP 패키지의 테스트로 검증하라. 그 테스트들은 명세 드리프트와 라우트/명세 일치를 다룬다. 생성된 프런트엔드 타입은 다루지 않으며, 그것은 별도의 CI 드리프트 작업이 검사한다. - 생성된 명세와 생성된 프런트엔드 타입을 소스 변경과 함께 커밋하라. CI는 둘 다 재생성하며, 커밋된 버전이 오래되었으면 실패한다. - 손으로 미러링한 클라이언트 DTO는 의도적인 수동 경계로 남으며 생성되지 않는다. ## 변경 요청(풀 리퀘스트)은 과제마다 하나로 한다 - 기존 풀 리퀘스트를 명시적으로 이어가는 경우가 아니라면 메인 브랜치에서 분기하라. - 풀 리퀘스트 하나당 이슈 하나를 유지하라. 별개의 작업을 요청받았다면 별도의 브랜치와 풀 리퀘스트를 만들어라. - feat, fix, docs, test, chore 같은 컨벤셔널 커밋 메시지 접두사를 사용하라. - 의도적으로 빠뜨린 부분은 풀 리퀘스트 본문에 설명하라. 특히 이전 구현이 현재 재작성판의 도메인보다 더 많은 동작을 지원했던 경우에 그렇게 하라. - 가장 범위가 좁은 관련 테스트를 먼저 실행하고, 그다음에 건드린 영역에 해당하는 저장소 및 CI 명령을 실행하라.