vibator 설정하기
참고: npx vibator docs configuration은 설정 형식을 출력하고, npx vibator docs rules는 모든 규칙과 옵션 및 기본값을 출력합니다.
이 스킬은 워크플로우이고, 해당 문서들은 계약입니다.
설정은 발견(discovery) 작업입니다. 올바른 설정은 프로젝트가 실제로 포함하는 내용에 따라 결정됩니다. 먼저 검사하고, 그 다음에 작성하고, 마지막으로 실행하세요.
기본 규칙
- 게이트를 통과시키기 위해 게이트를 약화시키지 마십시오. 규칙을 끄거나, 예산을 늘리거나, 현재 실패하는 파일을 제외하는 것은 문제를 숨기는 것일 뿐 해결하는 것이 아닙니다. 발견된 문제를 수정하거나, 규칙이 실패하도록 두고 그 이유를 명시하십시오. 유일한 한 줄 면제는
// vibator-ignore: <reason>이며, 이유는 필수입니다. - 기본값과 다른 부분만 설정하십시오. 모든 규칙은 설정 없이도 자체 기본 심각도로 실행됩니다. 모든 기본값을 다시 명시하는 설정은 중요한 줄을 묻어버립니다.
include와exclude는 규칙의 기본값을 대체합니다. 병합되지 않습니다. 범위를 좁히기 전에 여전히 필요한 기본값을 복사하십시오.- 실행을 통과시키기 위해
recommended: false를 설정하지 마십시오. 설정에서 명명되지 않은 모든 규칙을 비활성화하며, 통과하는 규칙도 포함됩니다. 이는 의도적인 선택을 명시하기 위한 것이며, 그 선택은 사람의 결정입니다. - 프로젝트가 확장하는 설정은 수정할 수 없습니다. 프리셋은 여러 프로젝트가 공유하는 표준을 명시합니다. 로컬에서 차이점을 설정하거나, 사람에게 프리셋 변경을 요청하십시오.
node_modules아래의 파일을 편집하여 발견된 문제를 무음 처리하지 마십시오. 다음 설치 시 어차피 교체됩니다.
단계
-
유효한 파일에서 시작하십시오.
vibator.json이 없으면npx vibator init을 실행하십시오. 이 명령은 편집기에서 유효성 검사를 제공하는$schema줄을 작성합니다. 그런 다음npx vibator list를 실행하면 모든 규칙과 기본값이 표시됩니다. 직접 규칙을 작성하기 전에 프로젝트가 이미 프리셋을 확장하고 있는지, 아니면 확장할 프리셋이 있는지 확인하십시오(package.json의@scope/quality스타일 패키지 또는 형제 저장소에서 동일한 설정이 반복되는 경우). 이를 확장하는 것이 다시 명시하는 것보다 낫습니다. 아래의 "공유 프리셋 기반 구축"을 참조하십시오. -
설정 없이 한 번 실행하십시오:
npx vibator --reporter json. 이 명령은 어떤 규칙이 통과하고, 실패하고, 옵션 부족으로 충돌하는지 보여줍니다. 진단 전에 개수를 읽으십시오. 400개의 발견 사항이 있는 규칙은 오늘 400개를 모두 수정하는 것이 아니라 결정이 필요합니다(6단계 참조). -
기본적으로 꺼져 있는 규칙에 필요한 것을 찾으십시오. 각 규칙은 프로젝트 지식 없이는 작동할 수 없기 때문에 꺼져 있습니다. 다음을 찾으십시오:
locale-parity: 로케일 디렉토리(locales/,i18n/,public/locales/)를 찾으십시오. 레이아웃을 기록하세요: 로케일별 디렉토리(layout: "directory-per-locale") 또는 로케일별 파일("file-per-locale"), 그리고 소스가 어떤 로케일인지.codegen-drift:package.json스크립트에서 생성기(db:generate,openapi,graphql-codegen)를 읽고 각각이 쓰는 경로를 찾으십시오. 생성기당 하나의 항목을name,command,paths와 함께 설정하십시오.banned-patterns: 프로젝트의 리뷰 규칙(CONTRIBUTING, 스타일 문서, 반복되는 리뷰 코멘트)을 읽으십시오. "절대 X를 하지 마세요"라는 모든 패턴 형태는 자체message,expected및fix와 함께 항목이 되며, 내장 규칙만큼 신중하게 작성됩니다.no-deprecated-apis: tsconfig 목록을 작성하십시오. 모노레포의 경우options.projects에서 확인해야 하는 각 프로젝트가 필요합니다.
-
guidelines를 사용하여 기존 프로젝트 문서를 규칙에 연결하십시오. 저장소에AGENTS.md,CLAUDE.md또는 규칙이 적용하는 표준을 명시하는 스타일 문서가 있는 경우 다음과 같이 매핑하십시오:"guidelines": {"AGENTS.md": ["tsdoc-coverage"]}. 프로젝트의 표준이 컨텍스트를 추가하는 대신 제공된 가이드라인을 대체하는 경우에만 규칙별docs필드를 사용하십시오. -
분할 표준에는 배열 형식을 사용하십시오. 하나의 규칙이 다른 글로브와 옵션으로 여러 번 실행될 수 있습니다:
"max-file-size": [ {"include": ["src/**"], "options": {"maxKb": 256}}, {"include": ["assets/**"], "options": {"maxKb": 4096}} ] -
레거시 코드베이스에는
--changed를 사용하여 점진적으로 도입하고, 약화시키지 마십시오. 새 작업은 즉시 확인하고(npx vibator --changed, 또는 CI에서 PR 전체 diff에 대해--since origin/main), 백로그는 줄어들게 하십시오. 발견 사항이 많은 규칙의 경우 임시로warn을 사용하십시오. 발견 사항은 차단하지 않고 계속 표시됩니다. "나중에"라는 의미로off를 사용하지 마십시오. -
결과를 확인하십시오.
npx vibator를 실행하고 다음을 확인하십시오: 활성화된 모든 규칙이 실행되고(충돌한 규칙은 설정 버그이며 메시지에 누락된 내용이 표시됨), 남은 발견 사항이 실제이며, 재정의한 모든 항목에 대해npx vibator explain <rule>이 올바른 가이드라인을 보여줍니다.
공유 프리셋 기반 구축
extends는 .으로 시작하는 경로 또는 패키지 지정자를 사용하며, 이를 선언하는 파일을 기준으로 해석됩니다. 나중에 오는 항목이 이전 항목보다 우선하며, 파일 자체 설정이 모든 것을 재정의합니다.
{
"extends": ["@acme/quality/vibator.json"],
"rules": { "max-file-size": "warn" }
}
병합은 Biome을 따르므로 해당 스택 사용자가 예상하는 대로 작동합니다. 올바르게 처리해야 할 두 가지 결과:
- 단순 심각도는 다른 모든 것을 유지합니다.
maxKb와include를 설정한 프리셋 위에"max-file-size": "warn"을 작성하면 심각도만 변경됩니다. 예산과 글로브는 상속됩니다. 이를 다시 명시할 필요가 없으며, 다시 명시하는 것은 프로젝트가 프리셋에서 조용히 벗어나는 방법입니다. - 배열은 병합하지 않고 대체합니다. 상속된
allow또는patterns목록에 항목 하나를 추가하려면 원하는 전체 목록을 작성하십시오. 이는 의도적입니다. 상속된 항목을 제거할 수 있게 합니다.
차이점만 작성하십시오. 프리셋이 이미 말한 것을 반복하는 설정은 프리셋과 다른 것과 구별할 수 없으며, 다음 프리셋 업데이트는 복사한 필드에 도달하지 않습니다.
선별된 선택으로 구축된 프리셋은 "recommended": false로 설정하고 원하는 규칙을 나열합니다. 이러한 프리셋에서는 명명되지 않은 규칙이 실행되지 않으므로 규칙이 누락되었다고 결론내리기 전에 이를 확인하십시오.
가이드라인 경로도 같은 방식으로 해석됩니다. 프리셋이 명시한 docs 및 guidelines 항목은 프리셋을 기준으로 해석되므로 발견 사항은 함께 제공되는 문서를 가리킵니다. 사용자 자신의 경로는 여전히 프로젝트 루트를 기준으로 해석됩니다.
심각도 정책
error: 거의 0에 가까운 거짓 양성(false positive)을 가진 결정론적 규칙입니다.warn: 보지 못한 코드베이스에 대해 틀릴 수 있는 규칙(env-example-sync는 텍스트를 일치시키고,prefer-array-methods는 배열과Set을 구분할 수 없음)과 대규모 백로그가 있는 규칙의 임시 도입에 사용합니다.off: 적용되지 않는 규칙에만 사용합니다(로케일이 없으면locale-parity도 없음). 통과 방법으로 사용하지 마십시오.
일반적인 실수
include를 작성하고 규칙의 기본 제외 항목(테스트,.d.ts)을 잃어버리는 경우.- 심각도 재정의 옆에 프리셋의 옵션을 다시 명시하면서 단순 심각도가 이를 폐기한다고 가정하는 경우. 그렇지 않으며, 복사본은 프리셋 추적을 중단합니다.
- 환경에 없는 서비스나 시크릿이 필요한 생성기와 함께
codegen-drift를 활성화하는 경우. 규칙은 명령을 실제로 실행합니다. guidelines에서 모든 문서를 모든 규칙에 매핑하는 경우. 실제로 해당 규칙의 표준을 명시하는 문서만 매핑하십시오.- 실패하는 실행을 종료하기 위해 발견 사항을 수정하는 대신 설정을 편집하는 경우. 사람이 게이트를 요청했다면, 게이트를 낮추는 것은 사람만이 결정할 수 있습니다.