IAP을 기존 세션에서 사용하기: 수동 CLI와 훅 도입 분리

IAP(Interaction Accommodation Protocol)은 목적, 완성 조건, 실질적 성과를 대응시키고 AI나 주변 환경이 업무로 복귀하는 것을 지원하기 쉽게 개발된 메커니즘입니다. 이번에는 IAP 자체의 도입 문서를 수정하는 작업에 기존 Codex 세션에서 CLI를 명시적으로 호출하는 방법을 사용했습니다.

README에서는 훅(hook)을 신뢰하는 절차가 먼저 있었지만, 실제 작업에서는 훅 설정 없이도 성과를 대조할 수 있었습니다. 우선 사용하는 진입점과 이벤트로 대조를 유도하는 설정을 분리하여 설명하기 위해 로컬 README와 새로운 수동 가이드를 수정했습니다.

본 기사에서는 직접 CLI를 사용할 경우의 준비, 평가, 재개 절차와 기록 저장으로 인해 늘어나는 확인 사항을 다룹니다. 이는 작성자 측의 이용 기록이며, 제3자의 도입 성공이나 본인의 이탈 감지 및 복귀 효과 측정과는 관련이 없습니다. 새로운 가이드는 로컬 편집 단계에 있으며, 공개 리포지토리에는 반영되지 않았습니다.

직접 호출하는 경우와 훅을 사용하는 경우

직접 호출하는 방법은 훅의 신뢰를 통과한 것을 의미하지 않습니다. Codex의 비관리 훅(non-managed hook)은 정의에 대한 검토와 신뢰가 필요합니다. 공식 훅 신뢰 절차를 참조해 주십시오.

이번 환경은 macOS, Node.js v22.14.0, 로컬 IAP core 0.2.5입니다. CLI의 필수 환경은 Node.js 22.13 이상입니다. CLI 자체는 모델이나 API를 구동하지 않으며, 현재 세션의 AI가 실질적 성과를 읽고 의미를 평가합니다. 새로운 별도 모델의 시험 실행은 하지 않았습니다.

먼저 저장소와 볼 성과를 결정하기

이하부터는 macOS/Linux 셸 예시입니다. 로컬에 있는 IAP의 checkpoint.mjs와 사용을 허가받은 전용 프로젝트 폴더의 절대 경로로 대체합니다. 기존의 .iap/contract.json은 덮어쓰지 마십시오.

iap_cli='/absolute/path/to/iap-codex/checkpoint.mjs'
iap_case='/absolute/path/to/your-work'
node --version
...

.iap/에는 목적, 평가, 인용을 저장합니다. Git을 사용하는 경우, 기록 저장이 전에 제외 항목을 정리하고 추적되지 않는지 확인합니다. 이번 작업에서 보충한 부분은 여기입니다. manage.mjs install은 제외 항목을 추가하지만, CLI의 직접 실행은 .gitignore를 자동으로 변경하지 않습니다. 제외 규칙을 추가해도 추적된 파일이나 과거 기록이 비공개로 되지 않습니다.

비밀 정보나 고객 정보는 넣지 마십시오. observe의 출력을 AI가 읽게 하는 내용도 일반적인 Codex 처럼 대상이 됩니다.

생략 없는 최소 contract 예시

프로젝트 내 .iap/contract.json에 저장합니다. 다음은 독자가 자신의 문서에 맞추기 위한 예시입니다. 이번 실제 작업은 네 가지 조건으로 관리한 것이며, 이 두 가지 조건의 예시를 실행했다는 의미가 아닙니다.

{
"format": "iap-codex-contract/0.1",
"revision": 1,
...
}

guide.md를 이번 성과로 대체하고 실제 파일을 프로젝트 내에 놓습니다. 관측 대상은 상대 경로의 UTF-8 텍스트 1~16건이며, 각 64,000바이트 이하입니다. 심볼릭 링크나 프로젝트 외부 파일은 대상으로 할 수 없습니다. 이미지나 브라우저 표시를 직접 읽는 기능도 아닙니다.

평가를 먼저 정하지 않고 실질적 성과부터 저장하기

node "$iap_cli" handoff "$iap_case"
node "$iap_cli" observe "$iap_case"
node "$iap_cli" template "$iap_case"

신규 프로젝트의 인계가 미평가인 것은 일반적인 시작 상태입니다. AI에게 목적과 관측된 실질적 성과를 읽게 하고, 다음과 같이 요청합니다.

