왜 폴리데우케스인가?

Polydeukes는 AI 코딩 파트너와 함께 일하거나 자신의 커밋에 같은 개발 관행을 적용하려는 사람을 위한 **규율 프레임워크(discipline framework)**입니다. 지킬 약속을 명시하고, 연결된 표면에서 관측한 증거를 판정하며, 일어난 일을 기록합니다. 작업 확인에 필요한 감독을 줄이는 것이 목적입니다. 모든 행동을 볼 수 있다거나 생성된 변경이 언제나 옳다고 주장하지는 않습니다.

문제는 확인할 수 없는 완료 주장입니다

에이전트가 “끝났고 테스트도 통과했다”고 말하는 것과 필요한 테스트가 실행됐다는 증거는 다릅니다. 프롬프트에 좋은 관행을 적을 수는 있지만, 지시만으로는 그 관행을 지켰는지 알 수 없습니다. 개발을 돕는 시스템이라면 정상 판정, 위반 발견, 검사 불가, 관측하지 못한 작업을 구별해야 합니다.

이 구분은 Polydeukes를 개발하면서 필요해졌습니다. 파일 편집은 거부하면서도 스크립트가 같은 내용을 쓰는 과정은 관측하지 못할 수 있었습니다. 안전하게 만들었다고 생각한 시험 입력이 판정 경로에 아예 들어가지 않은 적도 있었습니다. 경로를 지나치게 넓게 비교해 정당한 작업을 거부하기도 했습니다. 모두 서로 다른 결함이지, 차단이 잘 작동했다는 같은 사례가 아니었습니다.

그래서 주장을 좁히고 검사할 수 있게 만듭니다. 어떤 경로를 관측했는지, 무슨 증거가 있었는지, 어떤 비교를 했는지, 무엇을 기록했는지 밝혀야 합니다. 더 많이 차단한다고 더 잘 검증하는 것은 아닙니다.

지금 사용할 수 있는 것

여섯 패키지가 공통 입력 형식, 세 세션 어댑터, 프로그램용 TypeScript 클라이언트, 그리고 판정기와 pdks 명령을 포함한 통합 패키지 polydeukes를 구성합니다. 두 관측 표면은 서로 다른 용도로 쓰입니다.

• 세션 표면은 호출 하나를 실행 전에 판정합니다. 표준 입력으로 입력 IR을 받습니다. Claude Code, Grok, Codex에 설치할 수 있고, 프로그램은 @polydeukes/sdk-ts로 같은 표면에 닿습니다. 호스트마다 증명할 수 있는 대화 기록과 증인 기능은 다릅니다. 어댑터는 문서화되지 않은 대화 기록 형식을 계약으로 취급하지 않고, 안정된 호스트 이벤트로 그 증거를 구성합니다.
• 변경 집합 표면은 표준 입력으로 받은 통합 diff를 판정합니다. pre-commit 훅이 넘기는 스테이징 diff든 도구가 만든 diff든 같은 판정입니다. AI 에이전트 없이도 사용합니다. 프로젝트의 필요에 따라 한쪽만 연결하거나 둘 다 연결할 수 있습니다.

규율은 설정의 세 목록 가운데 하나에 적고, 어느 목록인지는 선언이 무엇을 읽는지가 정합니다. disciplines에는 두 표면이 모두 판정할 수 있는 것, 곧 변경된 파일만 읽는 선언을 적습니다. sessionDisciplines에는 실행 중인 호출만 가진 것, 곧 명령줄과 대화 기록과 주체를 읽는 선언을 적습니다. changeSetDisciplines에는 끝난 변경 집합만 가진 것을 읽는 선언을 적습니다. 로더는 표면이 관측할 수 없는 채널을 읽는 항목이 그 목록에 적혀 있으면 거부하므로, 설정 파일 자체가 각 규율이 어느 표면에 서는지를 말하고 pdks explain도 표면마다 같은 배치를 보여 줍니다.

규율(discipline)은 추출 단계와 관계를 담은 설정 데이터입니다. 현재 어휘에는 일곱 관계와 열여덟 메커니즘 이름이 있습니다. 이 중 delegated-scope는 사용할 수 없는 예약 이름입니다. 메커니즘은 선언이 취할 수 있는 구성을 제한하고, 표면은 공급할 수 있는 증거를 결정합니다. added-only 선언은 기존 위반을 허용하도록 쓸 수 있지만 모든 규율이 그런 것은 아닙니다. 예를 들어 짝 맞춤 선언은 선택한 키 집합을 비교합니다.

판정의 구성, 규율 작성하기, 설정 참조에서 구체적인 동작을 설명합니다.

원칙과 한계

함께 지키는 약속

약속(covenant)은 AI에게만 부과하는 제한이 아니라 개발자도 받아들이는 약속입니다. 누가 시작했든 관측한 작업에 설정된 보호를 적용합니다. 연결되지 않은 표면의 모든 편집을 막는 것은 아닙니다. 발견한 설정 파일은 자동으로 보호하지만, 다른 소스 파일의 보호 여부는 설정한 경로에 달려 있습니다.

