Featurevisor은(는) 무엇을 하나요?

Featurevisor를 통해 Git 기반 기능 관리를 진행 중인 사용자를 지원합니다. Featurevisor 프로젝트는 YAML(기본값) 또는 JSON 정의의 저장소입니다. CLI는 이 정의들을 린트, 테스트하고 정적 JSON 데이터 파일을 빌드하며, 애플리케이션은 SDK를 통해 이 데이터 파일을 로컬에서 평가합니다. 모든 작업은 다음 두 측면 중 하나에 해당합니다.

프로젝트 측: 기능, 세그먼트, 속성, 전역 변수, 테스트 등의 정의를 작성 및 조회하고 featurevisor CLI를 실행합니다.
애플리케이션 측: 데이터 파일을 로드하고 @featurevisor/sdk, React, Vue 또는 다른 언어용 SDK를 통해 평가합니다.

이 스킬은 Featurevisor v4에 대해 위 두 측면을 모두 다룹니다. 문서 인덱스는 https://featurevisor.com/llms.txt에 있으며, 전체 텍스트는 https://featurevisor.com/llms-full.txt에 있습니다. 아래 참조에서 다루지 않는 주제는 해당 링크를 통해 문서를 가져와 사용하세요.

사용자 파악하기

Featurevisor는 엔지니어, 제품 관리자, 마케터 등 YAML을 모르더라도 원하는 바를 설명하는 모든 사람이 사용합니다. 다음 사항을 염두에 두세요.

의도 해석. "네덜란드 사용자의 10%에게 배너를 켜 줘"는 롤아웃 규칙입니다. 직접 매핑을 수행한 후, 변경된 내용, 영향을 받는 대상, 그리고 다음에 어떤 일이 일어날지 사용자의 언어로 결과를 보고하세요.
일상적인 변경: 퍼센트 올리기, 포괄 규칙 위에 규칙 추가하기, 기능 추가하기, QA를 위해 기능 강제로 켜기. 이 작업들은 자신 있게 수행하세요.
위험한 변경: 규칙 키 이름 바꾸기, bucketBy 변경하기, 변형 가중치 변경하기, 퍼센트 낮추기, 아직 참조 중인 것을 보관 처리하기. 이러한 변경은 사용자를 결과 간에 이동시킵니다. "일부 사용자가 미드세션에서 기능을 잃게 됩니다"와 같이 명확히 말하고 진행 전에 확인하세요.
결과 보고. 변경 후, 배포 시 어떤 일이 일어날지 한두 문장으로 설명하세요. 예: "이 변경 사항이 머지되고 CI가 데이터 파일을 배포하면, 네덜란드 사용자의 약 10%가 배너를 보게 되고 나머지는 아무것도 보지 못합니다."
프로젝트를 YAML 대신 시각적으로 보고 싶은 사용자에게는 카탈로그를 제공하세요 (카탈로그를 통한 시각적 검토).

먼저 프로젝트 파악하기

이 스킬의 예제는 환경이 없는 기본 스캐폴드를 사용합니다. 프로젝트가 환경을 구성하는 경우 evaluate, benchmark, assess-distribution 및 build --print에 --environment=<name>을 추가하세요. 일반 파일 빌드는 모든 환경을 다룹니다.

프로젝트가 아직 없나요? 인터뷰 후 스캐폴드 생성

작업 트리에 featurevisor.config.js가 없으면 Featurevisor 프로젝트가 아닙니다. 사용자가 애플리케이션 저장소에 있다면 이는 SDK 작업입니다. 애플리케이션 통합을 참조하세요. 정의는 여기가 아닌 프로젝트 저장소에서 작성해야 합니다. 새 프로젝트를 원한다면 다음 사항을 먼저 물어보세요. 이후 작성되는 모든 파일이 이에 따라 달라집니다.

