긴 출력
테스트·빌드 로그가 대화에 그대로 들어오면 중요한 실패 원인이 묻힙니다.
Claude Code 플러그인 · 로컬 가드레일 · 에이전트 간 규칙
ContextGuard
파일·로그·출력을 AI 컨텍스트에 넣기 전에 줄입니다.
ContextGuard는 불필요한 파일·로그·명령 출력이 AI 에이전트 컨텍스트에 들어가기 전에 줄어들도록 돕는 로컬 우선 가드레일입니다. Claude Code 플러그인으로 바로 시작하고, 적용 전에는 읽기 전용 점검으로 현재 상태를 확인하세요. 같은 규칙은 다른 AI 코딩·도구 에이전트에도 적용할 수 있으며, 설치만으로는 설정이 바뀌지 않습니다.
install
# Claude Code
/plugin marketplace add ictechgy/context-guard
/plugin install context-guard@context-guard
/context-guard:setup
# Codex / 터미널 에이전트
npm install -g @ictechgy/context-guard
context-guard setup --agent codex --scope project --with-init --with-skill --plan
context-guard setup --agent codex --scope project --brief-mode standard --plan컨텍스트가 커질수록 판단은 흐려집니다.
긴 로그, 전체 파일 읽기, 반복 실패 출력, 민감 정보가 섞인 검색 결과는 AI 코딩 에이전트 세션의 컨텍스트를 빠르게 부풀립니다.
대용량 읽기
필요한 함수 하나를 찾으려고 파일 전체를 읽으면 컨텍스트가 금방 차오릅니다.
민감 정보
grep·diff 결과에 토큰, 키, 비밀번호처럼 보이는 값이 포함될 수 있습니다.
반복 실패
같은 명령이 계속 실패하면 스택 트레이스와 오류 로그가 컨텍스트를 빠르게 채웁니다.
ContextGuard가 하는 일
설치는 간단하지만 적용은 명시적입니다. 패키지 설치만으로는 전역 설정을 바꾸지 않고, 프로젝트 안에서 사용자가 승인한 변경만 기록합니다.
출력 축약
긴 로그를 head/tail 또는 의미 요약으로 줄이고 원래 명령의 종료 코드는 보존합니다.
민감정보 가림
에이전트 컨텍스트에 들어가기 전에 토큰·키·비밀번호처럼 보이는 값을 가립니다.
대용량 파일 가드
전체 파일 읽기 대신 검색, 심볼 구간, 작은 줄 범위 읽기를 안내합니다.
로컬 로그 보관소
큰 로그는 대화 밖에 저장하고, 필요한 줄 범위나 패턴 결과만 다시 가져옵니다.
예산 기반 컨텍스트 팩
우선순위가 있는 로컬 파일을 바이트 예산 안의 Markdown 팩으로 조립하고, --explain으로 로컬 선택 이유를 짧게 남깁니다.
설치 전 상태 점검
doctor와 setup --verify로 변경 없이 누락된 가드레일, 넓은 읽기 범위, 큰 컨텍스트 파일, 비용이 큰 설정을 확인합니다.
상태와 측정
상태표시줄, 대화 기록 감사, 기준/변형 쌍 비교로 사용량, 캐시 신호, 주장 범위를 확인합니다.
캐시 친화성 감사
대화 기록의 프롬프트 배치를 점검해 캐시에 불리한 구성과 안정적인 prefix 후보를 알려줍니다.
비용 가드와 route advisor
호출 전 cache breakpoint별 위험과 비용 범위를 추정하고, 로컬 총비용·batchability route 후보를 shifted-cost 경계와 함께 요약합니다. 원문 대신 keyed HMAC fingerprint만 로컬에 남깁니다.
에이전트 간 규칙
AGENTS.md, GEMINI.md, Cursor·Copilot 지시 파일에 brief 모드 권고 블록을 dry-run으로 확인한 뒤 설치합니다.
안전한 텍스트 압축
JSON·diff·로그를 결정적으로 줄이고, 관측한 바이트 근거와 추정 token proxy를 구분해 표시합니다.
Tool/MCP 스키마 정리기
큰 tool/MCP catalog를 작업 query 기준 top-k 리포트로 줄이고, 전체 가림 처리된 schema는 로컬 요약 기록으로 다시 조회합니다.
패키징·헬퍼 신뢰 경계
npm은 canonical context-guard/context-guard-* bin만 노출하고, 명령 매니페스트는 literal 데이터로 읽으며, setup과 macOS 헬퍼는 임의 PATH·CWD·symlink·상위 셸 환경을 기본 신뢰하지 않습니다.
캐시 도구를 대체하지 않고, 그 전에 생기는 낭비를 줄입니다.
Provider 캐시는 안정적인 프롬프트 앞부분을 재사용하고, semantic cache는 같거나 비슷한 요청의 이전 답변을 재사용합니다. 프롬프트 압축은 이미 선택된 텍스트를 줄입니다. ContextGuard는 그보다 먼저 불필요한 입력이 컨텍스트에 들어가기 전에 줄어들도록 돕는 로컬 가드레일입니다.
Provider prompt cache
안정적인 프롬프트 앞부분을 재사용합니다. ContextGuard는 자주 바뀌는 컨텍스트 뒷부분을 더 작고 깨끗하게 유지하도록 돕고, 감사와 cost preflight로 cache-write 가능성을 알려줍니다.
Semantic response cache
같거나 비슷한 요청의 이전 답변을 재사용합니다. ContextGuard는 AI 답변 캐시를 제공하지 않습니다.
Prompt compression
이미 선택된 텍스트를 더 짧게 만듭니다. ContextGuard는 로컬 출력 축약과 요약을 제공하지만 무손실 의미 압축을 보장하지 않습니다.
ContextGuard
큰 파일, 긴 로그, 반복 실패, 과도한 출력이 AI 코딩 에이전트 컨텍스트에 들어가기 전에 줄어들도록 안내하고, 직접 측정할 수 있는 전후 비교 근거를 남깁니다.
언제 특히 잘 맞을까요?
ContextGuard는 모든 작업에서 같은 절감률을 약속하지 않습니다. 대신 컨텍스트가 커지는 경로가 분명한 작업에서 측정 가능한 근거를 남깁니다.
효과를 확인하기 쉬운 경우
- 테스트·빌드 로그가 길고 실패 원인이 묻히는 프로젝트
- 큰 파일에서 필요한 함수나 설정 일부만 자주 찾는 작업
- 같은 실패 명령을 반복하는 디버깅 세션
- Claude 대화 기록과 로컬 벤치마크에서 토큰·비용 집중 지점을 확인하려는 팀
효과가 제한적인 경우
- 이미 작은 저장소에서 짧은 자연어 질문만 주고받는 경우
- provider prompt cache 적중률이 이미 높고 입력이 안정적인 워크플로
- 비슷한 질문의 답변 재사용이 핵심인 semantic cache 용도
- 직접 측정 없이 고정된 토큰·비용 절감률을 기대하는 경우
절감 수치를 해석하기 전, 측정 경계를 먼저 확인하세요.
벤치마크와 감사 결과는 숫자를 보여주지만, 어떤 숫자가 절감 근거이고 어떤 숫자가 진단용 신호인지 분리해 읽어야 합니다.
기준/변형 쌍 비교 벤치마크
context-guard-bench --ledger-jsonl ... --report-json ...는 성공한 baseline/variant task를 맞춰 비교합니다. workflow examples의 주장 범위를 먼저 확인하세요.
self-hosted sidecar
self_hosted_metrics는 run별 JSONL ledger sidecar입니다. context-guard experiments plan self-hosted-metrics-ledger는 dry-run preview만 만들며, CSV/report 요약이나 hosted API token/cost savings claim의 근거로 쓰지 않습니다.
측정 결과 binding 계약
--feasibility-json은 mac_visibility 스키마 같은 stable top-level binding 계약을 제공합니다. 과거 transcript scan은 live headroom이나 billing hit rate를 증명하지 않습니다.
실험 fixture는 출발점입니다
fixture-only starter와 experimental-token-reduction-radar는 matched successful task, provider-measured evidence, later-roadmap gate가 없으면 제공 기능이 아닙니다.
실험 기능은 명시적 명령 없이는 런타임 동작이 켜지지 않습니다.
context-guard experiments는 프로젝트 로컬 의도와 검토용 메타데이터를 기록합니다. 대부분의 lane은 dry-run checker/planner입니다. context-diff, visual crop/OCR, learned compression, self-hosted metrics, local proxy도 각각 명시적 로컬 명령과 gate를 통과한 좁은 evidence surface만 제공합니다. hosted API 절감이나 더 넓은 런타임 기능으로 주장하려면 별도 evidence gate와 future PR gate가 필요합니다.
context-diff compaction
context-diff-compaction은 dry-run plan으로 diff를 검토하고, 명시적 emit ... --receipt-id ... 명령에서만 caller-supplied compact replacement를 출력합니다. reviewable hunk, input diff와 일치하는 exact local artifact content/re-expand metadata와 더 작은 replacement가 모두 필요하며 semantic compression을 생성하지 않습니다.
visual crop/OCR
visual-crop-ocr은 dry-run plan과 명시적 emit visual-crop-ocr evidence pack으로 caller-supplied crop/OCR evidence를 검토합니다. full evidence receipt와 missed-context note가 필요하며 screenshot 캡처·image crop·OCR 실행·외부 service·file write·hosted savings claim은 하지 않습니다.
learned compression
learned-compression은 deny-by-default plan과 명시적 emit learned-compression으로 caller-supplied compact prose candidate를 검토합니다. verified exact fallback content가 필요하며 compressor 실행·embedding·reranker·model call·subprocess·external service·생성형 replacement·hosted savings claim은 하지 않습니다.
self-hosted metrics
self-hosted-metrics-ledger는 dry-run preview와 명시적 record ... --ledger-jsonl 로컬 sidecar 기록을 제공합니다. dry-run preview는 ledger 파일을 쓰지 않으며, record 결과도 hosted API 절감 근거로 쓰지 않습니다.
local proxy
local-proxy는 localhost-only advisory plan, design-only local-proxy-external-forwarding gate, 명시적 local-proxy-runtime-gate gate row, one-shot loopback forwarding MVP로만 검토합니다. plan/record는 listener, DNS lookup, external service call, traffic forwarding을 시작하지 않습니다. serve는 private ready-file nonce, literal loopback bind/target IP, 1회 요청, byte/time limit, credential-free request를 요구하며 API key persistence, CONNECT/TLS proxying, hosted savings claim을 차단합니다. optional diagnostic ledger는 successful forwarded request 뒤에만 shifted-cost 진단 row를 쓰고 raw headers/raw bodies나 hosted API 절감 근거를 저장하지 않습니다.
공통 안전 경계
experiments enable은 의도 기록일 뿐입니다. helper별 명시 flag, 주장 범위, 별도 runtime gate를 통과하기 전까지 안정 동작이나 절감 주장으로 승격하지 않습니다.
설치와 활성화를 나눠 시작하기
설치는 헬퍼를 준비하는 단계입니다. 프로젝트나 사용자 설정은 명시적인 setup 명령을 실행할 때만 기록됩니다.
Claude Code
/plugin marketplace add ictechgy/context-guard/plugin install context-guard@context-guard/context-guard:setup
Codex / npm
npm install -g @ictechgy/context-guardcontext-guard setup --agent codex --scope project --with-init --with-skill --plancontext-guard setup --agent codex --scope project --brief-mode standard --plan
macOS / Homebrew
brew install ictechgy/tap/context-guard
이미 tap했다면 brew install context-guard도 사용할 수 있습니다.
처음이라면 context-guard doctor --root . --json으로 현재 상태를 먼저 점검하세요. 기본값은 프로젝트 단위 설정입니다. 사용자 단위 설정은 --scope user와 명시적인 --agent가 필요하며, 지원되는 쓰기는 백업과 되돌리기 기록을 남깁니다. 설치만으로 설정 파일을 쓰지 않고, --allow-path-helper-fallback은 신뢰한 외부 설치를 확인할 때만 사용하세요.
세션 상태를 한눈에
상태표시줄은 모델, 저장소, 브랜치, 컨텍스트 사용률, 비용, 캐시 재사용 신호를 짧게 보여줍니다. cache와 reuse 값은 ContextGuard가 만든 절감률이 아니라 관측된 대화 기록·provider cache 신호입니다. 프롬프트 배치와 cache/headroom 감사도 증거 경계가 표시된 휴리스틱 진단이며 청구 기준이 아닙니다.
[Sonnet] repo | main | ctx 86% ⚠ | cost $0.123 | cache 80% | reuse 8.0xhelpers
# 컨텍스트 관리 검사
./plugins/context-guard/bin/context-guard-diet scan .
# 긴 로그를 로컬 보관본으로 저장
long-command 2>&1 | ./plugins/context-guard/bin/context-guard-artifact store --json
# 출력 축약과 종료 코드 보존
./plugins/context-guard/bin/context-guard-trim-output -- npm test
# 예산 기반 컨텍스트 팩
./plugins/context-guard/bin/context-guard-pack auto --root . --query "failing tests review" --diff HEAD --manifest-out suggested-pack.json --pack-out context-pack.md --budget-bytes 12000 --json --explain
# 또는 명시적인 두 단계:
./plugins/context-guard/bin/context-guard-pack suggest --root . --query "failing tests review" --diff HEAD --manifest-out suggested-pack.json --budget-bytes 12000 --json
./plugins/context-guard/bin/context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json
# Anthropic API 호출 전 비용·cache 위험 확인
./plugins/context-guard/bin/context-guard cost preflight --request request.json --budget-krw 3000 --json
# 로컬 총비용·batchability route 후보 확인
./plugins/context-guard/bin/context-guard route-advisor --workload workload.json --json
# tool/MCP catalog top-k 자문
./plugins/context-guard/bin/context-guard-tool-prune select --catalog tools.json --query "review failing tests" --json과장하지 않는 도구
ContextGuard는 “항상 몇 퍼센트 절감” 같은 약속 대신, 줄일 수 있는 컨텍스트 팽창을 먼저 줄이고 직접 측정할 수 있는 증거를 남깁니다. 로컬 RAM/디스크 보관본은 다음에 보낼 컨텍스트를 줄이는 데 도움이 될 수 있지만 Anthropic provider prompt cache를 대체하지 않습니다. 배포나 청구 설명 전에는 Anthropic prompt caching/pricing 문서를 다시 확인하세요.
측정 근거를 직접 남깁니다
벤치마크·감사·상태표시줄 신호로 실제 전후 변화를 측정하고, 절감 효과가 없으면 그대로 보고합니다.
고정 절감률을 보장하지 않습니다
저장소와 작업 방식에 따라 효과가 달라집니다. 벤치마크 도구로 직접 측정하세요.
외부 AI로 작업을 보내지 않습니다
토큰을 줄이기 위해 작업을 다른 AI 서비스로 보내거나 대신 실행하지 않습니다. 헬퍼는 로컬에서 동작합니다.
실험 레이더는 제공 기능이 아닙니다
Experimental token-reduction radar는 앞으로 검증할 후보와 later-roadmap gate를 기록합니다. 현재 제공되는 것은 대부분 dry-run checker/planner이며, 예외도 plan-only image-context-pack dry-run gate, context-diff emit, visual evidence-pack emit, learned candidate emit, self-hosted metrics JSONL sidecar record, local proxy gate record, one-shot literal-loopback local proxy serve 같은 좁은 명시적 로컬 surface뿐입니다. learned compressor runtime, 생성형 replacement, screenshot capture, image crop, OCR execution, generated image-context-pack renderers/runtime, self-hosted KV/latent runtime, external/daemon/hostname-DNS/credential-bearing proxy forwarding runtime은 provider-measured matched-task 근거와 별도 future PR gate 없이는 제공 기능이나 hosted API 절감으로 주장하지 않습니다.
전역 설정을 자동 변경하지 않습니다
설정은 프로젝트 단위로, 사용자가 명시적으로 적용할 때만 반영됩니다.
헬퍼 실행 경로를 좁힙니다
setup은 bundled/checkout-local helper를 우선 사용하고, macOS visibility helper는 bundle/resource/executable-relative 경로나 absolute explicit override만 허용합니다. 상대 override, launch CWD, symlink helper, 임의 PATH, 불필요한 상위 환경은 기본 신뢰하지 않습니다.
리브랜딩 호환성을 남겼습니다
예전 슬래시 명령은 별칭으로 제공하지 않지만, 기존 자동화를 위한 CLI 래퍼 파일은 계속 제공합니다. npm global/npx bin 링크는 canonical context-guard/context-guard-* 명령만 노출합니다.