표면 연결하기

작업에 맞는 표면을 고릅니다. Claude Code와 Grok, Codex는 세션 표면을 배선하고, git은 변경 집합 표면을 배선합니다.

두 표면은 같은 설정 어휘를 쓰지만 판정 시점이 다릅니다. AI 파트너가 편집할 때는 세션 표면을, 변경을 이력으로 기록하기 전에는 변경 집합 표면을 사용합니다.

Claude Code 세션 표면

Claude Code에서 AI 파트너와 함께 개발할 때 씁니다.

세 패키지를 프로젝트 의존성으로 설치합니다. pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-claude-code. 일회성 npx 실행만으로는 부족합니다. 두 표면 모두 프로젝트에 설치된 패키지에서 판정기를 불러옵니다.
프로젝트 루트에서 배선합니다. pnpm exec pdks-claude-code init. 이 실행 파일은 어댑터가 제공하며, 먼저 pdks init으로 초기 파일을 만든 뒤 Claude Code 등록 산출물을 씁니다.
생성된 훅, 병합된 설정, 초기 설정 파일, 문서 안내와 discipline-draft 스킬을 확인합니다.
훅이 바뀌면 프로젝트를 다시 엽니다. 생성된 훅은 패키지에 판정을 위임하므로 패키지를 갱신할 때 훅 파일까지 다시 쓸 필요는 없습니다.

설치기는 .claude/settings.json을 덮어쓰지 않고 병합합니다. 기존 훅과 권한은 보존합니다. .claude/rules/polydeukes.md에는 웹 검색 대신 설치된 pdks docs를 조회하도록 안내하고, .claude/skills/discipline-draft/SKILL.md에는 문제를 선언이나 초안으로 등록하는 절차를 제공합니다.

Grok 세션 표면

Grok에서 개발할 때 씁니다.

세 패키지를 프로젝트 의존성으로 설치합니다. pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-grok.
프로젝트 루트에서 배선합니다. pnpm exec pdks-grok init. 어댑터가 이 실행 파일을 제공합니다. 먼저 pdks init으로 초기 파일을 만든 뒤 Grok 등록 산출물을 씁니다.
설치가 끝나면 Hooks 탭을 다시 불러오거나 새 세션을 엽니다.

Grok 프로젝트에는 .grok/hooks/ 아래에 훅 JSON과 위임자가 생깁니다. 새 등록의 제한 시간은 60초입니다. Grok 호스트의 기본값은 5초이며, 훅 실행이 시간 초과로 끝나면 해당 호출을 차단하지 않습니다(fail-open). 세션 어댑터를 한 프로젝트에 둘 이상 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.

Grok는 세션 증인(witness) 밸브에 필요한 Claude 형식의 인간 메시지를 공급하지 않습니다. 대화 기록은 Claude JSONL이 아니라 ACP updates.jsonl입니다. 의도한 편집이 차단되면 자신의 터미널에서 수행하세요. 변경 집합 표면에는 증인 프롬프트가 없으므로 차단된 Grok 도구 호출을 커밋 쪽에서 허용할 방법도 없습니다.

Codex 세션 표면

Codex에서 개발할 때 씁니다.

세 패키지를 프로젝트 의존성으로 설치합니다. pnpm add -D polydeukes @polydeukes/core @polydeukes/adapter-codex.
프로젝트 루트에서 배선합니다. pnpm exec pdks-codex init. 어댑터가 이 실행 파일을 제공합니다. 먼저 pdks init으로 초기 파일을 만든 뒤 Codex 등록 산출물을 씁니다.
Codex에서 /hooks로 생성된 훅을 승인합니다. 승인하기 전까지는 훅을 건너뜁니다.

Codex 프로젝트에는 .codex/hooks/covenant-pretooluse.mjs 위임자와 .codex/hooks.json의 PreToolUse, UserPromptSubmit, PostToolUse, SessionEnd 항목이 생깁니다. 이 JSON은 덮어쓰지 않고 병합합니다. 사용자 항목, 같은 항목의 다른 handler, 다른 이벤트, 설치기가 모르는 키는 그대로 둡니다. 초기 설정은 기본적으로 .codex/hooks를 보호합니다.

승인은 선택이 아닙니다. Codex는 훅 정의의 해시로 신뢰를 기록하므로, 새로 쓴 훅은 검토 대상으로 표시되고 누군가 승인하기 전까지 건너뛰어집니다. 그때까지는 아무것도 판정되지 않습니다. init은 실행할 때마다 바이트가 같은 명령 문자열을 쓰므로, 다시 설치해도 이미 받은 승인이 무효가 되지 않습니다.

Codex는 훅에 도달하는 모든 파일 편집을 apply_patch 하나로 정규화하고, 경로 인자가 아니라 패치 텍스트를 보냅니다. Edit과 Write는 훅 파일에 적을 수 있는 matcher 별칭이며 도구 이름으로 도착하지 않습니다. 패치 하나가 여러 파일을 건드리면 파일마다 IR 원소 하나가 실리고, 그중 하나라도 차단되면 호출 전체가 차단됩니다.

