풀스택 엔지니어 → PPI 오케스트레이터
전환·실전·안정성 통합 가이드

1. 무엇이 달라지고, 무엇을 계속 책임지는가

풀스택 엔지니어는 이미 UI, API, 데이터, 인프라가 연결되는 방식을 안다. 오케스트레이터로 전환할 때 이 지식을 “어디를 직접 구현할까”에서 “어디를 나누고 어떤 계약으로 합칠까”를 판단하는 데 사용한다. 개발 경험이 있어야 에이전트의 그럴듯한 설명에서 빠진 상태·부작용·실패 경로를 발견할 수 있다.

계속 유지할 기술 책임: 아키텍처와 데이터 계약, 인증·인가, 상태 전이, 동시성, 실패 복구, 배포 영향, 관측 가능성. 구현을 위임해도 이 책임은 유지한다. 긴급한 작은 수정이나 낯선 경계를 익히는 작업은 직접 구현할 수 있다.

초기에는 코드 독해량이 늘 수 있다. 작성 시간을 줄인 만큼 테스트와 경계 검토에 시간을 배분한다. “직접 코딩을 안 한 비율”을 성과 지표로 삼지 않는다.

2. 기존 개발 능력을 여섯 가지 조정 능력으로 바꾸기

가장 먼저 익힐 것은 위임의 크기 조절

“이 이슈를 전부 해결해”는 범위와 판정 기준이 부족하다. 반대로 함수 하나마다 지시하면 조정 비용이 커진다. 하나의 관측 가능한 결과와 검증 방법을 가진 단위로 맡긴다. 예: “재접속 직후 음성 제어 상태가 서버 상태와 일치하는지 조사하고, 불일치 조건을 재현하는 테스트와 최소 수정안을 제출하라.”

작업자에게는 목적·경계·증거·완료 조건을 주고, 경계 안의 구현 선택은 맡긴다. 요구사항·공통 계약·권한 범위를 바꾸는 선택은 조정자에게 되돌리게 한다.

3. 전환은 네 단계로 연습한다

아래 4주는 시작용 제안이다. 달력보다 각 단계의 통과 기준을 우선한다. 처음부터 에이전트 수를 늘리기보다 위임한 결과를 판정할 수 있는지 확인한다.

전환 전략의 세 숙련 단계와 훈련의 연결

이 세 단계는 책임의 성숙도이고 아래 네 단계는 연습 순서다. 특정 도구나 문서를 보유했다는 이유만으로 현재 숙련도를 단정하지 않는다. 직접 코딩 0회·분석 시간 절반 같은 수치는 보편적인 졸업 조건이 아니며, 이해·검증·회귀·복구 근거를 먼저 평가한다.

1주차 — 직접 해결할 수 있는 작은 작업을 위임한다

PPI 백로그 중 익숙한 화면이나 상태 변경 하나를 고른다. 사람이 먼저 실행 경로와 실패 조건을 짧게 예상해 기록한다. 에이전트에게 코드 조사·테스트·구현을 맡기고, 결과와 자신의 예상을 비교한다. 직접 다시 전부 구현하는 대신 예상과 다른 경계·분기·테스트를 집중해서 읽는다.

통과 기준: 변경 파일의 역할과 핵심 조건을 설명하고, 각 AC를 어느 테스트가 보호하는지 가리킬 수 있다. ppi-docs에는 자신의 잘못된 예상도 정정 근거와 함께 남긴다.

2주차 — 구현자와 검토자를 분리한다

Claude Code 또는 Codex를 구현자로, 다른 하나를 읽기 전용 검토자로 둔다. 검토자에게 구현자의 결론뿐 아니라 원래 AC·기준 리비전·실제 diff·테스트 결과를 준다. 두 에이전트가 의견이 다르면 다수결 대신 재현·코드 조건·실행 결과로 판정한다.

통과 기준: 리뷰 finding 하나를 수용하거나 기각한 이유를 코드와 증거로 설명할 수 있다. 에이전트의 APPROVE만으로 완료 처리하지 않는다.

3주차 — 독립적인 조사부터 병렬화한다

VOC 하나에서 로그 타임라인 조사와 코드 경로 추적을 병렬로 맡긴다. 결과를 합쳐 원인 후보와 반증을 대조한다. 그다음 파일 소유권과 공통 계약이 명확한 구현만 병렬화한다. UI/API를 기계적으로 나누기 전에 요청·응답·오류 계약을 합의한다.

통과 기준: 왜 두 작업이 독립적인지 설명하고, 결과가 합쳐지는 경계의 테스트를 제시한다. 통합 코드가 달라졌으면 영향받는 검증을 다시 수행한다.

4주차 — 여러 인입과 세션 중단을 다룬다

