백엔드와 프런트엔드가 함께 있는 다중 모듈 저장소를 빌드를 깨지 않고 고치기

## 저장소 루트에서 시작해 관련된 모든 모듈의 규칙을 읽기 작업이 하나의 하위 프로젝트에만 한정된 것처럼 보여도 저장소 루트에서 프로젝트를 열고 전체를 조율한다. 루트 수준 에이전트 지침을 기준으로 삼고, 중첩된 지침 파일은 로컬 규칙을 추가하는 것으로 취급한다. 편집하기 전에 작업이 영향을 줄 수 있는 모든 모듈을 식별하고 각 모듈의 지침 파일을 불러온다. 모듈을 가로지르는 작업은 처음 제안한 변경과 가장 가까운 파일의 규칙만이 아니라 관련된 모든 로컬 규칙을 따라야 한다. ## 모듈마다 맡은 일을 정리하고 백엔드와 프런트엔드를 함께 고치기 주요 영역에 대한 책임 지도를 유지한다. - 공개 API 모듈은 확장 지점, 서비스 계약, 보안 추상화를 담당한다. - 백엔드 애플리케이션은 비즈니스 로직, 리액티브 서비스, 라우팅, 보안, 마이그레이션, 패키징을 담당한다. - 프런트엔드 작업 공간은 관리 및 사용자 인터페이스, 공유 패키지, 생성된 API 클라이언트를 담당한다. - 의존성 플랫폼 모듈은 애플리케이션과 하위 확장 기능에 적용되는 제약을 담당한다. - 개발자 문서는 사람이 읽는 아키텍처와 작업 흐름 안내를 담당한다. 계약, 페이로드, 인증, 탐색 또는 사용자 경험이 경계를 가로지르면 백엔드와 프런트엔드 변경을 하나의 풀스택 작업으로 취급한다. 공개 계약, 백엔드 핸들러, 프런트엔드 사용 방식을 같은 변경 안에서 동기화한다. ## API가 바뀌면 클라이언트를 다시 생성하고 손으로 고치지 않기 공개 요청 또는 응답 유형, 경로, 라우터 계약, API 스키마 주석, 생성된 스키마, 인증 또는 세션 동작이 변경될 때마다 프런트엔드에 미치는 영향을 평가한다. 원본 계약을 갱신한 뒤 저장소에서 정한 명령으로 API 설명과 클라이언트를 다시 생성한다. 생성된 클라이언트 파일을 절대 직접 편집하지 않는다. 계약이나 생성기 입력을 수정하고 출력을 다시 생성한 다음 그 결과로 생긴 차이를 검토한다. 생성된 출력을 파괴적으로 변경하거나 하위 소비자가 의존할 수 있는 공개 API를 변경하기 전에는 확인을 요청한다. ## 프런트엔드 결과물이 백엔드 빌드에 들어가는 과정을 확인하기 프런트엔드 출력이 배포 가능한 백엔드 산출물에 어떻게 들어가는지 이해한다. 백엔드 빌드가 컴파일된 인터페이스를 애플리케이션 리소스에 포함한다면, 모든 프런트엔드 출력 변경은 백엔드 패키징 경로에도 영향을 주므로 해당 경로에서 검증해야 한다. 백엔드 컴파일, 인터페이스 패키징, 테스트가 같은 의존 관계 그래프를 사용하도록 스택 간 조율 작업을 루트에서 실행한다. 빌드 시 다운로드, 사전 설정된 확장 기능, 복사된 배포 산출물을 부수적인 파일이 아니라 빌드 계약의 일부로 취급한다. ## 버전과 포맷 규칙은 정해진 파일에서 읽기 의존성 버전, 프로젝트 버전, 언어 릴리스, 플러그인 버전, 프런트엔드 의존성은 각각 지정된 카탈로그, 속성 파일, 빌드 스크립트, 패키지 매니페스트에서 읽는다. 이미 권위 있는 원본이 있는 버전을 하드코딩하지 않는다. 들여쓰기, 줄 너비, 지원 구문의 기준으로 설정된 포매터와 린터를 사용한다. 지정된 경우 `release 21`을 포함하여 선언된 언어 릴리스를 준수하고, 루트 수준 서식 규칙은 빌드가 예상하는 범위에 유지한다. ## 리액티브 코드에 블로킹 I/O를 넣지 않고 데이터베이스 위치를 지키기 다른 곳에서 가상 스레드를 활성화했더라도 리액티브 실행 경로에 블로킹 입력이나 출력을 도입하지 않는다. 프로젝트가 선택한 마이그레이션 엔진을 다른 엔진으로 몰래 대체하지 말고, 방언별 마이그레이션은 지정된 데이터베이스 디렉터리에 유지한다. 확장 스키마, 런타임 JSON 데이터, 프로필별 구성, 재정의 가능한 작업 디렉터리는 각각의 소유 위치에 유지한다. 파일 기반 임베디드 데이터베이스에는 절대 파일 경로를 사용한다. 상대 URI는 애플리케이션 모듈 아래에 불필요한 디렉터리를 만들고 실제로 열리는 데이터베이스를 바꿀 수 있다. ## 바뀐 부분에 맞춰 테스트를 고르기 실제 범위에 따라 검사를 선택한다. - 백엔드만 변경한 경우 저장소 포매팅과 영향을 받는 백엔드 테스트가 필요하다. - 프런트엔드만 변경한 경우 프런트엔드 포매팅, 유형 검사, 린트, 관련 단위 테스트가 필요하다. - 계약을 변경한 경우 API 설명 생성, 클라이언트 재생성, 프런트엔드 검증, 백엔드 테스트가 필요하다. - 스택을 가로지르는 변경은 계약 양쪽뿐 아니라 최종 패키징 산출물도 검증해야 한다. 먼저 범위를 좁힌 검사를 실행한 뒤 필요에 따라 범위를 넓힌다. 변경된 모든 동작에 대해 테스트를 추가하거나 갱신하고, 필수 지속적 통합 검사가 계속 실패하는 동안에는 작업을 제출하지 않는다. ## 푸시 전에 올바른 업스트림을 확인하고 작업 파일만 스테이징하기 푸시하거나 검토를 열기 전에 현재 저장소를 식별하고 원격 저장소를 확인한다. 해당 체크아웃에 맞는 올바른 업스트림을 대상으로 삼는다. 관련 공개 또는 독점 저장소의 업스트림을 잘못 사용하면 되돌리는 데 큰 비용이 들 수 있다. 의도한 업스트림 기준에서 작업을 시작하고 `upgrade/gradle-X`, `feat/name`, `fix/name`, `improvement/name`과 같은 저장소 브랜치 규칙을 따른다. 작업에 속한 파일만 스테이징한다. 빌드 출력이나 데이터베이스 산출물이 존재할 수 있을 때는 `git add -A`나 `git add .`을 절대 사용하지 않는다. 오래된 작업 트리가 기본 브랜치를 잠근 경우 작업 트리 목록을 확인하고 오래된 것으로 확인된 항목만 명시적으로 제거한다. 정확한 잠금 소유자를 식별하는 대신 광범위한 정리를 사용하지 않는다. ## 마이그레이션과 새 의존성은 먼저 묻고 비밀 정보는 커밋하지 않기 세 가지 제어 수준을 사용한다. - 항상 루트에서 작업하고, 적용 가능한 모든 중첩 규칙을 불러오며, 파일을 명시적으로 스테이징하고, 파생 클라이언트를 원본에서 다시 생성하며, 변경된 동작에 대한 테스트를 추가하고, 검토 설명에 AI 지원을 받은 자료임을 명시한다. - 공개 API 변경, 빌드 또는 패키지 의존성 추가, 데이터베이스 마이그레이션 작성, 보안 구성이나 지속적 통합 작업 흐름 변경, 생성 출력의 파괴적 교체를 수행하기 전에는 확인을 요청한다. - 비밀 정보를 커밋하거나, 권위 있는 버전을 하드코딩하거나, 리액티브 경로에 블로킹 작업을 추가하거나, 생성된 클라이언트를 직접 편집하거나, 올바른 업스트림을 확인하지 않고 검토를 열어서는 절대 안 된다. 구현 자체가 단순하더라도 이러한 경계는 적용된다. 구현이 쉽다고 해서 호환성, 보안, 데이터 또는 릴리스 위험이 줄어드는 것은 아니다. ## 데이터베이스 상대 경로 같은 알려진 빌드 함정을 피하기 알려진 도구별 불변 조건을 유지한다. 1. 파일 기반 임베디드 데이터베이스 위치는 절대 파일 시스템 경로로 해석되어야 한다. 상대 경로 형식은 불필요한 모듈 디렉터리를 만들고 애플리케이션이 잘못된 데이터베이스를 열게 할 수 있다. 2. 빌드 래퍼 업그레이드에는 버전을 지정한 래퍼 명령과 두 번째 래퍼 생성 명령이 모두 필요하다. 첫 번째 명령만 실행하면 생성된 래퍼 파일의 일관성이 깨진다. 3. 저장소 전체에 적용되는 기타 포매팅 구성은 루트에 유지한다. 이를 애플리케이션 하위 모듈로 옮기면 호환되지 않는 포매터 작업이 결합되고 빌드 도구 버전 `9.x`에서 암시적 의존성 검증 오류가 발생한다. 이러한 함정을 권위 있는 빌드 안내 가까이에 기록하고 영향을 받는 구성을 변경할 때마다 검증한다.