풀스택 TypeScript 모노레포를 고치고, LLM 기능은 의미로 테스트한다

## CI와 같은 패키지 단위 명령과 검사만 실행한다 무엇이든 실행하기 전에 리포지토리에 문서화된 개발, 빌드, 린트, 포맷, 테스트, 통합 테스트, 평가 명령을 확인하십시오. 루트 전체에 적용되는 도구로 대체하지 말고 영향을 받는 워크스페이스의 패키지 전용 명령을 사용하십시오. - 단일 테스트는 지원되는 경로나 이름 필터로 실행하십시오. - AI 평가는 리포지토리 루트에서 AI 패키지 전용 평가 명령으로 실행하십시오. - 애플리케이션의 CI 기준에 맞는 빌드 또는 타입 검사를 사용하십시오. 관련 없는 모노레포 기술 부채를 드러내는 지원되지 않는 루트 전체 타입 검사는 실행하지 마십시오. - 워크스페이스의 종속성이 아직 설치되지 않은 경우에만 테스트나 빌드 전에 종속성을 설치하십시오. - 작업에서 명시적으로 요청하지 않았다면 개발 서버나 전체 빌드를 시작하지 마십시오. 검증은 변경된 패키지 및 CI에서 사용하는 검사와 일치해야 합니다. ## 코드가 어떻게 쓰였는지가 아니라 무엇을 하는지 테스트한다 테스트를 만들거나 변경하기 전에 리포지토리의 테스트 지침을 검토하십시오. 핵심 버그 수정에는 실용적인 경우 레드-그린-리팩터 방식을 사용하십시오. 먼저 실패를 재현하고, 그다음 가장 작은 수정 사항을 적용한 뒤, 동작을 바꾸지 않는 범위에서 구조를 개선하십시오. 단위 테스트는 소스 파일과 같은 위치에 두십시오. 통합, 엔드투엔드, AI 평가 테스트는 각각 지정된 테스트 디렉터리 트리에 배치하십시오. 테스트가 로거 경계 자체를 대상으로 하지 않는 한 실제 로깅 구현을 사용하십시오. 의미 있는 동작 회귀를 포착하는 테스트를 우선하십시오. 비공개 구현 세부 사항을 되풀이할 뿐인 가치 낮은 어설션은 피하십시오. 프롬프트나 모델 동작을 변경할 때는 일반 코드 테스트와 함께 의미 기반 평가 또는 구조화된 계약 테스트를 마련해야 합니다. ## 종속성은 그것을 쓰는 워크스페이스에 설치한다 종속성은 모노레포 루트가 아니라 이를 사용하는 워크스페이스에 설치하십시오. 새 워크스페이스 패키지를 추가할 때는 종속성을 설치하기 전에 패키지 메타데이터를 복사하는 모든 프로덕션 및 로컬 컨테이너 빌드 매니페스트를 업데이트하십시오. 환경 변수는 예제 환경 파일, 런타임 검증 모듈, 모노레포 빌드 구성 간에 동기화하십시오. 브라우저 코드에 노출되는 변수에는 리포지토리에서 정한 공개 변수 접두사를 붙이십시오. 버전에 민감하거나 동작이 불분명한 프레임워크의 코드를 변경하기 전에 설치된 종속성에 포함된 문서를 읽으십시오. 기억이나 설치된 다른 버전의 문서에 의존하지 마십시오. ## 정의한 파일에서 직접 임포트하고 타입은 스키마에서 추론한다 엄격한 null 검사를 사용하고 인터페이스를 중복 정의하는 대신 검증 스키마에서 TypeScript 타입을 추론하십시오. 정의된 파일 안에서만 사용하는 타입은 내보내지 마십시오. - 모든 임포트는 파일 맨 위에 두고, 파일 중간에 동적 임포트를 추가하지 마십시오. - 재내보내기 체인이나 배럴 파일을 만들지 말고 원본 소스에서 직접 임포트하십시오. - 유틸리티 라이브러리 전체가 아니라 개별 유틸리티 함수를 임포트하십시오. - 내부 애플리케이션 임포트에는 구성된 프로젝트 루트 별칭을 사용하십시오. - 도우미 함수는 파일 맨 아래에 배치하십시오. - API 라우트 파일 하나에는 리소스 하나만 두십시오. 소유 관계를 직접적으로 유지하면 종속성, 트리 셰이킹, 변경 영향을 더 쉽게 이해할 수 있습니다. ## 코드가 더 명확해질 때만 보조 함수를 뽑아낸다 기본적으로 로직은 사용 위치에 인라인으로 작성하고 같은 곳에 배치하십시오. 작게 중복된 표현식은 성급하게 만든 도우미보다 명확한 경우가 많습니다. 매개변수 이름만 바꿔 전달하는 함수는 추출하지 마십시오. 도우미가 의미 있는 도메인 개념을 이름으로 드러내거나, 주변 제어 흐름을 더 읽기 쉽게 만들거나, 정확성에 민감한 동작을 여러 흐름에서 일관되게 유지할 때 추출하십시오. 여러 복사본을 동기화하지 않으면 버그가 발생하는 상당한 중복 로직은 일찍 중앙화하십시오. 크거나 중첩된 삼항 연산자는 피하십시오. 직관적인 제어 흐름, 목적이 분명한 도우미 또는 조회 테이블을 사용하십시오. 자명한 코드가 무엇을 하는지 설명하지 말고, 결정이 존재하는 이유를 주석으로 남기십시오. 가장 단순하고 읽기 쉬운 변경을 우선하십시오. 요구 사항에서 필요로 할 때만 하위 호환성을 유지하십시오. 그렇지 않으면 사용되지 않는 마이그레이션 경로를 겹겹이 추가하지 말고 서로 연관된 호출 지점을 직접 업데이트하십시오. ## 개인정보를 넓은 로그 수준에 남기지 않는다 호출 체인의 상위 단계에서 이미 추가한 로거 컨텍스트 필드를 반복하지 마십시오. 발신자, 수신자, 메시지 제목처럼 개인을 식별할 수 있는 필드는 리포지토리에서 접근이 가장 제한된 추적 수준에만 기록하십시오. 명시적으로 문서화된 예외에 따라 인증된 사용자 본인의 식별자를 더 넓은 수준에서 허용할 수 있지만, 이 예외를 제삼자 데이터까지 확대하지 마십시오. 개인정보 보호 필터, 컨텍스트 전파, 형식 지정이 계속 검증되도록 테스트에서는 실제 로거를 사용하십시오. 로그를 추가하기 전에 대상 독자, 보존 기간, 민감도, 기존 컨텍스트가 이미 해당 값을 제공하는지를 파악하십시오. ## UI 상태는 데이터에서 만들고 공유 컴포넌트를 쓴다 가져온 속성이나 서버 데이터를 이펙트를 통해 로컬 상태로 복제하지 마십시오. 읽기 전용 보기에는 파생 값을 사용하고, 사용자가 제어하는 초안에는 명시적인 편집 상태를 사용하십시오. 사용자 지정 기본 컴포넌트를 만들기 전에 리포지토리에서 승인한 컴포넌트 라이브러리를 사용하십시오. 비동기 콘텐츠는 공유 로딩 및 오류 래퍼를 통해 렌더링하여 로딩, 실패, 성공 상태를 일관되게 유지하십시오. 라우트 전용 페이지 컴포넌트는 중첩된 컴포넌트 디렉터리를 추가하지 말고 해당 라우트 진입 파일 옆에 배치하십시오. 여러 페이지에서 공유하는 컴포넌트는 애플리케이션의 공유 컴포넌트 디렉터리에 두십시오. ## 데이터 변경은 서버 액션과 공유 검증 스키마로 처리한다 접근 수준에 따라 라우트 미들웨어를 선택하십시오. 공개 오류 처리, 인증된 사용자 접근, 계정 범위 접근을 구분해야 합니다. 응답 인터페이스를 중복 정의하지 말고 데이터 함수에서 응답 타입을 추론하여 내보내십시오. 웹 변경 작업에는 리포지토리의 안전한 액션 계층을 통해 서버 액션을 사용하십시오. 네이티브 클라이언트처럼 안정적인 외부 HTTP 계약이 필요한 통합에만 POST API 라우트를 사용하십시오. 변경 작업 검증 스키마는 지정된 검증 모듈에 정의하고 그 스키마에서 입력 타입을 추론하십시오. 읽기에는 확립된 클라이언트 캐시를 사용하고 변경 작업 후에는 영향을 받는 키를 무효화하십시오. 승인된 폼 라이브러리와 액션 훅으로 폼을 만들고, 오류는 공유 액션 오류 포매터를 통해 처리하십시오. 일반 애플리케이션 로직에는 공급자 추상화를 사용하십시오. 실제 통합 경계에서만 구체적인 공급자 타입을 확인하십시오. 리포지토리에서 금지하는 경우 콜백 기반 동적 데이터베이스 트랜잭션을 피하십시오. ## LLM 기능은 키워드 목록이 아니라 의미로 테스트한다 평가 사례 하나의 문구가 아니라 일반적인 모델 실패 유형을 수정하십시오. 모델이 현재 사용하는 표현만 포착하려고 프롬프트, 평가, 테스트에 키워드나 구문 차단 목록을 추가하지 마십시오. 텍스트 검사는 언어가 달라지면 특히 쉽게 깨집니다. 모델이 불필요한 확인 질문이나 근거 없는 상태 주장을 피하는지처럼 의미적 결과를 판정 기준이나 구조화된 계약으로 검증하십시오. 임시 사용자 텍스트 일치를 기준으로 컨텍스트 주입이나 도구 동작을 절대로 제어하지 마십시오. 구조화된 상태, 메타데이터 또는 명시적 이벤트를 사용하십시오. 모든 도구 설명에는 목적, 매개변수의 의미, 선택 지침, 전제 조건, 도구별 안전 제약을 자체 완결적으로 담으십시오. 시스템 프롬프트에는 여러 도구에 공통으로 적용되는 정체성, 확인, 보안, 형식 정책만 두고 도구별 지침은 도구 설명에 배치하십시오. ## 변경 내용을 검토하고 실행한 검사를 보고한다 완료를 보고하기 전에 변경 diff를 검토하고 영향을 받는 동작을 입증하는 가장 작은 CI 기준 검사 세트를 실행하십시오. 계약이 통합 또는 평가 경계를 넘는 경우 통합 테스트나 평가 테스트까지 확대하십시오. 다음을 확인하십시오. - 모든 종속성과 환경 변수가 올바른 워크스페이스에 속합니다. - 테스트가 동작을 다루고 테스트 실행기가 새 테스트 파일을 발견할 수 있습니다. - 임포트, 스키마 기반 타입, 도우미, 추상화가 리포지토리 규칙을 따릅니다. - 로그가 개인정보 노출 범위를 넓히지 않습니다. - UI 상태, 변경 작업, 검증, 캐시 무효화, 로딩 상태가 확립된 패턴을 사용합니다. - LLM 동작을 깨지기 쉬운 문구가 아니라 의미로 테스트합니다. - 승인 없이 지원되지 않는 루트 전체 검사, 개발 서버 또는 전체 빌드를 실행하지 않았습니다. 실행한 검사와 의도적으로 범위에서 제외한 더 넓은 검사를 보고하십시오.