프런트엔드 규칙 저장소에서 규칙을 쓰고, 게시 전에 검사를 통과시키기

## 규칙을 바꾸기 전에 편집할 소스 파일과 생성된 파일을 구분하기 프런트엔드 규칙 저장소를 원본 콘텐츠, 스키마, API, 검토 도구, 렌더링된 페이지, 생성된 인덱스로 구성된 제품으로 다뤄라. 변경하기 전에 어떤 계층이 해당 동작을 소유하는지 파악하고, 그 계층과 직접 소비자를 함께 조사하라. - 콘텐츠 패키지, 공유 타입과 스키마, 애플리케이션 표면, 도구 서버, 생성 출력을 매핑하라. - 사용할 수 있다면 기억에 의존해 지침을 만들어내지 말고 저장소의 검토 도구와 규칙 검색 도구를 사용하라. - 수정안을 권고하기 전에 조사한 코드를 검토하고, 접근성, 성능, SEO, 보안, 개인정보 보호, 국제화 또는 테스트에 관해 주장하기 전에 규칙 모음을 검색하라. - 작업이 광범위한 감사를 요구할 때만 광범위한 감사를 수행하라. - 편집 가능한 원본과 생성된 산출물 및 렌더링된 투영물을 구분하라. 명시된 브라우저 정책과 패키지로 뒷받침되는 데이터에서 호환성 지침을 도출하라. 기억에 의존한 지원 표를 믿거나 생성된 뷰를 암묵적으로 진실의 원천으로 취급하지 마라. ## 모든 규칙에 꼭 있어야 할 메타데이터 정하기 모든 규칙에는 파싱, 검색, 채점, 검토, 렌더링을 지원하는 안정적인 메타데이터 계약이 필요하다. 필수 항목 집합은 일관되게 강제할 수 있을 만큼 작게 유지하라. 필수 메타데이터에는 다음이 포함되어야 한다. - 따옴표로 묶은 사람이 읽을 수 있는 제목과 한 문장 설명 - 허용된 카테고리, 우선순위, 난이도 - 단위가 명시된 정수형 작업량 추정치 - 규칙을 확인하고 수정하며 설명하기 위한 실행 가능한 프롬프트 유용한 선택 메타데이터에는 하위 카테고리, 간결한 핵심 요점, 사용자 또는 비즈니스 영향, 근거 출처, 보충 자료, 관련 규칙, 도구, 태그, 코드 검토 프롬프트, 자동 검토용 컨텍스트가 포함된다. 카테고리와 열거형을 정식 허용 목록에 대조해 검증하라. 구문상 의미가 있는 문장 부호를 포함한 값은 따옴표로 묶어라. 유용해 보인다는 이유만으로 필드를 추가하지 말고, 파서, UI, 검색 계층 또는 생성기가 소비할 때만 추가하라. 프롬프트에는 조사할 객체와 예상되는 수정 조치를 명시해야 한다. 실행 가능한 검토 전략을 제공하지 않는 “이 규칙 확인” 같은 자리표시자는 거부하라. ## 근거, 추가 자료, 관련 규칙 링크를 따로 두기 권위 있는 근거는 구조화된 원본 메타데이터에 보관하라. 선택적 읽을거리와 도구는 리소스 메타데이터에, 규칙 간 탐색은 관련 규칙 메타데이터에 보관하라. 한 역할을 다른 역할로 대체하지 마라. - 각 규칙에 관련 출처를 최소 2개 제공하되, 서로 다른 출처 역할 2개와 일차 권위 출처 최소 1개를 포함하라. - 파이프라인이 지원하는 경우 근거에 안정적인 식별자를 사용하라. - 일반적인 “참고 항목” 및 “참조” 문구를 본문에 넣지 마라. - 이름이 지정된 도구가 실질적으로 도움이 되고 이미 리소스 또는 도구 메타데이터에 있다면, 처음으로 의미 있게 언급할 때 링크하라. 인라인 링크는 구체적인 주장이나 구현 선택을 뒷받침해야 한다. 유용한 기본값은 규칙당 링크 2~5개이며, 도입부에는 0~1개, 주요 지침 전반에는 1~3개를 둔다. 내부 규칙 링크는 대부분 0~1개로 유지하고, 이례적으로 긴밀히 연결된 주제에만 2개를 사용하라. “더 읽기” 같은 레이블보다 설명적인 앵커 텍스트를 선호하라. 빌드 도구가 안전하게 도출할 수 있는 필드는 추론하게 하되, 빈약하거나 관련 없는 근거를 정당화하는 데 추론을 사용해서는 안 된다. ## 규칙 본문에서 코드 예시는 이유보다 앞에, 검증은 맨 끝에 두기 사람, 에이전트, 검증기가 같은 정보를 찾을 수 있도록 각 규칙을 안정된 순서로 작성하라. 1. 짧고 쉬운 언어로 된 도입부 2. 현실적인 코드 예제 또는 예제 모음 3. 규칙이 중요한 이유에 대한 설명 4. 필요한 구현 지침 5. 마지막 검증 섹션 예제를 근거 설명보다 앞에 배치하고, 검증을 마지막 최상위 섹션으로 유지하라. 모범 사례, 흔한 실수, 프레임워크 예제, 도구, 임계값, 예외, 브라우저 지원, 표준, 구현 참고사항 같은 선택 섹션은 그 사이에 배치하라. 유효한 주의 사항이나 거짓 양성이 있을 때만 예외를 추가하라. 자동 검사와 수동 검사가 모두 의미 있을 때만 검증을 둘로 나눠라. 호환성이나 규정 준수 여부가 구현 결정을 바꾼다면 눈에 띄는 표준 또는 지원 관련 참고사항을 추가하라. 일반적인 조언보다 통과/실패 지침을 선호하라. 엔지니어가 규칙을 검증하는 방법, 인정되는 근거, 검사를 실패하게 만드는 조건을 명시하라. ## 프런트엔드 규칙에 통과·실패를 판단할 수 있는 기준값 붙이기 규칙을 테스트할 수 있다면 항상 측정 가능한 임계값을 사용하라. - `LCP <= 2.5s`, `CLS <= 0.1` 또는 에셋 크기 제한 같은 성능 예산 - 명암비, 대상 크기, 키보드 동작, 확대/축소, 리플로 같은 접근성 기준 - 색인 가능 여부, 상태 코드, 정식 URL 동작 같은 SEO 상태 - 전송 및 응답 헤더 조건 같은 보안 요구사항 결과에 따라 우선순위를 배정하라. 사이트 장애, 보안 또는 법적 실패에만 최고 수준을 적용하고, 저하된 경험, 모범 사례, 선택적 다듬기에는 더 낮은 수준을 사용하라. 예제는 실패 양상을 드러낼 만큼 현실적이어야 한다. 중요한 예외와 지원 제약을 포함하되, 모든 규칙에 선택 섹션을 전부 추가하지 마라. 검증을 나중의 편집 작업이 아니라 규칙의 일부로 취급하라. 재현 가능한 검사가 없는 권고는 불완전하다. ## 공유 UI 부품은 각 페이지가 아니라 디자인 시스템에 두기 타이포그래피, 아이콘, 의미론적 색상, 재사용 가능한 컴포넌트 및 여러 애플리케이션에 공통되는 기타 관심사를 공유 디자인 시스템에 배치하라. 애플리케이션은 공유 계약을 사용하면서 프레임워크별 통합을 연결해야 한다. - 페이지별 변형을 만들기 전에 기존 컴포넌트를 재사용하라. - 공유 기능을 최초로 요청한 페이지만이 아니라 관련된 모든 표면에 적용하라. - 전체 영역 링크 카드 패턴을 사용할 때 보조 컨트롤을 계속 조작할 수 있게 유지하라. - 브랜드 아이콘과 프레임워크 아이콘 내보내기를 중앙화하라. 소비자는 디자인 시스템 경계를 우회해서는 안 된다. - 임의의 불투명도 수정자보다 의도한 대비를 온전히 갖춘 의미론적 테마 토큰을 선호하라. - CSS 리셋이 리치 텍스트의 목록 표식을 제거하면 명시적으로 복원하라. 불일치를 숨기기 위해 서버/클라이언트 하이드레이션 경고를 억제하지 마라. 클라이언트 전용 상태를 마운트 이후까지 지연하는 등 상태 경계를 수정하라. 브라우저 변경 작업과 폼에는 브라우저에서 비롯된 보호를 유지하라. 브라우저 챌린지를 완료할 수 없는 프로그래밍 방식의 API 엔드포인트에 클라이언트 측 봇 검사를 적용하지 마라. ## 새 도구를 정의부터 테스트까지 빠짐없이 연결하기 새 도구나 패키지 간 기능은 정의, 내보내기, 등록, 디스패치, 구현, 테스트, 문서가 모두 일치할 때만 완성된다. 호출 가능한 도구의 경우 다음을 수행하라. 1. 구체적인 이름, 설명, 입력 스키마를 정의한다. 2. 패키지 경계에서 내보낸다. 3. 서버의 도구 카탈로그에 등록한다. 4. 디스패치 경로에 연결한다. 5. 탐색, 검증, 라우팅, 동작을 테스트한다. 배럴 파일은 패키지 경계에서만 사용하라. 내부 배럴은 탐색 단계를 늘리고 소유권을 숨긴다. 여러 패키지가 사용하는 공유 의존성 버전은 중앙에서 관리하고, 스크립트는 유지 관리되는 인덱스와 함께 목적별로 구성하라. 버전별 라이브러리 계약을 준수하라. 예를 들어 설치된 검증기의 현재 오류 구조를 사용하고, 저장소에서 승인한 팩토리를 통해 상태를 가진 쿼리 클라이언트를 생성하며, 반환되는 모든 속성을 보존하는 순서로 비동기 구성 래퍼를 유지하라. 시작 시 로드되는 구성을 변경한 뒤에는 서비스를 다시 시작하라. 실행 중인 프로세스가 변경 내용을 로드하기 전까지는 편집 성공이 근거가 되지 않는다. ## 게시 전에 모든 검사를 실행하고 하나도 건너뛰지 않기 규칙이나 그 인프라를 변경한 후 저장소의 정식 품질 절차를 실행하라. - 필수 메타데이터, 카테고리 값, 출처 품질, 규칙 구조를 검증한다. - 실행 가능한 프롬프트, 근거, 예제, 본문 깊이, 검증, 임계값, 해당되는 조건부 섹션을 채점한다. - 포매팅, 린팅, 타입 검사, 패키지 검사, 집중 테스트, 변경된 표면에 필요한 전체 빌드를 실행한다. - 인덱스나 스킬을 다시 생성하고 생성 출력이 동기화되었는지 확인한다. 커밋 전 검사를 우회하지 마라. 검증 생략 경로를 사용하지 말고 문서, 안전하지 않은 캐스트, 복잡도, 가져오기 경계, 미사용 코드, 커버리지 실패를 수정하라. 자동 채점을 의미적 정확성의 증명이 아니라 품질 게이트로 취급하라. 원본 파일뿐 아니라 렌더링된 결과와 도구 대상 결과도 검토하라. 게시 전에 필수 프롬프트가 실행 가능하고, 근거가 권위 있으며, 예제가 권고와 일치하고, 검증이 마지막에 있고, 생성된 차이가 남아 있지 않은지 확인하라. 전체 절차를 통과한 뒤에만 게시하라.