조건별로 met・not_met・unknown을 판단하고, 실제 파일에서 짧은 인용을 첨부해 주십시오. template 필드명과 관측 ID를 유지하고, scope와 다음 조치도 채워주십시오. 미완성을 실패 취급하여 조건을 약화시키지 말고, 미관측을 달성으로 처리하지 마십시오.

평가 초안을 .iap/review-draft.json

저장한 후, 표준 입력으로 전달합니다.

node "$iap_cli" record "$iap_case" < "$iap_case/.iap/review-draft.json"
node "$iap_cli" verify "$iap_case"

이번 실습은 준비부터 재개까지의 절차, 실제 성과 인용 평가, README와의 연결 및 정본 일치, 한계와 저장 기록 설명이라는 네 가지 조건을 시작 시점에 두었습니다. 초안은 제목과 예정만으로 구성되어 있었고, AI가 이 네 가지 조건 모두 미달로 평가했습니다. record의 반환값은 다음과 같았습니다(공유문 생성 관련 정보는 생략).

{"valid": true, "ready": false, "problems": []}

이후 가이드에 완전한 contract 예시, AI 평가 요청 문구, 여섯 개의 CLI, Git 제외 및 호출 누락 설명 등을 추가하여 README에서 도달할 수 있는 형태로 수정했습니다. 재관측한 문서를 읽고 네 가지 조건 달성으로 평가했으며, 실제 verify는 다음과 같은 값을 반환했습니다.

{"valid": true, "ready": true, "problems": []}

이 값은 가이드의 의미가 정확하거나 독자의 이해를 인증하는 것은 아닙니다. IAP가 검사하는 것은 평가가 현재 조건/성과에 대응하고 필요한 항목과 실제 존재하는 인용을 갖추었는지 여부입니다. 내용 판단은 같은 세션의 AI가 수행합니다.

이번 경우, 가이드 정본이 프로젝트 외부에 있는 iap-codex/MANUAL_WORKFLOW.md에 있기 때문에, 관측에는 바이트 일치 복사본을 사용했습니다. 정본과 복사본의 SHA-256 값, README의 실제 문구 및 링크는 별도의 대조 기록에 저장하고 있습니다. IAP가 프로젝트 외부에 있는 정본을 자동으로 추적하는 것이 아니므로, 정본을 재편집했다면 복사본과 평가 업데이트도 필요합니다.

수정 후와 다음 세션

성과를 수정한 후에는 observe와 template로부터 평가를 다시 만들고, 동일한 record와 verify를 실행합니다. 오래된 JSON의 관측 ID만 바꾸는 것이 아니라, 현재 성과와 인용을 다시 읽습니다.

node "$iap_cli" share "$iap_case"
node "$iap_cli" handoff "$iap_case"

share는 로컬의 공유문 생성까지입니다. 전송, 공개, 요청자의 수락은 별개입니다. 다음 세션에서는 handoff와 실제 성과로부터 재개합니다. 이번에도 공유문과 인수인계를 저장했습니다.

짧은 문서라면, Issue나 체크리스트에 목적과 다음 단계를 작성하는 방식으로 충분할 때가 있습니다. 테스트나 CI는 코드의 동작 확인을 담당합니다. IAP를 추가하면, 조건/관측 대상 선정, 인용 평가, 수정 후 재관측이라는 추가 작업이 발생합니다. 수동 CLI에서는 호출 누락도 남습니다. 이번에는 일반 메모와의 부담 차이나 시간 단축은 측정하지 않았습니다.

먼저 다음 건부터 수동으로 대조할지, 이벤트로 촉진할지를 선택하고, 그 방법으로 저장되는 기록까지 준비하는 것. 이것이 이번에 가이드를 다시 작성하여 명확히 한 시작 조건입니다.

IAP도 개발 중입니다

Partial Standards에서는 업무의 목적이나 완성 조건, 확인 및 재개 방법을 사람 대 사람, 사람 대 AI 사이에서 공유하는 시스템 **IAP(Interaction Accommodation Protocol)**를 개발하고 있습니다.

발달 특성이 있는 사람이 설명이나 주변과의 조정을 혼자 감당하지 않고 일할 수 있도록 하는 노력을 목표로 합니다. 현재는 사양 초안과 Codex와 함께 개발을 진행하기 위한 시험판을 공개하고 있습니다.

생각 방식이나 사용법은 IAP 소개 사이트에 정리되어 있습니다. 괜찮으시면, 한번 방문해 보세요.

Discussion