풀스택 저장소를 그 저장소의 명령과 테스트대로 고치기

## 먼저 저장소 문서를 읽고 브랜치와 풀 리퀘스트로 진행하기 변경을 계획하기 전에 저장소 수준의 지침, 하위 시스템 문서, 패키지 매니페스트, 인접한 구현을 읽으세요. 프런트엔드, API, SDK, CLI, 데이터베이스, 컨테이너, 문서를 비롯해 영향을 받는 모든 영역을 파악하세요. 직접 개발할 때는 보호된 기본 브랜치를 읽기 전용으로 취급하세요. 용도를 잘 설명하는 이름의 브랜치를 만들고, 의미 있는 커밋을 작성하고, 검토를 위한 풀 리퀘스트를 여세요. 커밋을 수정해 공유 기록을 다시 작성하지 말고, 워크플로가 해당 결정을 검토자에게 맡기는 경우 자신의 풀 리퀘스트를 직접 병합하지 마세요. 브랜치는 요청된 동작에만 집중하세요. 관련 없는 정리 작업은 분리하고, 작업에서 의도적인 변경을 요구하지 않는 한 기존 패턴을 유지하세요. ## 저장소의 명령과 고정된 런타임 버전 사용하기 문서화된 개발, 포매팅, 린팅, 테스트, 마이그레이션, 시작 명령을 실행하기 전에 먼저 확인하세요. 저장소 루트 전체에 적용되는 도구로 대체하지 말고 영향받는 패키지가 제공하는 명령을 사용하세요. 고정된 런타임 버전과 기존 환경을 준수하세요. 더 새로운 런타임 주 버전이 자동으로 지원되는 것은 아닙니다. 종속성이 없을 때만 설치하세요. 작업이나 관련 검증에 필요하지 않다면 전체 애플리케이션 스택, 컨테이너 또는 장시간 실행되는 서버를 시작하지 마세요. 변경된 파일에 문서화된 모드로 포매터와 린터를 실행하세요. 지원되는 단일 테스트 선택기에서 시작한 다음 직접 영향을 받는 테스트 스위트로만 확장하세요. 하위 시스템이 소스 트리 대신 설치된 SDK 패키지를 가져오는 경우, 해당 SDK를 편집한 뒤 다시 설치하고 이를 사용하는 프로세스를 다시 시작하세요. 결합된 개발 프로세스를 시작하기 전에 필요한 포트와 전제 조건을 확인하세요. ## 화면, API, 서비스, 마이그레이션의 역할을 나눈 채로 고치기 편집하기 전에 책임을 구분하세요. - 사용자 인터페이스는 표시와 클라이언트 상태를 담당합니다. - API는 요청 검증과 전송 관련 사항을 담당합니다. - 서비스 모듈은 비즈니스 로직을 담당합니다. - SDK 및 CLI 패키지는 각자의 공개 계약을 담당합니다. - 마이그레이션은 데이터베이스의 발전을 담당합니다. 새 패턴을 도입하기 전에 변경할 하위 시스템의 문서를 읽고 유사한 기존 파일을 살펴보세요. 변경이 여러 계층에 걸치는 경우 작은 단계로 진행하세요. 타입 또는 스키마를 정의하고, 서비스 로직을 구현하고, API 계약을 노출하고, 클라이언트를 업데이트한 다음 인터페이스를 구축하세요. 종속성은 이를 사용하는 패키지에 설치하세요. 워크스페이스 패키지를 추가할 때는 종속성 설치 전에 패키지 메타데이터를 복사하는 모든 프로덕션 및 로컬 컨테이너 빌드 매니페스트를 업데이트하세요. ## TypeScript, Python, 데이터베이스 규칙 지키기 엄격한 TypeScript 타입을 사용하고, 범위가 제한되지 않은 타입을 피하고, 컴포넌트와 API 계약을 명확히 정의하고, 저장소에 확립된 컴포넌트 및 상태 관리 패턴을 따르세요. 프로퍼티를 여러 계층에 걸쳐 전달하는 방식보다 함수형 컴포넌트와 명시적인 상태 액션을 선호하세요. Python 코드에서는 모든 함수 경계에 타입 힌트를 제공하고, 직렬화에 검증 모델을 사용하며, 비즈니스 로직을 전송 라우터가 아니라 서비스에 두세요. 라우터는 요청을 검증하고, 서비스를 호출하고, 응답의 형태를 구성해야 합니다. 외래 키 금지를 포함하여 기존 테이블 및 마이그레이션 규칙을 따르세요. 지원되는 모든 엔진에서 데이터베이스 작업이 이식 가능하도록 유지하세요. 타임스탬프 필드에는 현지 시간, 더 이상 권장되지 않는 API 또는 직접 만든 변환 대신 저장소의 UTC 도우미를 사용하세요. 파일 시스템 저장소와 데이터베이스 저장소 중 무엇을 사용할지에 관한 저장소의 결정을 존중하세요. 단지 편리하다는 이유로 동기화된 클러스터 데이터를 데이터베이스로 옮기지 마세요. ## 동작을 담당하는 계층과 그 테스트 묶음에서 테스트하기 각 하위 시스템에 실제로 구성된 테스트 시스템을 사용하세요. 프런트엔드에 단위 테스트 프레임워크가 없다면 지원되지 않는 실행기를 도입하지 말고 지정된 엔드투엔드 스위트로 동작을 검증하세요. 백엔드 단위 테스트와 서비스 테스트는 기존 트리에 배치하고, CLI 소스를 변경한 후에는 CLI 스위트를 실행하세요. 외부 저장소, 컴퓨팅 제공업체, 파일 시스템 상호작용을 모의 처리하여 테스트가 빠르고 결정론적으로 유지되게 하세요. 전체 API 스택이 필요하지 않은 비즈니스 규칙에는 직접적인 서비스 테스트를 선호하세요. 먼저 하나의 집중된 테스트를 실행한 다음 관련 하위 시스템 스위트를 실행하세요. 기존 데이터가 있어도 반복 실행이 안전하도록 만들고, 안정적인 선택기를 사용하며, 대기열에 들어간 작업이나 상태 전환에는 현실적인 시간 제한을 허용하세요. 명령 이름만으로 성공했다고 주장하지 마세요. 의도한 테스트 파일이 발견되었는지, 그리고 결과가 변경된 동작을 실제로 실행하는지 확인하세요. ## 바꾼 화면을 브라우저로 확인하고 로그인이 필요한 API 시험하기 시각적으로 검사할 때는 저장소에서 승인한 대화형 브라우저 도구를 사용하세요. 자동화된 엔드투엔드 스크립트는 유지 관리되는 테스트 스위트나 명시적인 요청에만 사용하세요. 필요한 테스트 애플리케이션만 시작하고, 변경된 페이지와 직접 관련된 페이지로 이동하고, 증거를 수집하고, 눈에 보이는 회귀를 수정하세요. 역할, 정확한 텍스트, 플레이스홀더 선택기를 선호하세요. 깨끗한 데이터베이스를 전제로 하지 말고 반복되는 테스트 데이터를 처리하세요. 터미널 에뮬레이터가 렌더링한 콘텐츠는 DOM에 존재하지 않을 수 있으므로, 필요한 경우 기반 API를 통해 확인하세요. 인증된 API 검사에는 문서화된 테스트 ID와 인증 흐름을 사용하세요. 필요한 계정 또는 테넌트 범위 헤더를 제공하고, 보호된 엔드포인트와 보호되지 않은 엔드포인트를 구분하며, 재사용 가능한 자격 증명을 소스, 로그 또는 결과 문서에 절대 넣지 마세요. ## 종속성을 신중하게 추가하고 로그에 비밀번호 남기지 않기 종속성을 추가하기 전에 패키지 매니페스트를 확인하고 저장소의 설치 워크플로를 사용하세요. 프로젝트에서 의존하는 경우 커밋 전 포매팅 및 린팅 훅을 활성 상태로 유지하세요. 종속성 오버라이드는 영구적인 장식이 아니라 임시 보안 통제로 취급하세요. 상위 패키지를 업그레이드할 때는 오버라이드를 제거할 수 있는지 테스트하고, 관련 취약점 검사를 실행하고, 결정된 종속성이 여전히 안전하지 않다면 오버라이드를 유지하세요. 통합을 테스트하는 동안 자격 증명의 노출 범위를 넓히지 마세요. 외부 제공업체의 실제 동작이 테스트 대상이 아니라면 이를 모의 처리하고, 로그에 토큰, 비밀번호, 개인 식별자가 포함되지 않도록 하세요. ## 마치기 전에 변경 차이를 확인하고 실행한 확인 보고하기 계획하기 전에 읽고, 일관성을 갖춘 가장 작은 구현을 만들고, 범위를 확장하기 전에 영향을 받는 각 경계를 검증하세요. 규모가 큰 변경에서는 백엔드, API, 클라이언트, 인터페이스 작업을 하나의 불투명한 단계에 뒤섞지 말고 순서를 명시적이고 검토 가능하게 유지하세요. 완료를 보고하기 전에 diff를 검토하고, 변경된 영역에 필요한 관련 포매터, 린터, 타입 검사, 테스트, 마이그레이션 검사, 시각적 검증을 실행하세요. 단지 그럴듯해 보이기 위해 전체 빌드나 관련 없는 스위트를 추가하지 마세요. 무엇을 변경했는지, 어떤 검사를 실행했는지, 더 광범위한 검사 중 무엇을 범위 밖에 두었는지, 잔여 위험은 무엇인지 보고하세요. 완료하려면 단지 편집에 성공했다는 사실이 아니라 변경된 동작에서 얻은 증거가 필요합니다.