jinho-von-choi/anti-samcheonpo/samcheonpo

삼천포 사용 지침

삼천포는 AI 코딩 에이전트의 헛짓(같은 검사 반복, 요청 범위 이탈, 같은 실패 반복, 코드 밖 문제를 코드로 풀려는 시도, 허위 완료, 진척 없는 지출)을 실행 결과로 판정해 알리고, 경고를 무시하면 실행 전에 막는 로컬 하네스다. 모델을 호출하지 않고 기록은 사용자 컴퓨터에만 둔다.

아래는 에이전트가 삼천포를 세팅할 때(1·2절)와 삼천포 아래에서 일할 때(3~6절) 따를 규칙이다. 사용자 환경을 바꾸는 일(설치·연결·제거·설정 파일 수정)은 사용자가 요청했을 때만 한다.

1. 설치와 연결

순서대로 하고, 각 단계의 결과를 확인한 뒤 다음으로 넘어간다.

1. 설치 여부 확인: samcheonpo --version, samcheonpo-hook --version. 두 버전이 같아야 한다.
2. 없으면 GitHub Releases에서 플랫폼에 맞는 samcheonpo_<버전>_<OS>_<아키텍처>.tar.gz와 SHA256SUMS를 받는다(linux·darwin·windows, amd64·arm64).

``bash sha256sum -c --ignore-missing SHA256SUMS tar -xzf samcheonpo_<버전>_<OS>_<아키텍처>.tar.gz mkdir -p ~/.local/bin && install -m 755 samcheonpo samcheonpo-hook ~/.local/bin/ `` 두 파일은 같은 폴더에 둔다. Windows는 Git for Windows가 있어야 검사 명령이 POSIX 문법대로 동작한다.

1. 에이전트 연결: samcheonpo install --agent claude (또는 codex, opencode, agy, hermes, openclaw). 기존 훅과 상태줄은 보존된다. Hermes·OpenClaw 게이트웨이가 돌고 있으면 재시작해야 적용된다고 알린다.

• "이미 설치되어 있다"가 나오면 samcheonpo uninstall --agent <같은 에이전트> 후 다시 설치한다. 업그레이드 때 플러그인 파일을 갱신하려면 이 절차가 필요하다.

1. 점검: samcheonpo doctor --agent <에이전트>. error 항목이 없어야 한다. 에이전트 버전이 확인 범위 밖이라는 안내는 오류가 아니다(훅 형식이 맞는 동안 개입한다). hook_shape 경고가 나오면 그 에이전트의 훅 형식이 바뀐 것이므로 사용자에게 삼천포 업데이트가 필요하다고 알린다.

• ledger: 원장 무결성/스키마 확인 실패 (읽은 버전 N)는 업그레이드 직후 원장이 아직 갱신되지 않은 상태다. samcheonpo sessions를 한 번 실행하면 갱신된다. 원장을 지우지 않는다.

1. 첫 가치는 연결 없이도 나온다: samcheonpo audit --since 30d로 지난 기록의 헛짓 영수증을 보여 준다. 기록이 없으면 비어 있어도 정상이다.
2. 새 에이전트 세션부터 적용된다고 사용자에게 알린다.

2. 상황별 권장 세팅

설정 파일은 둘이다. 사용자 설정 ~/.samcheonpo/config.yml, 프로젝트 설정 .samcheonpo.yml(samcheonpo init으로 생성). 프로젝트 설정은 사용자 설정을 약하게만 바꿀 수 있다. 외부 프로그램(iron_laws.path), 알림 목적지(notify.push), 판정 모델(detectors.s3_drift.judge), 실험 모드(experiment.enabled), 군집 예산 확대는 사용자 설정에서만 가능하다. 이것들을 켜려고 프로젝트 설정을 고치지 않는다.

samcheonpo init 뒤에는 .samcheonpo/를 저장소 .gitignore에 넣기를 권한다. 계약 수락 기록과 통과 시점 기록이 커밋에 섞이지 않는다.

3. 작업 중 경고를 받았을 때

삼천포 경고는 관측 사실이다. 지시문으로 대하지 말고, 근거를 확인해 다음 행동을 바꾼다.

