pi 코딩 에이전트를 위한 자동 문맥 요약을 통한 토큰 효율적인 자율 작업 실행

pi 코딩 에이전트를 위한 자동 문맥 요약을 통한 토큰 효율적인 자율 작업 실행.

/boomerang 로그인 버그 수정

에이전트가 자율적으로 작업을 수행합니다. 작업이 완료되면, 향후 문맥(context)에서 가공되지 않은 대화 기록(raw turn history)은 확장된 핸드오프 요약(handoff summary)으로 대체됩니다. 이를 통해 작업은 완료되고, 토큰은 절약되며, 요약본은 채팅에 표시되고, 오케스트레이터(orchestrator)는 요약이 포함된 독립적인 후속 턴(follow-up turn)을 즉시 전달받게 됩니다.

긴 자율 작업은 방대한 문맥을 소비합니다. 10개의 파일을 읽고, 5번의 수정을 가하며, 테스트를 실행하는 버그 수정 작업은 5만 토큰을 소모할 수 있습니다. pi-boomerang을 사용하면 LLM은 다음과 같은 내용만 보게 됩니다:

[BOOMERANG COMPLETE]
작업: "로그인 버그 수정"
결과:
...

결과는 동일하지만, 토큰 소모는 극히 적습니다. 세션 트리(session tree)는 필요한 경우 /tree 탐색을 위해 전체 기록을 보존합니다.

역전된 D-Mail: 관찰자가 기억하는 동안 D-Mail이 현실을 다시 쓰는 것과 달리, boomerang은 현실이 지속되는 동안 관찰자를 다시 씁니다. 세션 트리는 당신의 리딩 슈타이너(Reading Steiner)가 되어줍니다.

pi install pi-boomerang

그 다음, 확장을 로드하기 위해 pi를 재시작하세요.

# 일반 작업
/boomerang JWT를 사용하도록 인증 모듈 리팩토링
# 프롬프트 템플릿 실행
...

에이전트는 합리적인 가정을 바탕으로 질문 없이 작업을 수행합니다. 완료되면 모든 것이 요약 브랜치(summary branch)로 반환됩니다. 요약은 채팅에 표시되고 UI에서 확장된 상태로 유지되며, 변경된 파일, 관련 읽기 작업, 검증 명령, 실패 사례, 모델/사고/기술 설정(model/thinking/skill config), 그리고 최종 결과와 같은 운영 핸드오프 문맥(operational handoff context)을 포함합니다. 오케스트레이터에게 전달되는 숨겨진 후속 정보에는 해당 요약이 직접 포함되어 있어, 에이전트가 단지 요약을 찾기 위해 세션 로그를 검색하지 않도록 합니다.

마지막에 단 한 번의 요약 반환과 함께 여러 템플릿을 순차적으로 실행할 수 있습니다:

/boomerang /scout "코드베이스 분석" -> /planner "수정 사항 설계" -> /impl "구현하기"

각 단계는 인라인(inline)으로 자체 인자(args)를 지정할 수 있습니다. 또한 인라인 인자가 없는 단계를 위한 폴백(fallback)으로 전역 인자를 설정할 수도 있습니다:

/boomerang /scout -> /planner -> /impl -- "인증 시스템 구축"

각 템플릿의 프론트매터 (frontmatter)는 해당 단계의 모델 (model), 기술 (skill), 그리고 사고 수준 (thinking level)을 제어합니다. Scout는 Sonnet에서 실행되고, Planner는 Opus에서 실행되며, Impl은 무엇이든 실행됩니다. Boomerang은 자동으로 전환하며, 요약이 반환된 후 원래의 설정을 복구합니다.

상태 표시기 (Status indicator)는 chain 1/3, chain 2/3 등으로 진행 상황을 보여줍니다.

--rethrow N을 사용하여 전체 작업을 N번 실행하고, 각 회차 사이에 문맥을 요약할 수 있습니다:

/boomerang /deslop --rethrow 3
/boomerang "improve code quality" --rethrow 2
/boomerang /scout -> /impl --rethrow 2 -- "auth module"

Boomerang 모드에서의 작동 방식:

• N은 필수이며 1-999 사이여야 합니다. 각 회차는 다음과 같이 진행됩니다: 작업 실행 -> 문맥 요약 -> 다음 회차 시작
• 파일 변경 사항은 회차 간에 디스크에 유지됩니다.
• 각 새로운 회차는 전체 원본 대화 기록 (raw turn history)이 아닌, 이전 회차들로부터 누적된 요약본을 확인합니다.
• Rethrow는 해당 실행의 현재 리프 (leaf)에서 내부적인 자동 앵커 (auto-anchor)를 사용합니다.

