senpi는 무엇을 보고 판단하는가

1. 한 장 요약

senpi의 판단 장치는 매 턴 새로 조립되는 시스템 프롬프트 한 장입니다. 상류 pi-mono의 정적 프롬프트를 걷어내고, 블록을 함수로 쪼개 순서대로 쌓습니다. 이 순서 자체가 설계 의도입니다 — 먼저 의도를 못 박고, 병렬로 긁어모으고, 언제 멈출지 정하고, 그다음에야 검증 기준을 준다.

가재코드가 워크플로 네 단계로 판단을 강제했다면, senpi는 같은 일을 프롬프트 블록과 런타임 훅으로 합니다. 무엇을 강제하려는지는 놀랄 만큼 겹치고, 강제하는 방법이 정반대입니다. 그 비교가 이 글의 마지막 절입니다.

2. 판단 규칙이 놓인 자리

npm 전역 설치본에 컴파일된 JS가 소스맵과 함께 그대로 들어 있습니다. 난독화가 없어서 프롬프트 문자열을 원문으로 읽을 수 있습니다. 이 글의 인용은 전부 그 파일들에서 가져왔습니다.

3. 턴이 열릴 때: 의도 게이트

senpi에서 가장 특징적인 장치입니다. 모든 메시지는 라우팅 한 줄로 시작해야 합니다.

핵심은 뒤 문장입니다. 읽었다고 해서 만들기로 한 게 아니다. 에이전트가 "설명해줘"를 "고쳐줘"로 착각해 파일을 건드리는 사고를 표 하나로 막습니다.

여기에 요청 종류별 범위 규칙이 붙습니다.

• 사소함 — 그냥 답한다.
• 명시적 — 시킨 것만 정확히. 추가 범위 금지.
• 탐색적 — 제안이나 변경 전에 관련 코드를 먼저 본다.
• 열린 요청 — 목표를 완전히 만족시키는 가장 짧은 경로를 택한다.
• 모호함 — 모호함을 이름 붙여 말하고, 가능한 한 맥락에서 스스로 해소한다.

그리고 게이트가 두 개 더 있습니다. 턴-로컬 의도 리셋은 매 턴 사용자의 마지막 발화를 백지에서 다시 읽고, 방향이 바뀌었으면 이전 계획을 버리라고 지시합니다 — 대기 중인 후속 지시와 조종 메시지가 이전 의도를 이깁니다. 컨텍스트 완결 게이트는 반대 방향의 브레이크입니다: 답이 코드·테스트·런타임 동작에 달렸으면 먼저 조사하되, 맥락이 충분해지면 그만 뒤지고 실행하라.

4. 근거를 모으는 방식

멈출 조건을 먼저 정한다

에이전트 프롬프트 대부분은 "충분히 조사하라"만 말하고 언제 그만둘지를 안 말합니다. 그 결과가 같은 파일을 여섯 번 읽는 토큰 낭비죠. senpi는 중단 조건을 세 개로 못 박았고, 재탐색의 정당한 사유까지 한정했습니다. 짧지만 이 문단이 이 프로젝트에서 제일 밀도가 높습니다.

대신 한 번에 넓게 긁는다

"값이 필요할 때만 순차로. 빠진 파라미터를 플레이스홀더로 채우지 마라"까지 붙어 있습니다. 모르는 인자를 그럴듯하게 지어내는 실패를 정면으로 겨냥한 문장입니다.

기억이 아니라 기록에서 꺼낸다

todo 도구 계약에도 같은 불신이 박혀 있습니다. 작업은 자동 생성 ID가 아니라 내용 문자열 그대로로 지목해야 하고, 정확한 텍스트를 잊었으면 view로 목록을 다시 받아 축어 복사해야 합니다 — 기억으로 재입력하는 건 금지입니다. 사용자가 다단계 계획을 주면 모든 항목을 각각의 작업으로 등록해야 하고, "중요한 것만 골라" 요약하거나 나머지를 머릿속에 두는 건 명시적으로 막혀 있습니다.

덤: todo 호출만 단독으로 한 턴을 쓰는 것도 금지입니다("왕복 낭비"). 실제 작업과 같이 묶어 보내라고 못 박습니다.

5. 검증: 범위는 나누되 엄격함은 안 나눈다

그 아래에 테스트 규율 6조가 붙습니다. 전부 "테스트가 운으로 통과하는 것"을 막는 조항입니다.