데일리 로그·VOC·백로그를 하나의 우선순위 목록으로 관리한다. 신규/재발/중복과 사용자 차단/품질 저하/관측 필요를 구분한다. 하루 중 다른 세션으로 바꿔 ppi-docs만으로 재개하는 훈련을 한다. 실제로 반복되는 수집·정규화·보고 초안부터 자동화 후보로 정한다.

통과 기준: 에이전트가 바뀌어도 승인 범위·현재 결론·미실행 검증·다음 행동이 복구된다. 수집 실패를 “이슈 없음”으로 잘못 보고하지 않는다.

4. PPI 백로그 하나를 수행하는 전환 예시

아래 “저장 중 중복 클릭 처리”는 연습용 가상 사례이며, 현재 PPI에서 발견한 결함이나 구현 결과가 아니다.

요청: “저장을 여러 번 누르면 중복 처리될 수 있으니 개선해 달라.” 풀스택 경험을 사용해 UI의 버튼 상태와 서버의 중복 요청 처리가 서로 다른 경계라는 점을 먼저 구분한다.

1. 사람: 로딩 중 재클릭, 실패 후 재시도, 다른 탭/클라이언트의 중복 요청 중 어디까지 보장할지 정한다. 제품 범위가 UI 중복 클릭 억제라면 서버의 완전한 멱등성까지 구현했다고 설명하지 않는다.
2. 조사자: CodeGraph로 저장 handler·API·서버 쓰기 경로와 기존 테스트를 추적한다. 실제 중복 처리 가능 조건과 부작용을 제출한다.
3. 오케스트레이터: 작업 범위·AC·허용 파일·검증·미포함 위험을 정리하고 runtime 변경 설계 승인을 확보한다.
4. 구현자: 실제 위험 동작의 harness를 먼저 확인한다. 관련 테스트를 실행하고 최소 수정 후 같은 검증을 재실행한다. UI 상태는 외부 의존성이 없는 Storybook story로 재현한다.
5. 검토자: 버튼만 막고 요청 경로를 놓쳤는지, 오류 시 상태가 복구되는지, 테스트가 mock의 호출만 확인하는지 실제 보장 범위를 읽는다.
6. 사람 / 오케스트레이터: 최종 diff와 AC별 결과를 판정한다. 코드 경계·미포함 위험·리비전·검증·배포 상태를 ppi-docs에 기록한다.

이 과정에서 사람이 만드는 핵심 산출물은 구현 코드의 양이 아니라 범위와 계약, 근거 있는 판정, 다음에 재사용할 지식이다. 잘못된 범위 설정은 도구를 바꾸어도 해결되지 않는다.

5. 코드 검증 능력을 잃지 않는 방법

매 작업에서 사람이 직접 확인할 다섯 지점

1. 입력과 권한: 누가 어떤 입력을 보낼 수 있고 어디서 거부하는가?
2. 상태 전이: 정상·실패·재시도·재접속 중 어떤 조건이 바뀌는가?
3. 부작용: DB 쓰기, socket 전송, 미디어 생성/해제, 외부 요청은 언제 발생하는가?
4. 보호 테스트: 어떤 assertion이 이번 회귀를 잡는가? 기존 코드에서 해당 결함을 드러낼 수 있는가?
5. 운영 신호: 문제가 다시 생기면 어떤 로그·지표·사용자 증상을 볼 것인가?

익숙한 경계에서는 위 지점을 집중적으로 읽고, 처음 접하는 경계에서는 작은 직접 구현·재현으로 이해를 보완한다. 에이전트가 설명한 코드와 실제 소스가 맞는지 확인하는 습관을 유지한다.

검증 결과는 리비전에 묶는다

작업 시작 시 base·HEAD를 기록하고 review·test마다 대상 SHA를 남긴다. 미커밋 결과는 diff 스냅샷과 체크섬으로 식별한다. 구현자가 이후 코드를 바꾸면 이전 통과 결과를 그대로 최종 결과에 붙이지 않는다.

AC | 관측 가능한 기대 동작 | 파일·심볼 | 검증 명령/절차
대상 SHA 또는 diff 식별자 | 실행 시각·cwd·exit code | 증거 경로
판정: PASS / FAIL / BLOCKED / NOT RUN | 남은 한계

PASS는 기대 동작 관측, FAIL은 제품 불일치, BLOCKED는 환경·인증·데이터 문제, NOT RUN은 미실행이다. 단위 테스트 통과는 실제 브라우저의 오디오·기기·네트워크 동작까지 확인했다는 뜻이 아니다.

PPI 저장소의 기존 품질 절차를 실행 기준으로 사용