상태는 rethrow 2/3로 표시되며, 체인 Rethrow의 경우 rethrow 2/3 · chain 1/2로 표시됩니다.

Boomerang에서의 --loop N 호환성:

• /boomerang ... --loop N은 /boomerang ... --rethrow N의 별칭 (alias)으로 처리됩니다.
• 두 플래그가 모두 존재하면 --rethrow가 우선하며 --loop는 무시됩니다. Boomerang은 렌더링된 작업에서 loop 메타데이터를 제거하여 내부 프롬프트 인자 (prompt args)가 --loop 토큰을 받지 않도록 합니다.
• 횟수가 없는 단독 --loop는 Boomerang에서 유효하지 않으며 --loop requires a count (1-999)를 반환합니다.

예시:

# 별칭 -> rethrow
/boomerang /deslop --loop 2
# 혼합된 플래그: --rethrow가 우선순위를 가짐
...

Rethrow 도중에는 /boomerang-cancel로 취소할 수 있습니다.

작업이 /로 시작하면, Boomerang은 이를 템플릿 참조 (template reference)로 취급합니다:

/boomerang /commit "fix the auth bug"
/boomerang /codex/review "the auth module"

템플릿은 <cwd>/.pi/prompts/에서 먼저 로드된 후, ~/.pi/agent/prompts/에서 로드됩니다. 하위 디렉토리는 경로 세그먼트 (path segments)에 매핑됩니다 (/codex/review → codex/review.md).

프론트매터 (Frontmatter) 필드:

---
model: claude-opus-4-6
skill: git-workflow
...

model — 작업 전에 전환하고 작업 후에 복구합니다.
skill

— 시스템 프롬프트 (system prompt)에 주입됩니다.
thinking

— 사고 수준 (thinking level)을 설정하며, 이후 복구됩니다.
$@

모든 인자 (args)로 확장됩니다.
$1

$2

등은 위치 인자 (positional arguments)를 위한 것입니다.

Ctrl+Alt+B를 누르거나

/boomerang auto on을 실행하여

다음 일반 제출 프롬프트 (prompt)에 대해 자동 부메랑 (auto-boomerang) 기능을 켭니다. 자동 모드에는 /review와 같은 프롬프트 템플릿 (prompt templates)이 포함되지만, /boomerang, /model, 또는 /tree와 같은 Pi 제어 명령 (Pi control commands)은 감싸지 (wrap) 않습니다.

자동 모드는 세션 전용이며 일회성입니다. 다음 프롬프트를 감싸고 나면 꺼지므로, 자동 체크포인트 (automatic checkpoint)를 원할 때마다 다시 활성화해야 합니다. 다음 프롬프트 전에 기능을 끄려면 /boomerang auto off, /boomerang auto toggle을 사용하거나 Ctrl+Alt+B를 다시 누르세요. 기능이 켜져 있고 유휴 (idle) 상태인 동안에는 푸터 (footer)에 🪃 auto가 표시됩니다. 폴백 요약 (Fallback summaries)은 /reload를 통해 채팅을 자동으로 새로고침하므로, 요약이 생성된 후에는 원본 브랜치 (raw branch) 콘텐츠가 화면에서 제거됩니다.

기본적으로 각 부메랑 (boomerang)은 자신의 작업만을 요약합니다. 여러 작업이 동일한 요약 지점을 공유하기를 원할 때는 앵커 (anchor)를 설정하세요:

/boomerang anchor # 여기에 앵커 설정
/boomerang "task A" # 앵커로 요약 A를 생성
/boomerang "task B" # 앵커로 요약 A + B를 생성
...

요약은 누적되므로, 각 작업의 문맥 (context)에는 이전 내용이 포함됩니다.

기능이 활성화되면, 확장은 에이전트 (agent)가 직접 호출할 수 있는 boomerang 도구 (tool)를 등록합니다. 두 가지 모드가 있습니다:

작업 모드 (Task mode) — 작업 문자열 (task string)을 전달하면 현재 턴 (turn)이 끝날 때 자율적으로 실행됩니다:

boomerang({ task: "refactor the auth module" })
boomerang({ task: "/deslop --rethrow 3" })
boomerang({ task: '/scout -> /impl -- "auth module"' })

명령어가 수행하는 모든 기능(템플릿, 체인, --rethrow N)을 지원합니다. 작업은 에이전트의 현재 턴이 완료된 후 큐 (queue)에 쌓이고 실행됩니다.

앵커 모드 (Anchor mode) — 작업 없이 호출하여 앵커/요약 지점 (anchor/summary point)을 전환합니다. 첫 번째 호출은 앵커를 설정하고, 두 번째 호출은 앵커 이후의 모든 내용을 요약합니다. 사용자의 개입 없이 스스로 관리되는 문맥 (self-managed context)을 구성할 때 유용합니다.