사람은 증인(witness)을 통해 정책을 고치지 않고 차단된 작업을 허용할 수 있습니다. 지원되는 세션에서는 토큰을 인간 메시지의 첫 줄에 단독으로 입력하고 정해진 유효 시간을 지켜야 합니다. 변경 집합 표면에는 프롬프트가 없습니다. 밸브는 세션 표면의 유효 시간 증인뿐이고, 변경 집합 표면은 사용자의 훅이 소비하는 종료 코드만 냅니다. 밸브는 판정 후에 확인하며 조립 오류를 복구하는 기능은 아닙니다.

결정론적 판정과 명시적인 강제 수준

판정기는 파일을 열거나 네트워크를 사용하지 않고 공급받은 데이터를 평가합니다. 같은 판정 결과를 재현하려면 경로명만 같아서는 안 됩니다. 선언과 공급한 증거가 같아야 합니다. 두 표면이 서로 다른 내용을 관측하면 결과도 달라질 수 있습니다.

일반 규율의 기본값은 advise입니다. 정상 사례와 위반 사례를 시험한 뒤 작성자가 block으로 승격할지 결정합니다. 표면과 항목의 수준이 다르면 더 관대한 쪽을 따릅니다. 조립 오류는 여전히 실패로 처리하며, 텔레메트리 쓰기 실패는 판정 결과를 바꾸지 않습니다. 증거가 없을 때는 빈 소스를 만들어 내지 않고 선언의 공급 정책을 따릅니다.

호출 하나는 행 하나를 남기고, 그 행을 쓰는 구성 요소는 하나입니다. 에이전트 어댑터는 호스트의 페이로드를 판정기의 입력으로 옮겨 건네줄 뿐, 아무것도 판정하지 않고 아무것도 기록하지 않습니다. 실패하는 경로에서도 마찬가지입니다. 어댑터가 입력을 만들지 못하면 그 실패를 스스로 기록하는 대신 사유를 판정기에 보내므로, 결과에 따라 기록하는 주체가 달라지지 않습니다.

관측 범위를 밝힌 증거

passed, blocked, witnessed, advised, skipped는 판정의 결과를 나타냅니다. unattributed는 기준 상태와의 비교에서 발견한 사실을 기록하며 판정 결과가 아닙니다. 관측 대상이 없거나, 등록을 판정하지 못했거나, 명령이 성공으로 끝났다는 사실만으로 프로젝트 전체가 약속을 지켰다고 볼 수는 없습니다.

자식 프로세스가 임의로 쓰는 파일은 개별 세션 도구 호출로 관측되지 않습니다. 기준 상태와 비교하면 나중에 설명되지 않는 보호 대상의 변경을 발견할 수 있지만, 없었던 판정을 복원하지는 못합니다. 로그와 기준 상태는 로컬 파일이므로 저장소를 복제해도 따라오지 않습니다. 에이전트가 지침을 읽었다는 사실 역시 호스트가 훅을 실행한다는 증거가 아닙니다.

측정에서 알 수 있는 것

아래 수치는 이 저장소의 과거 관측입니다. 다른 프로젝트의 성능이나 현재 버전을 측정한 결과가 아닙니다.

시기	관측 기록
최초 자체 사용 티켓	133행. 정상 75건, 차단 2건, 밸브 허용 56건.
v0.1 마일스톤	세 티켓에서 판정 결과 1,020건. 정상 455건, 차단 13건, 밸브 허용 552건. 마감 감사에서는 수정이 필요한 경로 매칭 누락 다섯 개도 발견했습니다.
권고 기본값 결정 전 다섯 라운드	실시간 차단이 나쁜 편집을 막았다고 측정한 사례는 없었습니다. 인간이 밸브를 사용한 경우의 93%는 판정 체계 자체의 복구와 관련됐습니다. 이 기간의 관측이지 차단이 언제나 무용하다는 증거는 아닙니다.
2026-08-26까지 5주	7,446행. passed 6,438건, skipped 686건, blocked 173건, advised 88건, unattributed 47건, witnessed 14건.
v0.5.0 권고 라운드	advised 735행 중 73행, 9.9%에서 같은 세션의 같은 대상에 나중에 정상 판정이 있었습니다. 편집 전 독서를 요구한 한 규율은 77%, 다른 규율은 292행에서 0%였습니다.
v0.5.0 차단 관측	차단 162건의 88%는 판정 체계 자체를 보호한 경우였습니다. 오탐 차단 신고는 없었습니다. 조립 오류로 71초 동안 호출 여덟 건을 거부하고 모두 기록했습니다.