runtime 변경 전 brainstorming과 code-quality-guardian을 적용해 new-code / safe-refactor / combined를 분류하고 명시적 설계 승인을 받는다. 아키텍처 변경은 writing-plans를 추가한다. 위험 동작의 harness와 baseline을 먼저 확인하고 변경마다 관련 검증을 수행한다.

UI 변경은 외부 backend·socket·media device 없이 검토 가능한 Storybook fixture와 관련 정적 빌드가 필요하다. overlay는 apps/web/shared/ui/overlay의 useOverlay를 사용한다. 필요한 브라우저 수용 검증 뒤 code-review-expert guardian-gate로 최종 검토한다. 범위 내 P0/P1 수정은 최대 두 라운드, P2/P3·잔여 위험은 보고한다.

# 현재 상태·리비전 확인
git status --short
git branch --show-current
git rev-parse HEAD
codegraph explore "<관련 심볼>의 caller, callee, 구현과 관련 테스트"

# apps/web/package.json에 존재하는 예시. 변경에 해당하는 명령만 선정
pnpm --dir apps/web run test:activity-skip
pnpm --dir apps/web run test:avatar-form
pnpm --dir apps/web run build-storybook
git diff --check

위 제품 테스트는 이번 문서 작성에서는 실행하지 않았다. CodeGraph로 관련 범위를 찾고 최소 테스트·lint·typecheck를 실행한다. 테스트 파일의 존재만으로 harness가 충분하다고 판단하지 않는다. assertion 약화나 flaky 재시도로 실패를 덮지 않는다.

완료를 두 단계로 구분: 로컬 코드 검증·문서화 완료와 운영 배포·영향 관측 완료. commit·push·PR·merge·배포는 기존 승인 범위를 각각 확인한다. 이미 허용된 일은 계속하고 새 권한이 필요한 단계만 구체적으로 요청한다.

6. 도구는 전환 단계를 지원하도록 배치한다

초기 권장 구성: 사람 1명, 주 오케스트레이터 1개, 구현자 1개, 필요 시 검토자 1개. 독립 로그 조사처럼 구체적인 이점이 있을 때 추가한다. 한 작업의 상태 변경 주체는 하나로 정하고 Orca와 Herdr가 같은 작업자를 동시에 제어하지 않게 한다.

Orca의 Run은 작업 묶음과 수신함이며 자동으로 업무를 분해·배치하는 판단 주체가 아니다. terminal idle/done 또는 worker_done은 실행 상태이고, 품질 게이트 통과는 조정자가 증거로 판정한다.

자동으로 맡길 범위와 사람의 개입

영역 이름만으로 “항상 사람만” 또는 “격리돼 있으니 무조건 자율”이라고 정하지 않는다. 요청의 조사/구현 범위, 실제 권한, 검증 환경, 부작용을 기준으로 구분한다. 사람은 라운드·리뷰·배포 게이트에 집중하되 정책 위반·잘못된 범위·운영 영향이 발견되면 중간에도 개입한다.

병렬 작업을 늘리기 전 확인

• 목표와 산출물이 독립적인가? 선행 작업 결과가 아직 필요한가?
• 같은 파일·공통 타입·DB 스키마를 동시에 수정하지 않는가?
• 검토자는 수정 없이 같은 리비전을 보고 있는가?
• worktree가 달라도 포트·DB·큐·미디어 장치·클라우드 리소스를 공유하지 않는가?
• 결과를 합치는 담당과 통합 테스트가 정해졌는가?

파일 충돌이나 다른 리비전 검증 때문에 필요한 경우 도구 규칙에 따라 worktree를 분리한다. Orca의 child/top-level 계층과 Git base는 다른 개념이므로 의도한 develop 리비전을 직접 확인한다.

Orca 최소 감독 루프 — 설치된 가이드 기준 예시

orca skills get orchestration
orca status --json
orca orchestration run-create --objective "<이슈 ID> 근거와 코드 경로 조사" --json
orca orchestration task-create --spec "로그 타임라인 조사. 읽기 전용. 근거·반증 제출" --json
orca orchestration task-create --spec "코드 경로와 테스트 조사. 읽기 전용. 파일·심볼 제출" --json
# 실제 응답의 Task ID 사용. 이 예시는 두 작업 모두 읽기 전용
orca orchestration worker-start --task <로그-task-id> --worktree current --agent claude --json
orca orchestration worker-start --task <코드-task-id> --worktree current --agent codex --json
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 60000 --json
# 모든 메시지·결과를 검토한 후 즉시 재사용하지 않는 완료 작업자를 정리
orca orchestration worker-release --dispatch <완료-dispatch-id> --json
orca orchestration check --ack <delivery-id> --wait --types worker_done,escalation,question --timeout-ms 60000 --json