에이전트가 이를 너무 공격적으로 사용했기 때문에 **기본적으로 비활성화(Disabled by default)**되어 있습니다. 다음 명령어로 활성화할 수 있습니다:

/boomerang tool on

에이전트가 언제 이 도구를 사용해야 하는지에 대한 가이드라인을 제공할 수 있습니다:

/boomerang tool on "3개 이상의 파일을 수정하는 작업에만 사용하세요"
/boomerang guidance "리팩터링(refactoring) 또는 다단계 구현(multi-step implementations)에 사용하세요"

도구 상태(Tool state)와 가이드라인(guidance)은 재시작 후에도 ~/.pi/agent/boomerang.json에 유지됩니다.

한 가지 특이사항: 도구에 의해 시작된 앵커 요약(anchor summaries)은 UI에 즉시 업데이트되지 않을 수 있습니다 (에이전트는 요약된 문맥을 보지만, 채팅 디스플레이는 /reload를 하기 전까지 지연될 수 있습니다).

명령	기능
Ctrl+Alt+B	다음 프롬프트에 대해 자동 부메랑(auto-boomerang)을 켜거나 끕니다
`/boomerang auto [on	off
/boomerang <task>	실행 및 문맥 요약
/boomerang <task> --rethrow N	재시도(rethrow) 사이에 요약을 포함하여 전체 작업을 N번 다시 실행합니다
/boomerang <task> --loop N	부메랑 모드에서 --rethrow N의 별칭(alias)
/boomerang /<template> [args]	템플릿을 실행하고 문맥을 요약합니다
/boomerang /a -> /b -> /c	템플릿 체이닝(Chain templates)
/boomerang /a -> /b --rethrow 2	템플릿을 체이닝한 후, 전체 체인을 두 번 재시도합니다
/boomerang-cancel	요약 없이 중단
/boomerang anchor	요약 지점(summary point) 설정
/boomerang anchor show	앵커 정보 표시
/boomerang anchor clear	앵커 제거
`/boomerang tool [on	off]`
/boomerang guidance [text]	가이드라인 설정/표시/삭제

pi-context는 에이전트에게 Git과 유사한 도구를 제공하여 스스로 문맥을 관리할 수 있게 합니다. 즉, 마일스톤(milestones)을 생성하고, 토큰 사용량(token usage)을 모니터링하며, 언제 압축(squash)할지를 결정할 수 있습니다.

문제점: LLM은 리소스 제한에 대해 알게 되면 지름길을 택하려 합니다. "용량의 80%를 사용 중입니다"라는 말은 결핍 사고방식(scarcity mindset)을 유발하여, 서두르거나, 탐색을 건너뛰거나, 더 얕은 분석을 수행하게 만듭니다.

pi-boomerang은 작업 에이전트(worker agent)가 이를 인지하지 못하게 유지합니다. 에이전트는 작업을 보고 철저하게 수행하며, 요약은 보이지 않게 이루어집니다. 그 후 오케스트레이터(orchestrator)에게 결과물인 핸드오프 요약(handoff summary)을 읽도록 프롬프트가 전달됩니다.

Boomerang은 오직 *문맥/토큰 (context/tokens)*만을 요약하며, 파일 상태 (file state)에는 절대 관여하지 않습니다. 작업 중에 이루어진 모든 파일 변경 사항은 보존됩니다. 이는 의도된 설계입니다. 작업 후에 파일을 복구하는 것은 Boomerang이 방금 완료한 작업을 되돌리는 결과가 되기 때문입니다.

rewind 확장은 필요하지 않습니다. /tree 또는 /fork를 통해 이전 파일 상태를 수동으로 복구하고 싶다면 별도로 설치하십시오.

Boomerang은 독립적으로 작동합니다. Boomerang에 의해 트리거된 문맥 요약 (context summarization) 과정 중에 rewind가 프롬프트를 띄우지 않습니다.

• 요약은 휴리스틱 (heuristic) 방식입니다. 기록된 도구 호출 (tool calls) 및 결과로부터 파일 작업, 검증 명령 (validation commands), 실패 사례를 추출하므로 의미론적 세부 사항 (semantic details)을 놓칠 수 있습니다.
• 에이전트 (Agent)가 지침에도 불구하고 질문을 할 수 있습니다 (그럼에도 불구하고 Boomerang은 작업을 완료합니다).
• 앵커 상태 (Anchor state)는 메모리 내 (in-memory)에만 존재하며, 세션 시작 또는 전환 시 삭제됩니다.
• 도구에 의해 시작된 요약은 UI를 즉시 업데이트하지 않을 수 있습니다 (/reload를 사용하여 새로고침하십시오).