권고 비율의 분모는 독립된 결정이 아니라 호출 수입니다. 무시한 권고가 반복될 수 있습니다. 나중의 정상 판정은 이 측정에서 정한 ‘권고 소비’의 기준이지, 권고 때문에 작업이 개선됐다는 증거가 아닙니다. 오탐 신고가 없었다는 사실도 오탐이 전혀 없었다는 뜻은 아닙니다.

선택 편향도 있습니다. 에이전트가 거부를 예상하고 호출 전에 형태를 바꿀 수 있기 때문입니다. 이 프로젝트는 그런 점에서 passed를 준수의 상한, blocked를 의도된 위반의 하한으로 해석합니다. 어느 수치도 제출하지 않은 행동을 세지는 못합니다. 앞서 제시했던 예측 가능성 ‘90% 이상’은 설계 목표이며 달성한 비율이 아닙니다.

이 관측을 바탕으로 권고 기본값, 유효 시간이 있는 증인, 더 명확한 관측 기록을 도입했습니다. 그렇다고 현재의 권고 전달 방식이 충분하다는 결론을 내릴 수는 없습니다. 당시 호스트 검사에서는 stderr 권고가 모델에게 전달되지 않았습니다. 그래서 생성 스킬은 작업을 시작하거나 마칠 때 텔레메트리를 읽도록 안내합니다. 호스트의 동작은 가정하지 말고 직접 확인해야 합니다.

측정이 바꾼 설계

수치가 아니라 기전을 바꾼 사건이 다섯 있습니다. 현재 설계를 설명하는 데 이 다섯 사건이 필요하므로 여기에 적습니다.

• 편집은 막았지만 셸 heredoc은 막지 못한 금지어. 도구 축은 금지어가 든 편집을 거부했습니다. 같은 내용이 heredoc 안에 담겨 오자 텔레메트리 행을 남기지 않고 저장소에 들어갔습니다. 호출이 판정에 이르지 못했기 때문입니다. 셸 축에 heredoc을 인식하는 분석과 리다이렉트 쓰기 감지를 넣었습니다.
• 문장 중간에서 증언을 발동한 토큰. 증인 토큰을 사람 메시지의 어느 위치에서든 찾았기 때문에, 증언이 언제 만료되느냐고 묻는 문장이 유효 시간을 연장했습니다. 지금은 토큰을 첫 줄에 단독으로 두어야 발동합니다.
• 요청을 증거로 받아들인 판정. 첫 precedent 판정은 호출을 요청하기만 해도 증거로 셌습니다. 그래서 echo "npm view yaml"이 실제 검사를 실행하는 것보다 적은 비용으로 판정을 만족시켰습니다. 지금은 실행되어 성공을 보고한 호출만 증거로 셉니다.
• 조상 경로로 보호한 파일 하나. 경로 하나를 조상까지 포함해 보호했더니 홈 디렉터리 전체가 보호 대상이 됐습니다. 그리로 cd하는 호출이 2주 동안 거부됐는데 아무도 알아채지 못했습니다. 지금은 그 경로를 전체 경로 등가로 판정하고, 프로젝트 루트 위는 관측 범위 밖입니다.
• 두 호스트는 일치했고 세 번째는 달랐습니다. 호출을 판정할 약속으로 보내는 경로 선택은 도구의 인자를 읽었고, 판정 자체는 증명된 파일 변경을 읽었습니다. 두 호스트는 대상 경로를 양쪽에 모두 싣기 때문에 이 불일치가 드러나지 않았습니다. 그러다 편집이 패치 텍스트로 오고 경로 인자를 싣지 않는 세 번째 호스트가 들어오자, 그 호출들은 어느 약속으로도 가지 못한 채 통과로 기록됐습니다. 지금은 경로 선택도 증명된 변경을 읽습니다. 두 호스트에서 통과했다는 사실은 그 아래 층이 옳다는 증거가 아니라, 그 호스트들이 경로를 두 번 적는다는 증거였습니다.

아직 계획인 것

검증 가능한 장부(ledger), 검색할 수 있는 로컬 기억(memory), 적대적 **검증(verify)**은 로드맵의 구성 요소이며 아직 제공하는 서비스가 아닙니다. 텔레메트리는 미래의 장부가 아니고, 문서 검색은 기억 시스템이 아니며, 테스트 실행은 구현된 적대적 리뷰 서비스가 아닙니다.

Polydeukes는 에이전트 실행 환경이나 샌드박스도 아닙니다. 린터와 테스트를 보완합니다. 파일 내용을 비교하는 선언도 있고, 관측한 작업 이력을 요구하는 선언도 있습니다. 판정 중에 새 벤치마크를 실행하거나 자연어 설명이 참임을 증명하지는 않습니다.

이름의 유래는 STORY.ko.md에 있습니다. 구현된 기능을 사용하려면 첫 판정 따라 하기를, 현재의 한계와 복구 방법은 문제 해결을 참고하세요. 아직 베타 단계입니다. 사람의 감독 없이 개발을 완수한다는 보장으로 읽기보다, 명시한 한계 안에서 주장을 확인해 주시기 바랍니다.