Pi Delegate
당신은 오케스트레이터입니다. 제한된 코딩 작업을 별도의 구현자(implementer) — Pi 코딩 에이전트 CLI — 에게 위임하고, 그것이 생성한 결과를 검토한 후 직접 커밋합니다. 당신이 브리프를 작성하고 판단을 내리며, 구현자는 자체 세션에서 변경을 수행하고, 당신이 검증 및 커밋합니다.
이 루프는 셸 명령과 파일 접근만 필요하므로, 모든 오케스트레이터가 사용할 수 있습니다.
사용하지 말아야 할 경우
- 작업이 인라인으로 처리할 정도로 작은 경우 — 위임 오버헤드가 가치가 없습니다.
piCLI가 설치되지 않았거나 인증되지 않은 경우.- 샌드박스 처리된 구현자가 필요한 경우. Pi는 샌드박스나 권한 모드가 없습니다.
--read-only는 도구 표면을 제한하지만, 쓰기 가능한 실행은 프롬프트 없이 수행됩니다.
전제 조건 (한 번 확인)
npm install -g @earendil-works/pi-coding-agent로 pi를 설치합니다.- 구독 제공자의 경우 pi 내에서
/login으로 인증하거나, API 키 제공자의 경우 환경 변수 또는 pi의 인증 파일에 API 키를 설정합니다. pi --version이 성공하는지 확인합니다.- 대상 git 저장소에서 작업하거나
--cd로 지정합니다.
모델 선택 (선택 사항)
--model을 생략하면 pi의 기본 모델이 사용됩니다. 다른 모델을 선택하려면 pi --list-models에서 목록을 확인하고, <provider>/<model-id> 또는 sonnet:high와 같은 명시적 ID나 패턴을 전달합니다. 릴레이는 문자, 숫자, . _ : / -만 허용하므로(값이 Windows 셸에 도달함), *를 포함한 글로브 패턴은 전달되지 않습니다.
루프
작업당 다음 다섯 단계를 실행합니다. 1, 4, 5단계는 판단이 필요하며, 2, 3단계는 기계적으로 수행됩니다.
1. 브리프 작성
Pi는 당신이 보낸 텍스트와 작업 공간에서 검사할 수 있는 내용만 볼 수 있습니다 — 채팅 기록이나 공유 컨텍스트는 없습니다. 목표, 현재 상태, 변경할 사항, 건드리지 말아야 할 사항, 프로젝트의 실제 게이트, 그리고 보고서 계약을 포함하세요. Pi에게 커밋하지 말라고 지시하세요. 브리프당 하나의 작업만 유지하세요. Pi는 작업 공간과 상위 디렉토리에서 AGENTS.md/CLAUDE.md 컨텍스트 파일을 자동으로 로드하므로, 인라인으로 포함하지 않아도 저장소 지침이 전달됩니다. 자세한 내용은 references/writing-the-brief.md를 참조하세요.
2. 디스패치
번들로 제공되는 릴레이를 사용하세요. 릴레이는 브리프를 stdin으로 pi --mode json에 전달하고, JSON 이벤트 스트림을 캡처하여 result.json을 작성합니다. (<skill-dir>는 이 SKILL.md가 포함된 설치 폴더입니다.)
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# 모델 선택: add --model <id from pi --list-models>
# 제공자 선택: add --provider <name>
# 읽기 전용 실행 (검토/진단): add --read-only
# 프로젝트 .pi 리소스 신뢰: add --approve
# 가장 최근 세션 재개: add --resume-last (델타 브리프만 해당)
# 특정 세션 재개: add --session <id> (델타 브리프만 해당)
# 하드 시간 제한 (와치독): add --timeout 2h (기본 30분은 짧은 실행에 적합; 구현 브리프는 보통 1-2시간 필요)
# 모든 옵션 보기: node .../relay.mjs --help
자식 프로세스의 cwd는 작업 공간을 고정합니다. 릴레이는 아티팩트를 기본적으로 시스템 임시 디렉토리에 작성하며 절대 커밋하지 않습니다. 자세한 내용은 references/dispatch-and-poll.md를 참조하세요.
3. 완료 대기
릴레이는 pi가 완료될 때까지 블로킹됩니다. 오케스트레이터의 백그라운드 명령 기능을 사용하거나, 셸에서 백그라운드로 실행한 후 result.json을 폴링(poll)하세요. 사전 실행 사용 오류는 종료 코드 2로 종료되며 결과를 작성하지 않고, pi가 없으면 종료 코드 127로 종료되며 status: "pi_unavailable"을 작성합니다.
진행 표시보다는 프로세스 상태와 작업 트리를 신뢰하세요. 완료는 프로세스가 종료되고 result.json이 존재함을 의미합니다. Pi의 전체 보고서는 result.json의 finalMessage 필드에 있습니다(보고서 마커 사이에 stdout으로 전문이 인쇄됨).
4. 검토 — 자체 보고서를 신뢰하지 마세요
Pi의 최종 메시지와 게이트 주장을 주장으로 처리하세요:
- 프로젝트의 게이트를 직접 재실행하세요.
touchedFiles부터 시작하여 브리프와의 diff를 읽으세요.- 설치된 관련 가드 스킬을 실행하세요.
- 마이그레이션을 왕복 확인하고, 삭제 또는 이름 변경 후 매달린 참조를 grep으로 찾으세요.
자세한 내용은 references/review-and-land.md를 참조하세요.
5. 커밋
구현자는 작업 트리를 수정합니다. 오케스트레이터가 커밋합니다. 게이트가 통과되고 diff가 유효할 때만 커밋하세요. 재작업이 필요한 경우 --resume-last 또는 --session <id>로 델타 브리프를 보낸 후 다시 검토하세요.
자율성 및 권한
Pi에는 샌드박스나 권한 모드가 없습니다. 기본 헤드리스 실행은 읽기, 쓰기, 편집, 셸 명령 실행을 프롬프트 없이 수행합니다. 컨트롤은 다음과 같습니다:
--read-only는 pi의 호출 가능한 도구를--tools read,grep,find,ls로 제한합니다(내장, 확장, 사용자 정의 도구 모두). 설치된 확장 코드는 여전히 사용자의 호스트 권한으로 실행됩니다.- 릴레이는 기본적으로
--no-approve를 전달하므로, 프로젝트.pi설정, 확장, 스킬은 신뢰되지 않은 상태로 유지됩니다.--approve는 사용자가 신뢰하는 저장소에 대해 명시적으로 선택하는 옵션입니다. touchedFiles와 diff는 변경된 사항의 기록입니다. 모든 실행 후 이를 검사하세요.
인증 모델
위임은 사용자가 선택하는 것입니다. 일단 사용자가 선택하면("이 큐를 실행", "진행"), 검증된 게이트 통과 작업을 커밋하는 것이 합의된 계약입니다. 두 가지 제한이 남아 있습니다: 표면화, 흡수 금지(Pi의 설계 결정, 방어 가능하지만 요청되지 않은 방향 전환, 비차단 사소한 의견을 보고) 및 범위 변경 시 중단(올바른 완료를 위해 브리프를 넘어서야 하는 경우, 권한을 확장하는 대신 질문). 자세한 내용은 references/review-and-land.md를 참조하세요.
참조
- references/writing-the-brief.md - 구조, 보고서 계약, 실제 게이트, stdin 전달, 델타 브리프.
- references/dispatch-and-poll.md - 플래그, 아티팩트,
result.json, 폴링, 실패 복구. - references/review-and-land.md - 검토 체크리스트, 커밋 경계, pi 세션을 통한 재작업.
- references/multi-task-queues.md - 순차 큐, 제약 전달, 진행 추적, 최종 일관성 패스.