프로젝트 설정하기

프로젝트 루트에 설정 파일 하나를 두고, 제품 소스의 범위와 검증 명령을 정합니다. 위반이 생겼을 때 작업을 계속할지 차단할지도 선택합니다. 아직 설치하지 않았다면 첫 판정 따라 하기부터 시작하세요.

설정 파일 찾기

Polydeukes는 프로젝트 루트 바로 아래에서 polydeukes.config.yaml, polydeukes.config.yml, polydeukes.config.json 중 하나를 읽습니다. 상위 디렉터리까지 찾아 올라가지는 않습니다.

• 파일이 없으면 설정이 필요한 명령은 실패합니다. 기본값으로 대신 실행하지 않습니다.
• 파일이 여러 개면 필요한 내용을 합친 뒤 하나만 남깁니다.
• 발견한 설정 파일은 자동으로 protectedPaths에 포함됩니다. 설정 자체를 바꾸는 작업도 보호 대상입니다.

pdks docs는 프로젝트 설정 없이 사용할 수 있습니다. 필드별 제약은 설정 참조에서 확인하세요.

편집기에서 스키마로 검사하기

YAML 파일에는 다음 줄을 넣어 설치된 스키마를 편집기에서 사용합니다.

# yaml-language-server: $schema=node_modules/polydeukes/dist/schema/polydeukes.schema.json

이 경로는 설정 파일을 기준으로 한 상대 경로이지 모듈 이름이 아닙니다. 설정 파일이 모노레포 하위 패키지에 있고 의존성은 워크스페이스 루트에 설치된 경우, 올라가는 층수를 직접 셉니다.

# yaml-language-server: $schema=../../node_modules/polydeukes/dist/schema/polydeukes.schema.json

pdks init은 생성한 설정 파일을 기준으로 기본 경로의 스키마를 찾을 수 있을 때만 스키마 줄을 넣습니다. pdks-claude-code init이 이 명령을 대신 실행합니다. 이 줄이 없다면 스키마 위치에 맞춰 상대 경로를 직접 추가하세요. $schema 경로를 찾지 못하면 편집기에 오류가 표시되지 않은 채 스키마 검증이 중단될 수 있습니다.

우산이 아니라 @polydeukes/core를 직접 설치했다면 그 사본을 가리킵니다.

# yaml-language-server: $schema=node_modules/@polydeukes/core/schema/polydeukes.schema.json

편집기가 정적으로 읽는 파일 경로입니다. 런타임에 스키마를 읽는 코드는 exports 서브패스 @polydeukes/core/schema.json을 씁니다. JSON 설정에는 $schema 속성을 쓸 수 있습니다. 로더는 이 속성을 허용하되 실제 사용할 설정에서는 제외합니다.

언어 블록 채우기

languages에는 항목이 하나 이상 있어야 합니다. 각 항목에 제품 소스의 경로와 검증 명령을 적습니다.

languages:
  typescript:
    productionGlob: 'src/**'
    testCmd: 'pnpm test'

언어 이름은 프로젝트에서 정하는 키입니다. 설치기가 만든 임시 값을 실제 경로와 명령으로 바꾸세요. 블록을 지우거나 비워 두면 유효하지 않은 설정이 됩니다. 이 설정을 읽는 것만으로 검증 명령이 실행되지는 않습니다.

권고와 차단 중 선택하기

설정	위반 시 동작
항목의 enforce: advise(또는 적지 않음)	권고를 기록하고 호출을 진행합니다. 종료 코드 0입니다.
항목의 enforce: block	판정한 호출을 거부합니다. 종료 코드 2입니다.

적지 않으면 advise입니다. 설정에는 표면 단위의 강제 수준 키가 없습니다. 강제 수준은 각 항목이 가지며 적지 않은 항목을 승격하는 설정도 없습니다. 설정된 경로의 보호는 이 항목별 기본값과 별개입니다. 세션 표면에서는 차단하고, 변경 집합 표면에서는 명령을 --enforce block으로 실행하지 않는 한 advised로 기록합니다. 조립 단계에서 오류가 나면 종료 코드 2를 반환합니다.

protectedPaths는 두 표면에 모두 적용하는 최상위 목록 하나입니다. 변경 집합 표면에서 판정기는 종료 코드만 내므로, 커밋을 멈출지는 훅 배선이 정합니다. 표면 연결과 증인에서 자세히 설명합니다.

설정 확인하기

• pdks explain은 설정을 읽고 등록된 항목을 보여 줍니다. 변경을 판정하지는 않습니다.
• git diff HEAD | pdks covenant check --diff는 아직 커밋하지 않은 변경 전부를 판정합니다.
• git diff --cached | pdks covenant check --diff는 스테이징한 변경을 관측합니다. pre-commit 훅이 쓰는 형태입니다. 이 명령은 사람에게 묻지 않고 종료 코드 0 또는 2만 내며, 커밋을 멈출지는 훅 배선이 정합니다.

종료 코드와 함께 stderr와 텔레메트리도 확인하세요. 권고나 일부 미판정도 종료 코드 0을 반환합니다. 조립에 실패했다면 규율을 시험하기 전에 오류가 지목한 설정이나 빠진 패키지부터 확인하세요.