예상한 모든 Dispatch가 종료될 때까지 반복한다. 질문은 해당 메시지에 reply하고 수신 묶음을 모두 처리한 뒤 ack한다. timeout만으로 실패 판정이나 작업자 교체를 하지 않는다. 실제 실행 시 환경에 지정된 Orca 실행 파일과 현재 가이드를 따른다. 이 문서 작업에서는 worker를 실행하지 않았다.

Herdr는 기존 작업 가이드를 사용하되 HERDR_ENV=1과 설치된 도움말을 먼저 확인한다. 이전 문서의 pane ID나 모델 옵션을 추측해서 재사용하지 않는다.

7. 네 가지 업무를 전환 훈련 과제로 활용하기

VOC 연습: “아동 소리가 안 들린다”

녹음·전송·구독·출력 기기 중 어느 경계인지 아직 모른다. 사용자 원문을 유지하고 시각·역할·OS/브라우저·세션·직전 행동을 수집한다. 조사자는 양쪽 로그를 맞추고, 코드 조사자는 해당 생명주기를 확인한다. 사람은 “같은 시각의 오류”와 “증상을 일으킨 원인”을 구분하고 반증을 요구한다. 재현 실패는 정상 판정의 근거가 아니다.

데일리 로그 연습: 먼저 수집의 완전성을 판단

전일 KST 00:00 이상 당일 00:00 미만처럼 구간과 시간대를 명시한다. 예를 들어 9월 5일 KST 하루는 UTC 9월 4일 15:00 이상 9월 5일 15:00 미만이다. 서비스·환경·조회 쿼리·페이지네이션·지연 업로드·중복 제거 키를 기록한다. 연계 키가 없으면 시간만으로 같은 사건이라고 단정하지 않는다.

“수집 성공, 이슈 0건”과 “부분 수집, 판정 불가”를 분리한다. 동일 오류 반복 횟수와 고유 영향 세션 수를 구분하고 정상 기능 flag·정상 종료 조건 때문에 발생한 오탐을 코드와 대조한다. 지연 로그는 같은 일자 보고서를 개정한다. 자동 스케줄과 backlog 등록은 이 수집 계약을 검증한 뒤 별도 구현한다.

8. ppi-docs에 쌓아야 할 것은 판단 능력이다

매번 결과만 기록하면 무엇을 고쳤는지는 남지만 왜 그렇게 판단했는지는 사라진다. 원인 후보를 어떻게 줄였고 어떤 테스트를 신뢰했는지를 남겨야 다음 에이전트와 자신이 더 빨리 판단한다. 하나의 사건에는 대표 문서 하나를 두고 기존 문서를 먼저 검색한다.

대표 문서 최소 구조

ID / 원문 / 목표·비목표 / AC / 담당 / 상태 / 최종 갱신
기준 branch·SHA / 운영 버전 / worktree / 승인 범위·근거
E-01 증거: source·시각·조회 조건·원본 위치·만료
H-01 가설: 지지 증거·반증·확정/기각/미확인
D-01 결정: 선택·이유·대안·영향·재검토 조건
T-01 작업: 담당·선행 작업·허용 파일·상태·결과
V-01 검증: AC·리비전·명령·판정·증거
변경 지점 지도 / 현재 결론 / 잔여 위험 / 배포·복구 상태
다음 한 행동 / 재개 조건 / 관련 문서 / 변경 이력

개인 전환 회고 — 작업마다 세 문장 추가

내 예상과 실제로 달랐던 점:
에이전트 결과를 수용/기각한 핵심 근거:
다음 작업 지시·검증에서 바꿀 한 가지:

대표 문서 편집자는 오케스트레이터 한 명으로 정하고 작업자는 자신의 증거·결과를 제출한다. 상태 변경·새 결정·검증·blocker 시점에 갱신한다. 세션 종료 직전에만 몰아서 쓰지 않는다. 과거 가설을 확정 사실로 덮지 않고 정정 이력을 남긴다.

issues/에서 bugs/·features/로 대표 위치가 바뀌면 기존 문서에 새 대표 링크를 남긴다. index와 manifest에 등록하고 제안·가설·검증 결과의 metadata를 구분한다. 제품 저장소와 문서 저장소는 별도 리비전으로 관리한다. 로컬 저장 후 승인된 commit·push 상태까지 인계에 남겨 장기 보존 여부를 알 수 있게 한다.

공유 HTML에는 필요한 비식별 요약을 남기고 원본 로그·녹음·개인 식별 정보·인증 정보는 접근 통제되는 증거 위치에 보관한다. 만료 링크에는 저장 키·조회 조건·보존 만료·재수집 가능 여부를 보완한다.

기억의 세 층과 운영 리듬

