agent-purge란 무엇인가
agent-purge는 여러 Coding Agent를 위한 시스템 프롬프트 관리 도구입니다. Agent마다 시작 인자, 설정 파일, Hook 또는 플러그인을 통해 프롬프트를 읽는 방식이 다를 수 있지만, agent-purge는 이러한 차이를 추상화하여 사용자가 동일한 Persona 콘텐츠를 기준으로 주입, 전환 및 철회를 수행할 수 있도록 합니다.
프로젝트는 세 가지 모드를 지원합니다.
- replace: Persona 본문으로 대상 시스템 프롬프트를 대체합니다.
- append: 기존 프롬프트 뒤에 Persona 본문을 추가합니다.
- off: 주입을 비활성화하고 변경 사항을 철회합니다.
모드는 즉시 전환할 수 있습니다. Web 전역 스위치를 끄거나 --mode off를 사용하면 도구가 관련 변경 사항을 원래 상태로 복원하며, 관리되는 주입 잔여물을 남기지 않습니다.
핵심 메커니즘과 기능
세 가지 통합 채널
agent-purge는 서로 다른 Harness에 대응하기 위해 세 가지 채널을 사용합니다. 세 채널 모두 최종적으로 현재 personas/<id>.md 파일의 본문을 사용합니다.
- install: 대상 Harness에 관리되는 설정 블록을 기록하며, Markdown, Hooks 또는 플러그인 메커니즘을 사용할 수 있습니다. 상시 설정에 해당하므로 다른 사용자가 해당 Harness를 직접 시작해도 적용됩니다.
- shim: 동일한 이름의 명령 셸을
PATH앞에 배치한 뒤 호출을agent-purge <h>로 전달하여 직접 입력한 원래 명령을 인계합니다. - slash: 세션에서
/purge on,/purge off또는/purge status를 사용해 즉시 전환하며, 디스크 설정은 수정하지 않습니다.
로컬 저장과 가역성
프로젝트는 프롬프트와 관련된 위치만 수정하며, 바이너리 파일을 수정하거나 라이선스를 해독 또는 우회하지 않습니다. 상태는 로컬 컴퓨터의 state.json에 저장되며 업로드되지 않습니다. 제거, 인계 해제 또는 모드 종료를 통해 원래 상태로 복원할 수 있습니다.
agent-purge uninstall <h>
agent-purge disarm
agent-purge <h> --mode off구체적인 Harness에서 지원하는 채널은 로컬 런타임 감지 결과를 기준으로 판단해야 합니다.
설치 전제 조건
agent-purge를 실행하려면 Node.js 20 이상이 필요합니다. 프로젝트 자체에는 종속성이 없으며, npm으로 전역 설치하거나 npx를 사용해 Web 콘솔을 바로 열 수 있습니다.
설치 및 최초 실행
방법 1: 전역 설치
npm i -g agent-purge설치가 완료되면 다음 명령을 바로 실행할 수 있습니다.
agent-purge web로컬 콘솔의 기본 주소는 http://127.0.0.1:7788입니다. 브라우저에서 해당 주소를 열면 Persona, Harness 상태 및 전역 스위치를 확인하고 관리할 수 있습니다.
방법 2: npx로 시작
먼저 전역 설치를 진행하지 않으려면 다음 명령을 바로 실행할 수 있습니다.
npx agent-purge web데이터 디렉터리
설정과 Persona는 npm 패키지 디렉터리에 저장되지 않으므로 패키지를 업그레이드해도 사용자 데이터가 덮어쓰이지 않습니다. 기본 위치는 다음과 같습니다.
- Linux 및 macOS:
~/.agent-purge/ - Windows:
C:\Users\<사용자>\.agent-purge\
디렉터리에는 주로 state.json과 personas/가 포함됩니다. 최초 실행 시 도구는 Persona 디렉터리에 시작 템플릿인 neutral.md를 생성합니다.
0.1.x 버전을 사용한 적이 있다면 새 버전을 처음 실행할 때 패키지 디렉터리에 있던 기존 데이터를 자동으로 마이그레이션하며, 원본 파일은 보존합니다.
사용자 지정 데이터 저장 위치
AGENT_PURGE_HOME 환경 변수로 별도의 데이터 디렉터리를 지정할 수 있습니다. Persona를 백업하거나 작업 환경을 구분하거나 설정을 다른 디스크에 저장해야 할 때 유용합니다.
Linux 또는 macOS
export AGENT_PURGE_HOME=/path/to/your/dataWindows
setx AGENT_PURGE_HOME D:\ap-data설정한 후에는 새 터미널 세션에서 agent-purge를 실행해야 환경 변수가 적용됩니다.
Persona 이해 및 관리
각 Persona는 하나의 personas/<id>.md 파일에 대응합니다. 파일은 Frontmatter와 본문으로 구성되며, 본문이 시스템 프롬프트에 실제로 기록되는 내용입니다.
Frontmatter는 다음 필드를 지원합니다.
- description: Persona 설명으로, Web 목록과
agent-purge ls출력에 표시됩니다. - desc: 이전 버전의 설명 필드로, 여전히 호환됩니다.
- order: 선택적 정렬 정보입니다.
- harness: 선택적 Harness 일치 정보입니다.
- model: 선택적 모델 일치 정보입니다.
Web 콘솔에서 이름과 설명만 수정하면 다른 Frontmatter 키는 보존되며 전체가 덮어쓰이지 않습니다.
Persona 목록 보기
agent-purge ls이 명령은 모든 Persona를 나열하고 현재 일치하는 항목을 표시합니다. 또한 실행 중 감지된 Harness 설치 상태, 버전, 주입 계층 및 각 채널의 사용 가능 여부도 보여 줍니다.
현재 Persona 전환
agent-purge use <id>여기서 <id>는 personas/ 디렉터리에 있는 Persona 파일의 이름 식별자입니다. 전환 후에는 이후의 관리 대상 호출에서 해당 Persona를 사용합니다.
한 번의 호출에만 Persona 지정
현재 전역 선택을 변경하지 않고 이번 호출에서만 다른 Persona를 지정하려면 다음 명령을 사용합니다.
agent-purge pi --persona <id>이 방식은 서로 다른 프롬프트의 효과를 임시로 테스트할 때 적합합니다. 호출이 끝난 후에는 해당 Persona가 이후 호출의 기본 선택으로 설정되지 않습니다.
기본 사용 예시
Web 콘솔 시작
agent-purge web그런 다음 http://127.0.0.1:7788에 접속합니다. 콘솔에서 실행 상태를 확인하고 전역 스위치를 조작할 수 있습니다. 전역 스위치를 끄면 주입이 철회됩니다.
현재 Persona로 Codex 시작
agent-purge codexagent-purge는 해당 Backend와 로컬 실행 환경에 따라 시작을 처리하고, 해당 Harness에서 실제로 사용할 수 있는 메커니즘을 통해 현재 Persona를 적용하려고 시도합니다.
pi에 일회성 질문 보내기
agent-purge pi --ask "이 프로젝트의 오류 처리 로직을 확인해 주세요"이 명령은 현재 Persona로 한 번의 호출을 시작하고 --ask 뒤의 내용을 이번 질문으로 전달합니다.
세션 내 즉시 전환
Slash 채널을 지원하는 Harness에서는 세션 내에서 다음 명령을 사용할 수 있습니다.
/purge on
/purge status
/purge off/purge on: Persona 주입을 활성화합니다./purge status: 현재 상태를 확인합니다./purge off: 주입을 끄며 디스크 설정은 수정하지 않습니다.
주입이 실제로 적용되었는지 확인하는 방법
matrix.json에는 정적 기능 매트릭스가 저장되지만, 정적 선언이 현재 컴퓨터의 실제 상태와 항상 일치하는 것은 아닙니다. 버전 차이, 설치 방식 및 Harness 자체의 변경이 채널 사용 가능 여부에 영향을 줄 수 있습니다.
따라서 먼저 agent-purge ls 또는 Web 콘솔에서 제공하는 런타임 정보를 확인해야 합니다. 다음 정보를 확인할 수 있습니다.
- Harness가 설치되어 있는지 여부.
- 감지된 Harness 버전.
- 프롬프트가
SYS또는USER주입 계층에 있는지 여부. install,shim및slash세 채널의 사용 가능 여부.
정적 기능 표와 런타임 감지 결과가 충돌하면 런타임 결과를 우선합니다.
고급 사용 팁
작업별로 여러 Persona 준비
personas/ 아래에 여러 Markdown 파일을 관리할 수 있습니다. 예를 들어 코드 리뷰, 리팩터링 제안 또는 일상적인 개발 협업용으로 각각 사용할 수 있습니다. description에 용도를 명확히 작성하고 order로 표시 순서를 조정할 수 있으며, 일치 범위를 제한해야 할 때는 harness 또는 model 필드를 사용할 수 있습니다.
전환하기 전에 다음을 실행합니다.
agent-purge ls대상 Persona를 확인한 후 다음을 실행합니다.
agent-purge use <id>장기 설정과 임시 실험 구분
- 상시 적용이 필요하면 대상 Harness가 지원하는 install 채널을 사용합니다.
- 원래 명령을 직접 입력해도 agent-purge가 인계하도록 하려면 shim 채널을 사용합니다.
- 현재 세션에서만 테스트하려면 slash 채널 또는 일회성
--persona인자를 우선 사용합니다.
특정 채널을 사용할 수 있는지는 여전히 런타임 감지 결과를 기준으로 판단해야 합니다.
수정 전에 복구 경로 확보
프로젝트가 상태를 저장하고 되돌릴 수 있는 작업을 제공하더라도, 실제 사용 전에는 현재 Persona, 대상 Harness 및 활성화 모드를 확인하는 것이 좋습니다. 테스트가 끝나면 다음 방식으로 철회할 수 있습니다.
agent-purge uninstall <h>
agent-purge disarm--mode off로 전환하거나 Web 콘솔에서 전역 스위치를 끌 수도 있습니다.
원래 상태로 시작한 것을 주입 성공으로 오해하지 않기
시스템 프롬프트가 서버 측에 있거나 폐쇄형 바이너리에 포함된 폐쇄 소스 데스크톱 클라이언트의 경우, agent-purge는 원래 상태로 시작만 하며 프롬프트 주입을 수행하지 않습니다. agent-purge <h>를 실행하면 도구가 주입할 수 없는 이유를 명확히 출력하며, 이미 적용된 것처럼 위장하지 않습니다.
프로젝트 구조 개요
bin/: CLI 진입점.lib/: 상태, Persona, 주입, 채널 및 감지 로직.backends/: 각 Harness의 시작 인자와 신원 문장 처리.web/: 로컬 콘솔로,server.mjs와ui.html을 포함합니다.bench/: 주입 성공률 실측 및 판정 스크립트. 개발에만 사용되며 정상 실행에는 참여하지 않습니다.matrix.json: 정적 기능 매트릭스.
보안, 개인정보 보호 및 준수 범위
agent-purge는 사용자가 관리 권한을 가진 로컬 공식 Harness를 대상으로 하며, 프롬프트 엔지니어링과 견고성 평가에 사용됩니다. 바이너리 파일을 수정하지 않고, 권한 부여를 우회하지 않으며, 로컬 상태를 외부로 업로드하지 않습니다. 또한 권한이 없는 시스템에서 사용해서는 안 됩니다.
- 본인이 제어할 권한이 있는 장치, 소프트웨어 및 규정을 준수하는 실험 환경에서만 사용해야 합니다.
- 무단 공격, 취약점 악용, 데이터 탈취, 불법 침입 또는 악성 페이로드 유포에 사용해서는 안 됩니다.
- 관련 법률 및 규정, 모델 서비스 약관과 오용 방지 정책을 위반해서는 안 됩니다.
- 이 프로젝트는 MIT 라이선스에 따라 “있는 그대로” 제공되며, 사용자는 자신의 입력, 출력 및 사용 행위에 책임을 져야 합니다.
- 프로젝트 이름, 아이디어, 코드 또는 프롬프트를 차용할 때는 저장소의 고지에 따라 출처를 밝히고 저작자를 표시해야 합니다.
README에는 특정 지역의 서버와 웹사이트에 대한 접근도 엄격히 제한되어 있습니다. 실제로 사용하기 전에 저장소의 면책 및 규정 준수 고지를 모두 읽고, 작업 범위가 해당 요구 사항을 충족하는지 확인해야 합니다.
요약
agent-purge는 여러 Coding Agent에서 서로 달랐던 프롬프트 진입점을 Persona, install, shim 및 slash 등의 개념으로 통합하고, Web 콘솔, 실행 중 감지 및 되돌릴 수 있는 철회 기능을 제공합니다. 처음에는 도구를 설치하고 Web 콘솔을 연 다음 agent-purge ls를 실행해 지원 현황을 확인하고, Persona를 선택해 대상 Harness를 시작할 수 있습니다. 일시적인 실험에는 단일 Persona 또는 세션 핫 스위칭을 우선 사용하고, 장기 구성에는 실행 중 기능과 규정 준수 범위를 확인한 후 상시 채널을 활성화해야 합니다.