• 테스트 코드를 읽거나 고칠 때 비결정성은 버그로 취급한다. 타이밍 운으로 통과해선 안 된다.
• 시간 자체가 검증 대상이 아닌 한 고정 sleep·폴링 지연·시간 대기 패턴 금지.
• 비동기는 액션을 트리거하기 전에 정확한 이벤트/상태 변화를 구독하고, 바운드된 타임아웃으로 그 신호를 기다린다.
• 목(mock)은 검증하려는 계약을 보존해야 한다. 대상 통합이 실패할 수조차 없을 만큼 격리하지 마라.
• 프롬프트 테스트는 문장을 그대로 고정하지 말고 동작·결정·구조·파싱된 규칙 데이터를 단언한다.
• 관련 테스트 명령을 한 번 돌리고 그 통과를 신뢰할 수 있게 만든다(단일 실행 통과).

마지막 문장이 실무적으로 중요합니다. 기존 실패까지 떠안고 고치려다 범위가 폭발하는 걸 막고, 동시에 그걸 조용히 덮는 것도 막습니다.

6. 모를 때 · 넘칠 때

senpi의 불확실성 처리는 "묻기"가 아니라 금지 + 브레이크로 되어 있습니다.

1. 모르면 읽는다, 알면 멈춘다

   컨텍스트 완결 게이트: 답이 코드·테스트·런타임에 달렸으면 먼저 조사한다. 충분해지면 브라우징을 계속하지 말고 행동한다.

2. 읽지 않은 것은 말하지 않는다

   하드 블록: "읽거나 검증하지 않은 코드·테스트·런타임 동작에 대해 절대 추측하지 마라." 환각 보고를 정책 레벨에서 차단합니다.

3. 커밋은 명시적 요청 없이는 절대

   나머지 두 하드 블록도 같은 성격입니다: 타입 에러·린트 경고·테스트 실패를 우회하려고 억누르지 마라.

4. 막혔을 때 하지 말아야 할 것 3종

   실패하는 테스트를 지우거나 스킵해서 초록불 만들기, 의도 없이 에러 조용히 삼키기, 무관한 편집과 맹목적 재시도로 산탄총 디버깅 하기.

5. 계획이 막히면 todo에 적는다

   "Blocked? 활성 단계에 작업을 추가하거나 drop하라." 막혔다는 사실 자체를 상태로 남기게 합니다.

6. 맥락이 넘치면 요약하되, 원문은 지키게 한다

   압축 요약기는 "COMPACTION ARCHIVIST" 역할을 받고 규칙 네 개를 받습니다: 사용자 요청과 제약은 축어로 인용(의역 금지), 내용이 없는 섹션도 "None."으로 남기고 삭제 금지, 이전 요약의 요청·최종 목표·제약은 불변(덧붙이기만), 세션 ID·파일 경로·식별자는 바이트 단위로 보존. 산출 형식은 7개 섹션 고정(요청 축어 → 최종 목표 → 제약 → 완료한 일 → 활성 작업 맥락 → 남은 작업 → 정확한 다음 단계).

7. 압축 자체가 폭주하지 않게 막는다

   적응형 임계는 컨텍스트의 40~70% 사이에서만 움직이고(수확이 좋으면 늦추고 나쁘면 당김), 투기적 압축은 임계의 75% 지점에서 미리 돕니다. 실패가 3회 쌓이면 서킷 브레이커가 60초 열리고, 한 턴에 소프트 캡 3회·하드 캡 10회를 넘지 못합니다.

8. 오래 걸리는 명령은 미리 잘라둔다

   bash 기본 타임아웃 120초, 권장 최대 600초. 그보다 오래 필요한 작업은 tmux 같은 백그라운드로 돌리라고 프롬프트에 박아둡니다. "명령이 영원히 도는 걸 가정하지 마라."

정리하면 senpi는 사람에게 되묻는 장치가 거의 없습니다. 모호하면 이름 붙여 말하고 맥락에서 스스로 풀라고 하고, 파괴적인 단계에서만 멈춥니다. 가재코드가 인터뷰·승인 게이트로 사람을 붙잡아 두는 것과 정확히 반대 방향의 선택입니다.

7. 권한 기본값 — 여기 주의