ppi-docs는 대표 결론·결정·검증의 정본, 모델별 메모리는 문서 링크와 재사용할 판별법의 보조 색인, trace/artifact는 실제 실행의 원자료로 구분한다. 메모리가 자동으로 읽힌다고 가정하지 않고 다음 세션의 시작 지시에 대표 문서 경로를 넣는다.

매일은 수집 coverage와 신규/재발 후보, 작업마다 계약·검증·인계, 매주는 변경된 코드와 기존 문서의 불일치·표본 검토·회고를 확인한다. 기존 문서의 특정 cron 시각·룰 수·자동화 수준은 해당 실행 설정을 다시 확인한 뒤 사용한다. 원자료는 조직의 보존 기간과 접근 정책에 따라 보관하고, 문서가 남았다는 이유로 검증 근거를 즉시 폐기하지 않는다.

세션 재개 루틴

대표 문서의 현재 결론 → 마지막 인계 → git 리비전·diff → 살아 있는 작업자·소유 파일 → 승인 범위를 확인한다. 달라진 부분만 재조사하고 다음 한 작업을 시작한다. 문서와 실제 상태가 다르면 실제 상태를 확인한 뒤 정정한다.

9. 전환 훈련용 지시 템플릿

오케스트레이터에게

이 PPI 작업을 내가 코드 수준에서 이해·검증하며 완료하도록 조정해.
ID / 원문 / 목표:
기준 develop 리비전 / 환경:
수용 기준 / 비목표:
권한 범위:
대표 ppi-docs 문서:

1. 현재 지침·기존 문서·소스를 확인하고 실행 경계와 위험을 설명해.
2. 독립 작업만 나누고 담당·허용 파일·선행 조건·완료 증거를 지정해.
3. 내가 판단해야 할 제품·설계 선택은 근거와 구체적인 안으로 제시해.
4. 구현 전 저장소 설계 승인·guardian·harness 절차를 적용해.
5. 검토자는 원래 AC와 실제 diff·같은 리비전의 테스트를 확인하게 해.
6. 핵심 판단마다 파일·심볼·조건·테스트·운영 신호를 연결해.
7. 에이전트 간 의견 차이는 코드·재현·증거로 정리해.
8. 단계 전환과 종료 전에 ppi-docs를 갱신해.
9. 마지막에 내가 직접 읽어야 할 코드 경계와 남은 위험을 짚어줘.

작업자에게

목적 / 선행 결과 / 기준 SHA:
읽을 문서·증거 / 허용 수정 경로 / 제외 범위:
AC / 최소 검증 / 권한 / 질문이 필요한 조건:
산출물 경로:
보고 형식: 결론 → 파일·심볼 → 증거 → 검증 → 반증·한계 → 다음 행동

검토자에게

구현자 설명을 원래 요구사항·실제 diff·실행 결과와 대조해.
수정은 하지 말고 actionable finding을 보고해.
각 finding: 심각도 / 파일·심볼 / 발생 조건 / 사용자 영향 /
누락된 테스트 / 근거 / 최소 수정 방향.
통과 주장에는 대상 리비전을 붙이고 미실행·환경 차이를 표시해.

10. 전환이 되고 있는지 평가하기

전환 성공 기준: 직접 작성하지 않은 변경도 핵심 실행 경로와 실패 조건을 설명하고, 증거가 부족하면 합격을 보류하며, 다음 세션이 재개할 수 있게 남길 수 있다. 에이전트 수나 생성 코드량은 이 능력을 대신하지 못한다.

• 설명 가능성: 무작위로 고른 변경 한 건의 입력·분기·부작용·테스트·운영 신호를 설명할 수 있는가?
• 검증 연결률: AC 중 실제 실행 증거가 있는 비율. NOT RUN을 통과에 포함하지 않는다.
• 재개 시간: 새 세션에서 올바른 다음 행동을 정하기까지 걸린 시간.
• 재작업·회귀: 위임 범위 누락, 통합 충돌, 완료 후 재발 건수와 원인.
• 판단 비용: 작업당 사람 개입 횟수·리뷰 라운드·경과 시간·모델 사용량.

첫 주에 기준선을 측정하고 개선 목표를 정한다. 초기에 늘어난 검토 시간은 학습 비용일 수 있으므로 속도와 회귀를 함께 본다. 핵심 결론의 근거 누락과 완료 작업의 인계 누락은 0건을 목표로 한다.

자주 생기는 전환 실패와 교정

다음 실제 업무부터 할 다섯 가지