환경? 기본값은 환경이 없으며 규칙은 직접 목록 형태입니다. --example=with-environments는 명시적인 staging과 production 환경을 제공합니다.
세트? 기본값은 아니오. 독립적으로 검토되는 트리(dev에서 staging, production으로 승격되는 릴리스 레인, 또는 스토어프론트와 관리자 페이지처럼 관련 없는 표면)에 대해서만 세트를 제공하세요. 먼저 sets-promotions.md를 읽으세요.
소비자? 하나의 애플리케이션은 기본 all 타겟을 사용할 수 있습니다. 이 타겟은 선택자가 없으며 모든 활성 정의를 포함합니다. 여러 표면이 있는 경우 일반적으로 web, ios, android와 같은 태그와 표면별 타겟을 사용합니다.
파일 형식? YAML(기본값) 또는 JSON.
사용자를 식별하는 방법? userId, deviceId 또는 둘 다 (bucketBy: { or: [userId, deviceId] }). 린트는 모든 기능에 bucketBy를 요구하므로, 이 질문은 각 기능이 무엇을 선언할지와 어떤 속성이 먼저 오게 될지를 결정합니다.

애플리케이션 코드와 별도로, 빈 디렉토리(자체 저장소)에 스캐폴드하세요:

npx @featurevisor/cli@latest init
npm install

--example=with-environments는 환경 키 기반 규칙을, --example=environments는 세트를 릴리스 레인으로, --example=sets는 독립적인 표면을 제공합니다. CLI 설정 표에 모든 예제가 나와 있습니다. 그런 다음 인터뷰 답변에 맞게 featurevisor.config.js를 조정하세요. templates/example-project/는 린트와 테스트를 통과하는 완전한 v4 프로젝트로, 각 구성 요소가 어떻게 조화를 이루는지 참조하는 데 유용합니다.

기존 프로젝트인가요? 건드리기 전에 버전과 구조를 확인하세요

프로젝트의 패키지 매니페스트와 락파일에 @featurevisor/cli가 설치되어 있는지 확인하고, npm ls @featurevisor/cli로도 확인하세요. 그런 다음 프로젝트에서 설치된 CLI를 실행하세요:

npx featurevisor --version

프로젝트 자체의 바이너리를 사용해야 합니다. CLI가 없거나 npx가 패키지를 다운로드하겠다고 하면, 프로젝트의 잠긴 의존성을 복원하는 방법을 물어보고 중단하세요. 버전 확인을 위해 원격 CLI를 설치하거나 의존성을 업그레이드하지 마세요.

4.x: 이 스킬의 모든 내용이 적용됩니다.
3.x: v3 구문은 다릅니다. 규칙에 segments를 사용하고 requiredFeatures를 사용하며, 통합 conditions 대신 사용합니다. 또한 변수 조건, 합성, continue, 테스트 checks, 시나리오 및 여러 연산자가 없습니다. v3 프로젝트에 v4 구문을 작성하지 마세요. upgrading-to-v4.md에 v3 구문으로 나열된 범위 내에서 작업하고, 요청에 v4가 필요하면 업그레이드를 제안하세요.
2.x: scopes:, environments/ 디렉토리 또는 애플리케이션 코드의 createInstance와 같은 형태가 있습니다. 먼저 upgrading-to-v3.md를 제안하세요.

소비자가 게시 가능한 항목을 결정합니다. v4 데이터 파일은 v4 SDK가 필요합니다. v3 SDK는 통합 conditions를 이해하지 못하므로 규칙 매칭이 중단됩니다. 데이터 파일의 schemaVersion은 정보 제공용이며 이전 SDK가 파일을 거부하게 만들지 않습니다. 누적 재정의나 최신 연산자와 같은 런타임 기능을 도입하기 전에, 해당 데이터 파일을 소비하는 모든 애플리케이션의 SDK 버전을 확인하세요. 사용자가 모르는 경우 물어보세요. 각 SDK를 SDK 호환성 매트릭스와 대조하여 확인하세요. 네이티브 버전 번호가 다를 수 있으므로 호환되는 모든 SDK가 4.x라고 가정하지 마세요. CLI 린트 성공만으로 런타임 지원이 확립되는 것은 아닙니다. 테스트 검사와 시나리오에는 호환되는 CLI 러너가 필요하며, 이는 소비자가 지원하는 것과는 별개의 문제입니다.

그런 다음 설정을 읽어보세요:

npx featurevisor config --json --pretty
npx featurevisor info

네 가지 값이 작성하는 모든 것의 구조를 바꿉니다:

sets: true인 경우 모든 정의는 sets/<set>/ 아래에 있으며 명령어는 --set을 사용합니다. 먼저 sets-promotions.md를 읽으세요.
environments: 선언된 경우 기능의 rules, force 및 expose, 그리고 전역 변수의 overrides는 환경을 키로 하는 맵입니다. 환경이 없으면 직접 목록이며, expose는 불리언 또는 태그 목록입니다.
parser: "json"이면 JSON, "yml"(기본값)이면 YAML, 또는 설정된 사용자 정의 형식(custom-parsers.md)으로 작성합니다.
namespaceCharacter: 서브디렉토리 키의 구분자. 기본값은 .이므로 features/checkout/promo.yml은 checkout.promo가 됩니다. 일부 프로젝트는 /를 사용합니다. 모든 참조는 프로젝트의 구분자를 사용해야 합니다. npx featurevisor list --segments --json으로 실제 키를 확인하세요.

또한 tags(사용하는 모든 태그는 선언되어야 함), disallowOperators, allowedConditions, 그리고 featuresDirectoryPath와 같은 디렉토리 재정의도 확인하세요. 그런 다음 기존 정의를 한두 개 읽어 로컬 스타일을 파악한 후 새 정의를 추가하세요.

Featurevisor 구성 요소 이해하기

정의	경로	목적
속성	`attributes/<key>.yml`	컨텍스트 키와 그 타입을 선언합니다. 네임스페이스가 적용되지 않습니다.
세그먼트	`segments/<key>.yml`	`conditions`를 통해 오디언스에 이름을 부여합니다.
기능	`features/<key>.yml`	플래그, 선택적 변형 및 기능 변수, 롤아웃 규칙을 포함합니다. 버킷팅됩니다.
전역 변수	`variables/<key>.yml`	순서가 있는 재정의 또는 다른 값의 `compose`가 있는 타입이 있는 값입니다. 버킷팅되지 않습니다.
스키마	`schemas/<key>.yml`	재사용 가능한 변수 형태입니다.
타겟	`targets/<key>.yml`	어떤 정의가 데이터 파일에 포함될지 결정합니다.
테스트 스펙	`tests/*/.spec.yml`	기능, 세그먼트 및 변수 어설션, 그리고 독립적인 시나리오입니다.

조건은 정의가 선택하거나 게이트하는 모든 곳(세그먼트, 규칙, 강제 항목, 루트 게이트 및 재정의)에서 사용되는 단일 문법입니다. 리프는 속성을 비교하거나, 베어 문자열로 세그먼트를 참조하거나, 기능을 요구하거나, 변수 값을 비교합니다. 목록은 AND를 의미하며, and, or 및 not 그룹은 중첩됩니다. '*'는 모든 사람을 매칭하지만, 전체 표현식으로만 사용됩니다.

conditions:
  - attribute: country
    operator: equals
    value: nl
  - payingAccounts # 베어 문자열은 항상 세그먼트 키입니다
  - feature: liveChat # liveChat이 활성화되어 있어야 함
  - variable: maintenanceMode
    operator: equals
    value: false

평가 순서. 기능의 플래그는 스티키 값을 확인한 후 데이터 파일에 기능이 있는지 확인하고, 첫 번째로 일치하는 강제 항목, 루트 conditions, 그리고 조건이 일치하는 첫 번째 규칙을 확인하고 마지막으로 해당 규칙의 퍼센트를 사용자의 버킷과 비교합니다. 퍼센트가 일치하지 않으면 다음 규칙으로 넘어가지 않습니다. 전역 변수는 스티키 값을 확인한 후 루트 conditions, 합성 소스(있는 경우), 첫 번째로 일치하는 재정의(재정의가 continue: true를 설정한 경우 이후 재정의도), 마지막으로 기본값을 확인합니다. 자세한 내용: features.md 및 global-variables.md.

핵심 작성 규칙

참조 문서는 깊이를 더하지만 이 규칙을 재정의하지는 않습니다.

1. 버킷팅과 규칙 키는 계약입니다