승인된 훅도 Code Mode는 덮지 못합니다. codex-cli 0.154에서 Code Mode exec 호출과 그 JavaScript 안에 중첩된 도구 호출은 PreToolUse에 도달하지 않으므로 (openai/codex#23411), 그 경로로 이루어진 편집은 /hooks에 훅이 Active로 표시되는 동안에도 판정되지도 기록되지도 않습니다. init이 이 사실을 note: 줄로 출력하고, 패키지 레퍼런스가 다른 선언된 한계와 함께 나열합니다.

Codex의 대화 기록 형식은 계속 불안정하므로 해석하지 않습니다. 대신 UserPromptSubmit이 시각을 붙인 사람 메시지를, PostToolUse가 완료된 도구 호출을 .polydeukes/codex-sessions/ 아래의 어댑터 소유 파일에 기록하고 SessionEnd가 지웁니다. 의도한 차단을 풀려면 설정된 증인 토큰을 첫 줄에 단독으로 보낸 뒤 호출을 다시 시도합니다. 복구 메시지가 UserPromptSubmit 증거가 없다고 알리면 재시도가 증인 밸브에 닿지 못하므로 자신의 터미널을 사용합니다. 세션 어댑터를 한 프로젝트에 둘 이상 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.

변경 집합 표면

스테이징한 변경을 이력으로 기록하기 전에 Git에서 판정하려면 이 표면을 사용합니다.

프로젝트 루트에 polydeukes.config.yaml을 만듭니다.
pre-commit 훅을 추가합니다.
필요할 때는 git diff HEAD | pnpm exec pdks covenant check --diff를 직접 돌려 같은 판정을 봅니다.

lefthook 예시는 다음과 같습니다. git diff의 플래그는 판정기가 받는 것을 고정합니다. 색 코드 없음, 외부 diff 드라이버 없음, textconv 변환 없음, 번역기가 벗기는 a/·b/ 접두입니다. 사용자의 git 설정이 관측을 바꾸지 못합니다(CLI 레퍼런스 참고).

pre-commit:
  commands:
    covenant:
      priority: 1
      run: git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff

husky 예시는 다음과 같습니다.

git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff

일반 git 훅으로 연결해도 됩니다.

#!/bin/sh
git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/ | ./node_modules/.bin/pdks covenant check --diff

일반 훅은 .git/hooks/pre-commit으로 저장한 뒤 chmod +x .git/hooks/pre-commit으로 실행 권한을 줍니다. 기존 훅이 있다면 덮어쓰지 말고 호출을 추가하세요. lefthook은 패키지 관리자로 설치하고 YAML을 저장한 뒤 훅 설치 명령을 실행합니다. husky는 git이 찾을 수 있도록 husky 설치기로 .husky/pre-commit을 저장하세요.

판정기는 종료 코드 0 또는 2만 내고 사람에게 묻지 않습니다. 기본값에서는 protectedPaths 위반을 포함한 이 표면의 모든 위반이 stderr에 진단 한 줄을 남기고 행으로 기록되며 종료 코드 0입니다. 스테이징된 관문 파일 변경은 이미 세션 표면에서 판정을 받았거나 사람이 직접 한 것이고, 이 표면에는 사람이 답할 밸브가 없기 때문입니다. protectedPaths 위반이나 enforce: block 항목의 위반을 종료 코드 2로 받으려면 명령에 --enforce block을 붙입니다. 커밋을 멈출지는 훅 배선이 정합니다. 위 예시는 종료 코드를 그대로 따릅니다. 조립 실패는 언제나 종료 코드 2입니다.

증인과 회복

증인 토큰은 두 표면에서 같은 뜻이지만 전달 방식은 다릅니다.

세션 표면에서는 대화 메시지 첫 줄에 토큰만 단독으로 넣습니다.
변경 집합 표면에는 프롬프트가 없습니다. 판정은 종료 코드로 전달되고, 그것으로 무엇을 할지는 훅 배선이 정합니다.

밸브는 판정 결과가 차단일 때 확인합니다. 의도한 편집 전에 토큰을 입력해도 되며, 먼저 실패하는 요청을 보낼 필요는 없습니다. 정상 판정은 바꾸지 않고, 현재 Grok 대화 기록 형식에서는 세션 밸브를 사용할 수 없습니다.

Grok가 훅을 아직 읽지 못했다면 Hooks 탭을 다시 불러오거나 새 세션을 여세요. 판정기를 적재할 수 없다면 패키지를 다시 설치하거나 워크스페이스를 다시 빌드한 뒤 시도하세요.

배선한 뒤 확인할 것

pdks explain은 각 표면이 어떤 등록을 조립했는지 보여 줍니다.
.polydeukes/roi.log는 표면이 남긴 행을 기록합니다.
git diff HEAD | pdks covenant check --diff는 작업 뒤에 쓰기 좋은 즉시 확인 명령입니다.
git diff <base>..<head> | pdks covenant check --diff는 PR 전에 쓰기 좋은 형태입니다.