1. 작은 PPI 백로그 하나를 선정하고 목표·AC·비목표를 작성한다.
2. 직접 예상한 코드 경계와 실패 조건을 짧게 기록한다.
3. 구현자 한 명에게 위임하고, 별도 검토자로 같은 결과를 검증한다.
4. 자신이 읽은 핵심 코드와 수용/기각 근거를 ppi-docs에 남긴다.
5. 새 세션에서 문서로 재개해 보고 누락된 정보를 템플릿에 반영한다.

11. 투명한 작업 과정과 기업에서 사용할 수 있는 안정성

전환의 다음 목표는 에이전트의 행동을 관측하고, 산출물을 독립 검증하며, 실패의 영향을 통제하는 개발 시스템을 운영하는 것이다. 모델의 생성 결과에는 변동성이 남는다. 동일한 프롬프트·낮은 temperature·복수 모델의 합의만으로 무결함을 보장할 수 없다. 입력과 검증 조건을 통제하고, 검증 실패나 근거 누락이 있으면 다음 단계로 진행하지 못하게 해야 한다.

이 절은 PPI에 적용할 운영·구현 제안이다. 아래 실행 원장, CI 강제 게이트, 대시보드, 권한 분리 기능의 실제 구축 여부는 이번에 확인하지 않았다. 기존 Herdr/Orca 기록과 연결하되 지원하지 않는 기능은 별도 개발 과제로 다룬다.

11-1. 개발자가 볼 수 있어야 하는 세 가지

요구할 것은 검토 가능한 판단 요약과 외부 행동의 증거다. 모델 내부 추론을 완전히 재현·공개했다고 간주하지 않는다. pane을 계속 보는 방식은 초기 감독에 유용하지만 로그 누락·화면 잘림·자기 보고 오류를 해결하지 못한다. 개발자는 요약에서 필요한 이벤트와 diff·검증 결과까지 내려갈 수 있어야 한다.

11-2. 하나의 작업을 관통하는 실행 원장

Orca의 Run/Task/Dispatch 식별자와 애플리케이션 작업 ID를 연결한다. 실행기 또는 수집기가 발생 시점에 기록하고, 작업자가 사후에 작성하는 보고서는 별도의 주장으로 저장한다. 도구 실행을 관측하지 못한 구간은 관측 공백으로 표시한다.

run_id / task_id / attempt_id / dispatch_id
event_id / parent_event_id / sequence / timestamp / actor
event_type: task_started | tool_started | tool_finished |
            artifact_created | check_finished | approval | task_finished
input_ref / base_sha / working_diff_hash / tool·agent·model version
command 또는 tool_name / cwd / 허용된 범위 / 마스킹된 인자
started_at / finished_at / exit_code / stdout_ref / stderr_ref
artifact_ref / artifact_hash / evidence_ids
verdict: PASS | FAIL | BLOCKED | NOT_RUN | UNKNOWN

시크릿을 포함한 전체 환경변수를 저장하지 않는다. 환경은 이미지·도구 버전·의존성 식별자와 허용된 설정 목록으로 기록한다. 로그·VOC 안의 지시문은 조사 대상 데이터로 취급하고 에이전트 실행 권한이나 정책을 바꾸는 명령으로 받아들이지 않는다.

감사 신뢰 경계: 원장 보관 권한을 구현자의 수정 권한과 분리하고 접근 제어·보존 정책·추가 기록 방식·무결성 검증을 둔다. 해시만 생성해도 같은 작업자가 파일과 해시를 함께 바꿀 수 있으면 독립 증거가 되지 않는다. 초기 로컬 로그는 이 한계를 명시하고, 조직 적용 시 신뢰할 수 있는 CI/수집기가 artifact를 보관하도록 확장한다.

작업의 블랙박스를 검증하는 아홉 가지 실무 점검

초기 최소 세트는 실제 실행 기록·변경 지점 지도·관련 검증 재실행이다. 기업 적용 시 원장의 독립 보관과 강제 게이트를 추가한다. 자기 보고와 terminal 화면만으로 감사 증거가 완전하다고 간주하지 않는다.

11-3. 개발자가 보는 작업 화면의 최소 구성

[작업 계약] 목표 · AC · 비목표 · 승인 범위 · 기준 SHA
[진행 상태] 작업 DAG · 담당 · 파일 소유권 · 현재 단계 · 관측 공백
[타임라인] 질문/판단 → 도구 실행 → diff → 테스트 → 리뷰 → 승인
[변경 지도] 파일·심볼 · 바뀐 조건 · 부작용 · 실패 시 신호
[검증표]   AC별 PASS/FAIL/BLOCKED/NOT RUN · 리비전 · 원본 링크
[개입]     다음 단계 보류 · 범위 수정 · 추가 증거 요구 · 취소/복구 요청