bucketBy는 퍼센트가 변경되는 동안 각 사용자의 결과를 안정적으로 유지합니다. 한 번 선택하고 절대 자동으로 변경하지 마세요.
로그인된 표면은 userId로, 익명 표면은 deviceId로, 혼합 표면은 { or: [userId, deviceId] }로 버킷팅합니다. 속성 이름은 프로젝트마다 다릅니다: attributes/를 읽고 명확하지 않을 때는 어떤 것을 사용할지 물어보세요. 속성 이름을 임의로 만들지 마세요.
규칙 키는 목록(환경이 구성된 경우 환경별) 내에서 고유해야 하며, 사용자가 버킷팅된 후에는 변경되어서는 안 됩니다. 상태 파일은 각 규칙의 변형 범위를 키로 저장하므로 이름을 바꾸면 범위가 재할당됩니다. 이름을 바꾸는 대신 새 규칙을 추가하세요.

2. 첫 번째로 일치하는 규칙이 승리합니다

규칙은 위에서 아래로 실행됩니다. 국가 100%와 같은 좁은 규칙을 포괄 conditions: '*' 규칙 위에 두세요. 규칙이 일치하면 해당 퍼센트가 적용되며, 그 위의 사용자는 이후 규칙으로 넘어가지 않습니다.

3. 존재하는 것만 참조하세요

참조하는 모든 속성, 세그먼트, 기능 및 변수가 존재하는지 확인하거나 생성하세요. featurevisor.config.js의 allowedConditions도 확인하세요. 이는 각 위치에서 허용되는 조건의 종류를 제한할 수 있습니다(예: 세그먼트만 이름을 지정하는 규칙, conditions.md 참조). 린트는 알 수 없는 참조를 거부합니다. 또한 보관된 정의에 대한 참조가 보관되지 않은 정의나 스펙에서 발생하는 경우 archived_reference로 거부합니다. 보관된 정의는 데이터 파일에서 제거되므로, 이에 대한 참조는 자동으로 매칭을 중단하며, not 아래에서는 모든 사람을 매칭하게 됩니다. 린트는 보관된 정의의 형태만 확인하므로, 보관된 정의가 사용했던 것은 나중에 변경되거나 사라질 수 있습니다. 더 이상 사용되지 않는 정의에 대한 참조는 deprecated_reference 경고입니다. 보관, 이름 변경 또는 삭제 전에 npx featurevisor find-usage를 실행하고, 삭제보다는 보관을 선호하세요. 보관된 파일은 키를 예약합니다.

4. 변형 가중치는 100이어야 합니다

각 값은 고유합니다. control과 treatment는 관례일 뿐입니다. 린트는 가중치 합계가 100이 아니면 거부합니다. CLI 4.0.0에서는 그렇지 않았으므로 직접 합계를 확인하세요. 짧은 분할은 한 번 빌드된 후 모든 후속 빌드에서 Invalid saved variation allocation으로 실패합니다. 상호 배타적 실험에 대해서는 mutual-exclusion.md를 참조하세요.

5. 조건은 SDK 간에 이식 가능해야 합니다

모든 SDK가 동일한 데이터 파일을 평가하므로 린트는 이식 가능한 하위 집합을 강제합니다:

