Claude Code를 매일 사용하다 보니 새 코딩 에이전트가 나오면 작은 저장소에서 시험한다. Pi Coding Agent는 완성된 워크플로우를 강하게 제시하는 제품보다 사용자가 하네스를 구성할 수 있는 툴킷에 가깝다. 짧은 시간 저장소를 읽고 작은 수정을 맡기면서 코어와 확장 경계를 살폈다.
프로젝트도 변했다. 처음 참고한 badlogic/pi-mono 주소는 현재 earendil-works/pi로 이동한다. 공식 저장소는 프로젝트를 Pi Agent Harness라고 소개하며 coding agent CLI, agent runtime, 다중 제공자 LLM API, 터미널 UI 패키지를 함께 관리한다. 제품 기능을 설명할 때는 현재 문서와 버전을 확인해야 한다.
작은 실험으로 첫 인상을 제한했다
30분 사용으로 장시간 안정성과 생태계를 평가할 수 없다. 첫 실험의 범위를 다음처럼 정했다.
작업: 문서의 잘못된 링크 하나 수정
허용 파일: README와 링크 검사 테스트
금지: 패키지 설치, 외부 서비스 쓰기, Git push
완료: diff 확인, 테스트 통과, 변경 이유 설명
나는 설치 성공과 첫 답변 속도를 점수로 삼지 않았다. 도구가 어떤 파일을 읽고 어떤 명령을 실행했는지, 작업 범위를 지켰는지 봤다. 오류가 생겼을 때 로그와 세션에서 원인을 찾을 수 있는지도 확인했다.
짧은 실험에서 얻은 결과는 사용한 모델과 저장소, 당시 Pi 버전에 묶여 있다. 다른 모델 제공자와 큰 monorepo에서도 같은 결과가 나온다고 확대하지 않는다.
Pi 저장소를 네 패키지로 읽었다
현재 공식 README는 주요 구성을 다음처럼 나눈다.
| 패키지 | 역할 |
|---|---|
pi-coding-agent | 대화형 코딩 에이전트 CLI |
pi-agent-core | 도구 호출과 상태를 다루는 agent runtime |
pi-ai | OpenAI, Anthropic, Google 등을 위한 통합 LLM API |
pi-tui | 터미널 사용자 인터페이스 라이브러리 |
이 분리는 모델 호출과 agent loop, 사용자 인터페이스를 따로 이해하게 해 준다. 범용 코딩 CLI를 그대로 사용하거나 core와 AI 패키지로 좁은 전용 에이전트를 만들 수 있다.
오픈소스 저장소에서는 프롬프트와 도구 구현, 상태 관리 방식을 읽을 수 있다. 특정 행동이 어디에서 결정됐는지 추적하고 필요한 부분을 확장할 여지가 있다. 코드를 읽을 수 있다는 사실만으로 안전성이 증명되지는 않는다. 실제로 사용하는 버전과 의존성, 확장 코드를 검토해야 한다.
확장 전에 기본 행동을 기록한다
Pi의 확장 가능성은 매력적이지만 첫날부터 기능을 추가하지 않는다. 기본 상태에서 다음 행동을 기록한다.
어떤 파일을 자동으로 컨텍스트에 넣는가
셸 명령을 실행하기 전에 무엇을 보여 주는가
도구 오류를 다음 모델 입력에 어떻게 전달하는가
세션을 저장하고 다시 여는 방법은 무엇인가
모델을 바꿀 때 도구 스키마가 유지되는가
로그에 프롬프트와 비밀 값이 남는가
기준선을 만든 뒤 확장 하나를 추가하고 같은 작업을 실행한다. 여러 확장을 함께 설치하면 어느 코드가 파일과 네트워크에 접근했는지 찾기 어렵다.
전용 블로그 검증 에이전트를 만든다면 도구 이름과 입력을 좁게 둔다.
source_read 허용한 URL과 메타데이터만 읽기
draft_save 지정한 content/drafts 폴더에 저장
link_check 원고의 HTTPS 링크 상태 확인
publish_preview DB 변경 예정 행과 diff 출력
publish_preview는 실제 게시 권한을 갖지 않는다. 사람 승인을 받은 별도 명령이 상태를 변경한다. 도구가 적다는 사실보다 각 도구의 경로와 외부 효과가 제한됐는지가 중요하다.
내장 권한 시스템이 없다는 문장을 먼저 봤다
현재 Pi README는 파일시스템과 프로세스, 네트워크, 자격증명 접근을 제한하는 내장 권한 시스템이 없다고 명시한다. Pi는 실행한 사용자와 프로세스의 권한으로 동작한다. 작은 코어를 제한된 권한으로 오해하면 위험하다.
운영 키를 가진 사용자 계정에서 Pi를 실행하면 에이전트와 확장도 그 권한에 접근할 수 있다. 저장소가 공개돼 있고 코드가 짧아도 OS 권한은 자동으로 줄어들지 않는다.
공식 문서는 더 강한 경계가 필요할 때 micro-VM 확장, Docker, 정책 기반 sandbox 같은 containerization 패턴을 안내한다. 나는 첫 실험에서 다음 경계를 둔다.
- 복사한 샘플 저장소와 테스트 데이터만 마운트한다.
- 운영
.env와 SSH 키를 전달하지 않는다. - 외부 쓰기가 필요 없으면 네트워크를 제한한다.
- 생성 파일과 실행 명령을 로그에서 검토한다.
- 컨테이너 밖의 삭제와 배포를 도구로 노출하지 않는다.
샌드박스도 만능 경계가 아니다. 마운트한 폴더와 네트워크 허용 목록이 넓으면 피해 범위가 커진다. 컨테이너 설정을 코드와 함께 검토한다.
확장 패키지를 코드로 검토한다
확장은 셸과 파일, 네트워크를 호출할 수 있다. 설치 전 다음 항목을 확인한다.
저장소와 유지관리자
최근 변경과 배포 태그
직접·간접 의존성
설치 스크립트와 lifecycle script
읽고 쓰는 경로
외부 요청 도메인
로그와 telemetry
업데이트와 제거 방법
버전을 고정하고 lockfile을 보관한다. 새 버전으로 올릴 때 diff와 권한 변화를 본다. 확장의 설명문이 “읽기 전용”이라고 써 있어도 실제 도구 구현에서 쓰기와 명령 실행을 확인한다.
테스트가 없는 작은 확장은 샘플 컨테이너에서 실행한다. 홈 디렉터리와 운영 자격증명에 접근할 수 있는 환경에서 처음 실행하지 않는다.
모델과 하네스를 분리해서 비교한다
Pi의 pi-ai는 여러 모델 제공자를 위한 통합 API를 제공한다. 같은 agent loop에서 모델을 바꿔 볼 수 있다는 점은 하네스와 모델의 영향을 구분하는 실험에 유용하다.
모델을 바꿔도 같은 결과를 기대하지 않는다. 컨텍스트 크기와 도구 호출, 지시 준수, 응답 속도와 가격이 다르다. 제공자별 인증과 데이터 처리 조건도 확인해야 한다.
고정된 작업 묶음으로 비교한다.
| 항목 | 측정 방법 |
|---|---|
| 완료율 | 같은 테스트와 검토 기준 통과 여부 |
| 범위 준수 | 허용 목록 밖의 변경 파일 수 |
| 복구 | 오류 뒤 성공까지 필요한 재시도 |
| 비용 | 모델 비용과 실행 인프라 비용 |
| 검토 | 사람이 diff를 읽고 고친 시간 |
| 안정성 | 같은 입력의 결과 편차 |
토큰 가격이 낮아도 사람이 수정하는 시간이 길면 작업 비용이 커진다. 비싼 모델이 긴 작업에서 재시도를 줄일 수도 있다. “편집용 저가 모델, 설계용 고가 모델” 같은 규칙은 내 작업 샘플의 결과가 쌓인 뒤 정한다.
세션과 실패 복구를 시험한다
코딩 에이전트는 성공한 한 번보다 중단 뒤 복구가 중요하다. 다음 상황을 의도적으로 만든다.
테스트 명령 실패
모델 요청 중 네트워크 종료
컨텍스트가 긴 세션
작업 중 프로세스 재시작
확장이 잘못된 경로 반환
모델 제공자 전환
세션 기록이 어느 경로에 남고 비밀 값이 포함되는지 확인한다. 재시작한 에이전트가 현재 Git 상태와 완료된 검사, 남은 작업을 읽을 수 있는지도 본다. 복구 과정에서 같은 파일을 처음부터 다시 쓰거나 외부 요청을 중복 실행하지 않아야 한다.
실패 시 사람이 읽을 수 있는 로그와 제거 절차가 없다면 운영 작업에 사용하지 않는다. 개인 실험과 장기간 자동화의 요구 수준은 다르다.
기존 메인 도구를 유지한 이유
Claude Code와 Codex에는 내가 익숙한 지침 파일과 승인 흐름, 검토 방식이 있다. 도구 전환 비용은 CLI 설치 시간보다 저장소 규칙과 권한, 검사 절차를 다시 검증하는 시간에서 나온다.
Pi의 짧은 실험만으로 장시간 작업과 복구, 확장 생태계를 평가할 수 없었다. 익숙한 대규모 저장소에서는 기존 도구를 유지하고, Pi는 범위가 좁은 검증 에이전트에서 더 시험하는 편이 안전했다.
메인 도구를 바꾸려면 같은 작업 묶음에서 다음 조건을 확인한다.
- 성공률과 사람 검토 시간이 기존 도구와 비슷하다.
- 권한 경계를 샌드박스에서 재현할 수 있다.
- 세션 중단과 모델 오류에서 복구된다.
- 팀이 설치와 업데이트, 제거 절차를 이해한다.
- 필요한 확장의 코드와 의존성을 검토했다.
Pi의 작은 코어는 내가 에이전트 하네스를 조립하고 모델을 비교할 공간을 준다. 사용자가 OS 수준 경계를 준비해야 한다는 책임도 함께 준다. 다음 실험에서는 블로그 링크와 frontmatter만 검사하는 에이전트를 만들고, 외부 게시 권한 없이 여러 모델의 완료율과 검토 시간을 비교할 생각이다.