“일시정지”는 새 작업 배정을 멈추는 것인지 현재 프로세스를 중단하는 것인지 구분한다. 이미 수행한 DB 쓰기나 배포가 자동으로 되돌아가지는 않는다. 범위를 바꾸면 작업 계약 버전을 올리고 영향을 받는 승인·검증을 무효화한다. 모든 중간 단계에 사람이 클릭할 필요는 없지만, 새 권한·계약 변경·근거 충돌·위험한 실행은 눈에 띄게 알려야 한다.

11-4. 확률적인 생성 결과를 검증 게이트 안에 둔다

• 작업 전: 요구사항·설계 승인·허용 경로·변경 금지 범위·필수 검증을 버전 관리한다. 정상·실패·경계 조건을 fixture로 고정하고 기존 결함을 드러내는 테스트를 가능한 범위에서 먼저 확보한다.
• 작업 중: 타입·schema·contract 검사와 최소 관련 테스트를 실행한다. 테스트·정책 자체의 변경도 별도 검토 대상으로 올리고 구현자가 임의로 합격 기준을 낮추지 못하게 한다.
• 통합 전: 신뢰하는 CI 환경에서 정확한 후보 SHA를 검증한다. 필수 check와 리뷰 승인은 저장소 보호 규칙으로 강제하고 작업자 자격증명에 우회 권한을 주지 않는다. 실제 도입 시 현재 저장소 설정부터 확인한다.
• 배포 전: 검증한 소스로 만든 artifact와 배포 artifact의 digest를 연결한다. SHA·설정·의존성·artifact가 달라지면 영향받는 검증과 승인을 다시 받는다.
• 배포 후: 해당 변경에 맞는 점진 배포·기능 flag·health 및 사용자 영향 관측을 설계한다. 사전에 정한 실패 지표와 복구 담당·절차를 연결한다. 데이터 migration은 되돌리기 가능 여부를 따로 확인한다.

검증 실행도 환경·시간·외부 서비스 때문에 흔들릴 수 있다. 고정 fixture와 시간 제어·의존성 격리로 재현성을 높이고, flaky는 원인을 조사한다. 통과할 때까지 반복한 마지막 결과만 남기지 않는다. 모든 시도와 변경 유무를 보존하며, 지정한 검증의 통과가 전체 시스템의 무결함을 증명한다고 표현하지 않는다.

11-5. 검토자도 틀릴 수 있다는 전제로 분리

다른 모델은 다른 관점을 제공할 수 있지만 오류가 통계적으로 독립이라고 가정할 수 없다. 둘 다 같은 잘못된 전제·누락된 AC·불완전한 mock을 공유할 수 있다. 원래 요구사항을 가진 읽기 전용 검토자, 실제 테스트를 재실행하는 검증기, 권한을 집행하는 저장소/CI를 분리한다. 작은 버그 수정은 관련 regression test, 계약 변화는 contract test, 고위험 상태 전이는 필요한 fault injection으로 검증 강도를 맞춘다.

사람은 모든 실행을 감시하기보다 계약 변경, 누락된 증거, 구현·검토 충돌, 정책 위반, 운영 영향에 집중한다. 승인 화면은 “승인하시겠습니까”만 보여주지 않고 대상 diff·검증·미해결 위험·실행 범위를 함께 보여줘야 한다.

11-6. 실패·중단·재시작을 정상 운영 경로로 설계

• 중복 실행 방지: 재시도는 새 attempt로 연결하고 외부 쓰기에는 작업별 idempotency key 또는 실행 결과 조회 절차를 둔다. 응답을 잃었다고 미실행으로 가정하지 않는다.
• 동시성 통제: 동일 파일·공통 계약은 단일 소유자를 두고, 필요 시 잠금/lease와 오래된 작업자의 쓰기 거부를 구현한다. worktree만으로 공유 DB·배포 대상 충돌을 막을 수 없다.
• 제한된 복구: 시간·비용·동일 실패 재시도 상한을 계약에 적는다. 상한에 도달하면 증거와 재개 조건을 남긴다. 도구 호출 실패와 제품 테스트 실패를 다른 경로로 처리한다.
• 최소 권한: 읽기 조사, 격리 코드 수정, 테스트, 문서 작성, Git 인계, 운영 변경의 실행 권한을 역할별로 부여한다. prompt의 “하지 말라”와 실제 자격증명·sandbox 통제를 함께 사용한다.
• 복구 연습: 테스트 실패, worker 종료, 도구 응답 유실, stale SHA 승인, 로그 수집 누락을 시험해 잘못된 완료·중복 쓰기·무단 배포가 차단되는지 확인한다.

11-7. PPI에서의 도입 순서와 기업 적용 판정