날짜(before, after)는 시간대가 포함된 완전한 ISO 8601 타임스탬프를 따옴표로 묶어 사용합니다: '2026-11-27T00:00:00Z'. 날짜만 있거나 시간대가 없는 값은 린트에 실패합니다. 두 연산자는 엄격합니다.
버전(semver*)은 '5.5' 또는 '5.5.0'과 같이 따옴표로 묶인 문자열이므로 YAML이 텍스트로 유지합니다.
정규 표현식(matches, notMatches)은 g, i, m, s 플래그만 허용하며, 비캡처 (?:…)를 포함한 모든 (? 구문, 역참조 및 소유 수량자를 거부합니다.
연산자는 선언된 타입에 대해 확인됩니다. format: date-time이 있는 type: string 속성은 before, after 및 존재 연산자만 사용하며, in은 문자열 목록을 사용합니다.

자세한 내용 및 린트 메시지: operators.md.

6. 프로젝트 구조에 맞추기

환경, 세트, 파서 및 네임스페이스 구분자는 동일한 요청이 작성되는 방식을 변경합니다. 템플릿은 환경이 없는 기본 구조를 사용합니다. 환경이 있는 프로젝트에서는 각 rules, force 또는 전역 overrides 목록을 환경 키 아래에 배치하고 테스트에 environment를 추가하세요.

완료 조건

모든 변경 후 이 루프를 실행하세요. 이것이 변경이 사용자가 요청한 대로 작동함을 증명하는 방법이며, 결과를 보고할 증거를 제공합니다.

린트. npx featurevisor lint가 통과해야 합니다. --json을 사용하면 각 오류에 filePath, path, message 및 code가 있으므로 정확한 필드를 수정할 수 있습니다. 수정 후 다시 실행하세요. 일부 오류는 이전 오류가 수정된 후에만 나타납니다.
새 정의 확인. npx featurevisor list는 생성한 모든 정의를 보여줍니다.
테스트 실행. npx featurevisor test가 통과해야 합니다.
변경된 사항을 요약하여 보고하세요. 무엇을 변경했는지, 누구에게 영향을 미치는지, 그리고 배포 시 어떤 일이 일어날지 사용자의 언어로 설명하세요.

참조

이 스킬의 나머지 부분은 심층 문서 파일을 참조합니다. 자세한 내용이 필요하거나 이 요약에 없는 항목이 있으면 문서를 가져오세요. 문서 인덱스는 https://featurevisor.com/llms.txt에서, 전체 텍스트는 https://featurevisor.com/llms-full.txt에서 확인할 수 있습니다. 주제별 참조:

속성: attributes.md
세그먼트: segments.md
기능: features.md
전역 변수: global-variables.md
테스트: testing.md
조건: conditions.md - 연산자, 허용된 종류 및 타입 검사
연산자: operators.md - 각 연산자에 대한 자세한 내용
타겟: targets.md
CLI: cli.md
SDK: sdks.md
스티키: sticky.md
내보내기: export.md
동기화: sync.md
사용자 정의 파서: custom-parsers.md
업그레이드: upgrading-to-v4.md, upgrading-to-v3.md
개인 정보 보호: privacy.md
제한: limitations.md
세트 및 프로모션: sets-promotions.md
상호 배제: mutual-exclusion.md
사용법 찾기: find-usage.md
카탈로그: catalog.md
스키마: schemas.md
구성: configuration.md - featurevisor.config.js 옵션

질문하기 전에

프로젝트가 있나요? featurevisor.config.js를 확인하세요. 없으면 프로젝트가 아닙니다.
버전은 무엇인가요? 앞서 설명한 대로 확인하세요.
보고 계신 오류 메시지는 무엇인가요? 사용자가 직면한 정확한 오류를 물어보세요.
무엇을 성취하려고 하나요? YAML 구문이 아닌 의도에 집중하세요.

적용 통합 (SDK)

사용자가 Featurevisor 프로젝트 저장소가 아닌 애플리케이션 저장소에 있는 경우, 다음을 도와야 합니다:

데이터 파일 로드
SDK를 통한 기능 평가

지원되는 SDK:

JavaScript/TypeScript: @featurevisor/sdk
React: @featurevisor/react
Vue: @featurevisor/vue
기타 언어: SDK 문서 확인

기본 SDK 사용법:

import { createInstance } from '@featurevisor/sdk';

const f = createInstance({
  datafileUrl: 'https://cdn.example.com/datafile.json',
});

const isEnabled = f.isEnabled('my-feature', { userId: '123' });
const variation = f.getVariation('my-experiment', { userId: '123' });
const variableValue = f.getVariableValue('my-variable', { userId: '123' });

OpenFeature 제공자

Featurevisor는 OpenFeature용 제공자를 제공합니다:

JavaScript/TypeScript: @featurevisor/openfeature-provider
기타 언어: OpenFeature 제공자 문서 확인

CLI 플러그인

Featurevisor CLI는 플러그인을 지원합니다. CLI 문서를 참조하세요.

카탈로그를 통한 시각적 검토

카탈로그는 YAML을 읽지 않고 프로젝트를 검토할 수 있는 웹 UI를 제공합니다. 사용자가 프로젝트를 시각적으로 보고 싶어하면 다음을 제안하세요:

npx featurevisor catalog

이 명령어는 로컬에서 카탈로그를 시작합니다. 자세한 내용은 catalog.md를 참조하세요.

v2 또는 v3에서 업그레이드

v2에서 v3로 업그레이드하려면 upgrading-to-v3.md를, v3에서 v4로 업그레이드하려면 upgrading-to-v4.md를 참조하세요.

Featurevisor

Featurevisor란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서