senpi는 opencode식 권한 시스템을 빌트인으로 옮겨왔습니다. 규칙은 도구별·패턴별로 allow/ask/deny를 정하고, TUI에서 한 번 허용 / 항상 허용 / 거부 / 사유와 함께 거부를 고르게 합니다. 잘 만들어져 있습니다.

다만 코드를 열어보면 기본 프리셋이 full-access입니다 — 즉 { permission: "*", pattern: "*", action: "allow" }. 규칙 병합 순서는 기본 프리셋 → 글로벌 설정 → 프로젝트 설정 → CLI 플래그라서, 아무것도 설정하지 않으면 권한 시스템은 켜져 있어도 전부 통과시킵니다. 저장소가 컨테이너 경계를 제공하지 않는다고 밝힌 것과 같은 맥락입니다.

# 이번 실행만
senpi --permission-preset workspace

# 프로젝트에 고정: .senpi/settings.json
{ "permission": { "bash": "ask", "edit": "ask" } }

평가: 기본값을 열어두는 선택 자체는 이 도구의 성격(자기 작업 머신에서 빠르게 굴리는 러너)과 일관됩니다. 문제는 권한 시스템이 있다는 사실이 기본이 안전하다로 읽히기 쉽다는 점입니다. 남의 코드·회사 저장소에 붙일 거라면 프리셋을 먼저 바꾸고 시작하세요.

8. 가재코드와 비교 — 같은 병, 다른 처방

앞선 해부와 나란히 두면 재미있습니다. 두 프로젝트가 겨냥하는 실패는 똑같습니다: 에이전트가 확인하지 않은 것을 확인한 것처럼 보고한다. 처방이 정반대입니다.

어느 쪽이 낫냐는 일의 되돌리기 비용에 달렸습니다. 되돌리기 쉬운 내 저장소의 일상 작업이면 senpi 쪽이 훨씬 빠르고 덜 성가십니다. 되돌리기 비싼 일(마이그레이션, 인증, 공개 API 변경)에는 가재코드처럼 승인과 증거를 파일로 남기는 구조가 값을 합니다.

비판

• 프롬프트는 계약이 아니라 부탁입니다. "검증 없이 깨끗하다고 보고하는 건 위반"이라고 써 있어도, 위반을 막는 코드는 없습니다. 가재코드는 게이트 JSON을 CLI가 거부하죠. senpi에서 이 규율이 지켜지는지는 모델 성실성에 달렸습니다.
• 기본값이 전부 허용입니다. 권한 시스템이 있다는 사실과 안전한 기본값은 별개입니다.
• 포크 유지 비용. 상류 pi-mono를 주기적으로 리베이스하는 구조라, changes.md 규율이 있어도 상류가 크게 움직이면 흔들릴 여지가 있습니다.
• 실험 단계. 저장소가 스스로 "프로덕션 파이프라인을 걸지 말라"고 못 박았고, 설치 시 ~/.pi/agent를 ~/.senpi/agent로 통째 이관합니다(상류 pi 사용자는 백업 먼저 — 리뷰에 실측 기록).

그럼에도 배울 게 분명합니다. 특히 탐색 중단 조건과 검증 티어링은 다른 에이전트를 쓰든 자기 프롬프트에 그대로 옮겨 적을 만한 두 문단입니다.

9. 직접 확인해보기

설치돼 있다면 이 글의 인용은 전부 자기 디스크에서 확인됩니다.

npm install -g @code-yeongyu/senpi
senpi --version

# 설치 경로
cd "$(npm root -g)/@code-yeongyu/senpi/dist/core"

cat dynamic-prompt/build.js          # 프롬프트가 어떤 순서로 조립되는지
cat dynamic-prompt/intent-gate.js    # 의도 게이트 전문
cat dynamic-prompt/exploration.js    # 탐색 중단 조건 (제일 짧고 제일 밀도 높음)
cat dynamic-prompt/verification.js   # V1·V2·V3 + 테스트 규율 6조
cat dynamic-prompt/policies.js       # 하드 블록 3 + 안티패턴 3
cat dynamic-prompt/style.js          # 실행 스탠스

# 권한 기본값 확인 (여기 주의)
grep -n "DEFAULT_PERMISSION_PRESET" -A 20 extensions/builtin/permission-system/config.js

# 압축 상수
head -8 extensions/builtin/compaction/policy.js
cat extensions/builtin/compaction/circuit-breaker.js | head -3