평가 세트에는 정상 작업뿐 아니라 틀린 구현, 부족한 증거, 실패한 수집, 잘못된 권한 요청을 포함한다. 잘못된 결과를 얼마나 통과시키는지와 정상 결과를 얼마나 불필요하게 막는지를 함께 측정한다. task별 분모·표본 수·관측 기간을 밝히고 한두 번의 성공을 기업 사용 준비 완료로 일반화하지 않는다.

파일럿 합격 조건 예시 — 목표이며 현재 달성 수치가 아님
- 승인 산출물의 SHA·검증 결과·승인 기록 연결: 100%
- 필수 검증 실패/누락 후보의 배포 허용: 0건
- 무단 범위 변경·실행 차단: 준비한 정책 시험 모두 통과
- 중단/응답 유실 복구: 준비한 시나리오에서 중복 쓰기 0건
- 운영 회귀율·복구 시간·작업당 비용: 기준선 측정 후 목표 확정

ppi-docs에는 계약·결정·검증·위험·재개 정보를 요약하고 원장은 접근 통제되는 artifact 저장소에 둔다. 문서가 실행 원장을 대신하거나 에이전트 자기 보고만으로 검증 상태를 승격하지 않게 한다. 기업 적용은 이 통제의 실제 작동을 확인하고 해당 조직의 데이터·보안·변경관리 요구에 맞춰 판정한다.

이 접근은 역할·책임, 반복 가능한 평가, 운영 관측을 다루는 NIST AI RMF Core와 방향을 같이한다. 소스와 빌드 산출물의 관계는 SLSA provenance, 그 증거를 검증하는 절차는 SLSA artifact 검증을 참고할 수 있다. 이 문서의 event schema·게이트·화면·파일럿 기준은 PPI용 설계 제안이며 표준 준수 인증을 의미하지 않는다.

2026-09-06 보강 — 실행 과정의 투명성, 외부 검증 게이트, 감사·권한·복구 통제 및 기업 적용 파일럿 기준 추가.

확인 근거와 문서 유지

현재 규칙·로컬 코드·설치된 도구 가이드를 확인해 전환 방법을 구성했다. 전체 백로그·로그 수집 경로를 이번에 완전 추적하거나 실제 멀티 에이전트 실행을 시험한 것은 아니다.

• ppi/AGENTS.md 및 제공된 지침: CodeGraph 우선, guardian, 설계 승인, Storybook·overlay 규칙.
• ppi/.agents/skills/pm-delivery/SKILL.md: 구현·브라우저·리뷰·Git 단계와 완료 기준.
• ppi/package.json, ppi/apps/web/package.json: 개발·관련 테스트·Storybook 명령.
• ppi/apps/web/types/db/session-log.types.ts, ppi/apps/web/features/session-log-export/model/use-session-log-export.ts: CodeGraph로 확인한 로그 타입·export 조사 출발점.
• ppi-docs/scripts/docs/catalog.js, html-metadata.js, metadata-schema.js, build-manifest.js: 분류와 metadata·manifest 규약.
• 설치된 orca skills get orchestration: Run/Task/Dispatch와 worker 완료·질문·ack·정리 계약.
• Claude Code 공식 병렬 작업 안내: subagent·팀·worktree의 구분. 구체적인 역할 분담과 훈련 계획은 이 문서의 PPI용 제안이다.

관련 문서

• Herdr 백로그 작업 가이드
• consensus-loop 구현·리뷰 가이드 — 라운드 규칙은 현재 저장소 guardian-gate와 혼합하지 않고 적용 범위를 정한다.
• S3·Grafana 분석 에이전트 설계
• 기술 이슈 대응 AI 파이프라인 개선안
• 운영·인프라 문서화 백로그
• PPI Docs 홈

• 재현 경로 파악 에이전트 설계
• 수업 로그 기술이슈 리포트 포맷 — before/after
• Hermes 완결형 지시 템플릿
• PO Translator
• 증상별 트러블슈팅 매트릭스
• 버그 교훈 누적
• 홍윤우 1회기 지지직 — Codex 합의 루프 분석

통합 편집: 2026-09-06 v2 — 전환 전략·실전 훈련·투명성·기업용 안정성의 중복 설명을 통합했다. 기존 전략의 3단계와 훈련의 4단계를 연결하고, 자동 권한·직접 코딩량·짧은 실행 시간에 대한 단정은 실제 승인·증거·검증 기준으로 정리했다. 이전 두 문서의 이력은 Git에 보존한다.

변경 이력: 2026-09-06 v1 — 풀스택 엔지니어의 역량 전환을 중심으로 단계별 훈련·검증·도구 배치·ppi-docs 학습 기록 작성. 첫 위임 작업 종료 후 예상/실제 차이와 재개 테스트 결과로 갱신한다.