TL;DR

  • Papercut은 지정된 SDK, CLI 또는 제품을 사용하는 코딩 에이전트의 어려움을 기록해 제품 관리자가 개선 여부를 확인하는 도구임.
  • 에이전트는 시도한 작업, 기대한 결과, 실제 결과와 우회 방법을 제품 식별자와 함께 보고하며, 보고서에는 제품 버전과 표면 영역도 선택적으로 포함됨.
  • 여러 소비 저장소의 보고서는 하나의 비공개 저장소에 모이며, 제품 이름은 명시적으로 지정하고 현재 Git 저장소는 사용 위치를 나타냄.
  • list, show, triage-pack으로 보고서를 검토하고 관련 사례를 묶어 제품이나 문서를 개선한 뒤 해결 참조를 기록함.
  • 제품에 귀속되지 않은 과거 보고서는 그대로 보존되며, 제품을 추측해 연결하지 않고 새 광범위 신호 수집도 중단된 상태임.

Papercut

  • Papercut은 코딩 에이전트가 SDK, CLI 또는 관심 제품을 사용하는 과정에서 어려움을 겪는 지점을 제품 관리자가 확인하도록 지원함.
  • 에이전트는 지정된 제품을 사용하면서 시도한 내용, 기대한 결과, 실제로 발생한 결과와 우회 방법을 기록함. 제품 관리자는 보고서를 검토하고 제품을 개선한 뒤 후속 작업이 쉬워졌는지 확인함.
  • 서로 다른 소비 저장소의 보고서는 하나의 비공개 저장소에 보관됨. 제품은 명시적으로 이름을 지정하고, 현재 Git 저장소는 제품을 사용한 위치를 알려줌.

설치

  • Rust와 Cargo를 설치한 뒤 cargo install papercut-cli --locked, papercut install --yes, papercut doctor 순서로 실행함.
  • 크레이트 이름은 papercut-cli이고 설치되는 명령은 papercut임. ~/.cargo/bin이 PATH에 포함되어 있어야 하며, 체크아웃에서 빌드할 때는 cargo install --path . --locked를 사용함.
  • install은 감지된 에이전트의 전역 지침 파일에 짧은 안내를 추가하고 이전 Papercut 실패 명령 훅을 제거함. 설치 후 에이전트 세션을 다시 시작해야 갱신된 안내를 읽음.
  • v0.1.0에서 업그레이드할 때는 새 안내에서 --product를 요구하므로 install --yes를 실행하기 전에 바이너리를 교체해야 함.

제품 지정 및 사용

  • 에이전트에게 일반 작업과 안정적인 제품 ID를 제공함. 예를 들어 @nibzard/example-sdk를 사용해 애플리케이션의 모든 항목을 나열하도록 요청하고, 작업 중 해당 SDK를 Papercut으로 관찰하도록 안내함.
  • SDK의 공개 인터페이스 때문에 작업이 어려워지면 papercut add --product '@nibzard/example-sdk' --product-version 0.4.0 --surface 'Client.items.list' -- '...' 형식으로 보고서를 추가함. 예시 보고서는 페이지 매김 안내 때문에 list()가 다음 페이지 커서를 반환할 것으로 예상했지만 배열만 반환했고, pages()를 찾는 데 세 번 시도한 뒤 작업을 마쳤다는 내용을 기록함.
  • 제품 버전과 표면 영역은 선택 항목임. 작업이 결국 성공했더라도 헷갈리는 도움말, 오해를 부르는 출력, 찾기 어려운 기능이나 사용 중 발견한 버그를 보고할 수 있음.
  • 제품과 무관한 셸 또는 컴퓨터 오류는 제품 보고서에 포함하지 않음. 제품을 지정하지 않으면 설치된 안내는 에이전트에게 부수적인 실패를 보고하도록 요청하지 않음.
  • add는 보고서 ID를 출력하며, 관찰 내용에는 제품 식별자, 소비 저장소, 작업 디렉터리, 에이전트와 시간이 함께 저장됨. 추정 원인과 제안 수정안은 각각 --hypothesis, --fix 필드에 따로 기록함.

제품 사용 검토

  • papercut list --product '@nibzard/example-sdk'로 제품 보고서를 나열하고, papercut show <id-or-ref>로 개별 보고서를 확인하며, papercut triage-pack --product '@nibzard/example-sdk' --max-tokens 8000으로 검토용 관찰 자료를 구성함.
  • 제품 보기는 별도 --repo를 추가하지 않는 한 여러 소비 저장소를 아우름. list는 상태, 경과 기간, 에이전트 필터도 지원함.
  • triage-pack은 토큰 예산 안에서 완전한 관찰 자료를 에이전트에 제공해 사람이 주도하는 검토를 지원함. 관련 관찰을 묶고 사용 경로를 확인한 뒤 제품이나 문서를 개선하고 해결 참조를 기록함.
  • 로컬 우회 방법만으로는 이후 사용자가 겪을 제품 장애가 해결됐다고 볼 수 없음.
  • 제품 식별 정보가 없는 기존 보고서는 과거 근거로 계속 이용 가능하며, papercut list --unattributed와 papercut triage-pack --unattributed --repo all로 확인함.
  • 보고서가 저장소나 명령을 바탕으로 제품에 임의 귀속되는 일은 없음. 과거 실패 명령 신호는 저장된 상태로 유지되지만, 상호작용을 제품에 귀속할 수 있는 어댑터가 마련될 때까지 새 광범위 신호 수집은 중단됨.
  • papercut sweep은 보고서 전용 모드를 설명하며 세션을 검색하지 않음.

개인정보 보호 및 출력

  • 저장소 위치는 $XDG_DATA_HOME/papercuts/이며, 기본 경로는 ~/.local/share/papercuts/임.
  • papercut render --product ID --write는 비공개 저장소 안에 투영 자료를 작성함. 일치하는 체크아웃에서 --repo .를 명시적으로 추가하면 그 위치에 PAPERCUTS.md를 작성함. 투영 자료를 게시하기 전에 비공개 보고서를 검토해야 함.
  • 모든 명령은 동일한 봉투 형태의 출력을 제공하는 --output json을 지원하며, 명령 실행 중 대화형 입력을 요청하지 않음.
  • CLI를 직접 호출할 때 성공은 종료 코드 0, 실제 실패는 1, 사용 오류는 2로 나타남. 오래된 훅 호출은 아무 출력도 내지 않으며 상위 작업을 방해하지 않음.
  • 보고서에 비밀 정보, 환경 변수 값, 대화 기록 또는 소스 파일을 포함하지 않아야 함.
  • 명령은 사용 안내서, 검토 절차는 분류 안내서, 아키텍처와 구현 기준은 계획 문서에서 확인 가능함. 개발 검증에는 cargo test와 cargo clippy --all-targets -- -D warnings를 사용함.