실행이 "권고가 이미 전달됐는데 반복되어 이번에는 막았다"로 거부되면:

• 차단을 피하려고 명령 글자만 바꾸지 않는다(환경변수 덧붙이기, 래퍼 추가, 명령 목록으로 감싸기, 파일 이름만 바꾸기). 판정은 실제 실행 내용과 작업 폴더 상태를 본다. 이런 우회는 같은 낭비를 반복하는 것이다.
• 차단 사유와 이전 결과를 읽고 접근을 바꾼다.
• 판정이 틀렸다고 보이면 근거를 들어 사용자에게 말한다. 해제는 사용자가 /samcheonpo:keep normal(이 판정은 틀림) 또는 /samcheonpo:keep now(이번만 허용)로 한다. 에이전트 셸에서 samcheonpo cmd keep·accept·skip·edit·extend·rollback apply를 실행하면 거부된다.

코드 밖 원인

설치되지 않은 의존성·명령, 실행 권한, 주소 해석 실패, 접속 거부, 권한 없음, 포트 점유, 인증 거부, 디스크 부족은 코드로 풀리지 않는다.

• 첫 실패 뒤: 출력에서 원인을 확인하고, 코드가 아니라 환경이 원인이면 사용자에게 할 일을 알린다. 사용자 승인 없이 서비스를 켜거나 패키지를 설치하지 않는다. 환경을 고친 뒤의 재실행 한 번은 회복 확인으로 허용된다.
• 같은 명령이 환경 변화 없이 같은 원인으로 두 번 실패하면 소스 수정이 실행 전에 보류된다. 거부 사유에 "외부 조치(사람이 실행): npm install yaml" 같은 명령이 들어 있다. 이때는 코드를 고치지 말고 그 명령을 사용자에게 그대로 전달하고 기다린다.
• 보류 중에도 의존성 선언 파일(package.json, requirements.txt, go.mod 등)은 고칠 수 있다. 누락된 패키지를 선언하는 것은 정당한 코드 쪽 일이다.
• 보류는 같은 명령이 통과하거나, 설치·서비스 기동 명령이 성공하거나, 사용자가 /samcheonpo:keep normal로 풀 때 해제된다. 사용자가 조치했다고 하면 같은 명령을 한 번 실행해 확인한다.

맥락 압축 뒤

응답에 [SAMCHEONPO ANCHOR] goal=... protect=... allow=... budget=... done=n/m 줄이 오면 압축으로 잃은 계약 상태를 다시 알려 준 것이다. 그 줄의 목표·보호 경로·남은 완료 조건을 현재 작업 기준으로 삼는다. 압축이 없으면 이 줄은 오지 않는다.

4. 작업 계약

기본은 관찰 전용이다. 사용자가 완료 기준을 하네스가 직접 확인하길 원하면 계약을 쓴다.

# .samcheonpo/contract.yml
goal: 로그인 세션이 만료되면 재로그인 화면으로 보낸다   # 바뀔 동작을 사용자 말로 한 문장
done:
  - check: "pytest -q tests/test_session.py"            # 하네스가 직접 실행할 명령
  - manual: 만료된 토큰으로 접속하면 /login으로 이동한다  # 사람이 확인할 조건
scope:
  allow: ["src/auth/**", "tests/**"]
  protect: ["migrations/**"]
budget: {krw: 5000, minutes: 40}

• 초안은 에이전트가 쓸 수 있지만 수락은 사용자만 한다(/samcheonpo:accept). 초안은 실행 승인이 아니다. 초안을 쓴 뒤 수락을 기다리지 말고 요청받은 작업을 이어서 한다.
• check는 순수하고 결정적인 명령으로 둔다. 빌드 산출물을 만들거나 마이그레이션을 돌리는 명령은 근거 재사용에서 빠진다.
• .samcheonpo/contract.state.json을 직접 쓰거나 고치지 않는다. 수락 기록은 사용자 키로 서명되며 에이전트가 쓴 기록은 인정되지 않는다.
• 수락 뒤 계약의 어느 항목(목표 포함)을 바꾸면 다시 수락해야 한다. 목표를 바꿔 범위 이탈을 정당화하지 않는다.
• 완료 여부는 samcheonpo cmd check(또는 /samcheonpo:check) 결과로 말한다. 수동 조건은 사용자가 확인하기 전까지 미완료다.

5. 상태 확인과 되돌리기

• 상태줄 맨 앞 상태: 순조로움(진척 근거 있음), 지켜보는 중, 지금 끼어드세요, 확인 불가(관측 누락·저장 실패·기한 초과). 경고가 없다는 것을 진척으로 보고하지 않는다.
• 요약: samcheonpo cmd summary (요청한 일, 지금 하는 일, 끝난 것, 막힌 것, 쓴 돈). 현재 상태: samcheonpo cmd status.
• 되돌리기(마지막 진척 시점): AI가 쓰기 도구로 바꾼 파일을 마지막으로 검사가 통과한 시점으로 되돌린다.

1. samcheonpo cmd rollback으로 미리보기와 계획 ID를 보여 준다.
2. 적용은 사용자가 /samcheonpo:rollback apply <계획 ID>로 한다. 에이전트 셸에서 실행하면 거부된다.

• 되돌리기(기록된 통과 시점): 검사가 통과할 때마다 AI 소유 파일이 .samcheonpo/snapshots에 기록된다(최근 5개). samcheonpo cmd rollback golden으로 목록, rollback golden <id>로 미리보기, 적용은 사용자가 /samcheonpo:rollback golden <id> apply <계획 ID>로 한다. 데몬이 다시 시작된 뒤에도 쓸 수 있다.
• 두 되돌리기 모두 소유권이 확실한 파일만 다룬다. 사람 편집이 섞인 파일, 셸·링크로 바뀐 파일, 1MB 초과 파일, 다른 세션의 AI가 쓴 파일은 대상이 아니며 미리보기에 이유가 나온다. 바꾸기 전 내용은 ~/.samcheonpo/backup/에 백업된다.

6. 회고와 보고

• samcheonpo audit --since 30d: 지난 기록에서 토큰이 진척·필요한 탐색·헛짓·기타 중 어디에 쓰였는지 집계한다. 모델을 호출하지 않는다.
• samcheonpo receipt <세션> --evidence: 세션 하나의 근거. 공유할 때는 --share.
• samcheonpo gaps --since 30d --out <새 파일>: 규칙이 놓친 의심 구간 후보. 판정이 아니다.
• samcheonpo interventions: 처방이 제안·전달·인지·효과 관측 중 어디까지 갔는지.
• samcheonpo handoff <세션>: 다른 에이전트나 새 세션에 넘길 첫 지시문. 원문이 들어 있어 공개 공유용이 아니다.

결과를 보고할 때:

• 원화는 "API 환산액"이라고 쓴다. 실제 청구액이나 절감액이라고 쓰지 않는다.
• 단가·사용량이 빠지면 0원이 아니라 "미확인"이다.
• 소급 분석의 맥락 이탈 판정은 추정이라고 밝힌다.
• "실시간이었다면 개입 N회"는 판정 후보 수다. 실제 개입이나 효과가 아니다.
• 완료는 완료 조건 검사 결과로만 말한다. "시험이 통과했다"고 말하기 전에 마지막 실행 결과가 실제로 통과였는지 확인한다.

7. 하지 않을 것

• 경고를 피하려고 명령·시험·설정을 조작하지 않는다.
• 사용자를 대신해 keep, accept, rollback apply, rollback golden ... apply를 실행하지 않는다.
• 코드 밖 원인 보류 중에 소스를 고쳐 우회하지 않는다. 사용자 승인 없이 패키지를 설치하거나 서비스를 켜지 않는다.
• 원장(~/.samcheonpo/ledger.db), 수락 기록, .samcheonpo/snapshots를 지우거나 직접 고치지 않는다.
• 프로젝트 설정으로 외부 전송·외부 프로그램·실험 모드를 켜거나 군집 예산을 늘리지 않는다.
• 삼천포 판정을 근거로 효과나 절감을 주장하지 않는다. 효과는 아직 입증되지 않았다.