Claude Code 플러그인 · 로컬 가드레일 · 에이전트 간 규칙

ContextGuard

파일·로그·출력을 AI 컨텍스트에 들어가기 전에 줄입니다.

ContextGuard는 불필요한 파일·로그·출력이 AI 에이전트 컨텍스트에 유입되기 전에 걸러내는 로컬 가드레일입니다. Claude Code 플러그인으로 바로 시작하고, 다른 AI 코딩·도구 에이전트에도 같은 규칙을 적용할 수 있습니다.

빠른 시작 GitHub 보기
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

컨텍스트가 커질수록 판단은 흐려집니다.

긴 로그, 전체 파일 읽기, 반복 실패 출력, 민감 정보가 섞인 검색 결과는 AI 코딩 에이전트 세션을 빠르게 비대하게 만듭니다.

01

긴 출력

테스트·빌드 로그가 대화에 그대로 들어오면 중요한 실패 원인이 묻힙니다.

02

대용량 읽기

필요한 함수 하나를 찾으려고 파일 전체를 읽으면 컨텍스트가 금방 차오릅니다.

03

민감 정보

grep·diff 결과에 토큰, 키, 비밀번호처럼 보이는 값이 포함될 수 있습니다.

04

반복 실패

같은 명령이 계속 실패하면 스택 트레이스와 오류 로그가 컨텍스트를 빠르게 채웁니다.

ContextGuard가 하는 일

설치는 간단하지만 적용은 명시적입니다. 전역 설정을 건드리지 않고 프로젝트 안에서만 동작합니다.

↧

출력 축약

긴 로그를 head/tail 또는 의미 요약으로 줄이고 원래 명령의 종료 코드는 보존합니다.

✦

민감정보 가림

에이전트 컨텍스트에 들어가기 전 토큰·키·비밀번호처럼 보이는 값을 가립니다.

⌁

대용량 파일 가드

전체 파일 읽기 대신 검색, 심볼 구간, 작은 줄 범위 읽기를 안내합니다.

▣

로컬 로그 보관소

큰 로그는 대화 밖에 저장하고, 필요한 줄 범위나 패턴 결과만 다시 가져옵니다.

⊡

예산 기반 컨텍스트 팩

우선순위 있는 로컬 파일을 바이트 예산 안의 Markdown 팩으로 조립하고, 생략 사유와 정확한 slice 명령을 함께 기록합니다.

◎

컨텍스트 진단

누락된 가드레일, 넓은 읽기 범위, 큰 컨텍스트 파일, 비용이 큰 설정을 찾습니다.

↗

상태와 측정

상태표시줄, 대화 기록 감사, 기준/변형 쌍 비교로 사용량과 절감 근거를 확인합니다.

⌬

캐시 친화성 감사

제한된 범위의 가림 처리된 segment hash로 자주 바뀌는 내용이 안정적인 프롬프트 앞부분을 흔드는지 점검합니다.

↔

에이전트 간 규칙

AGENTS.md, GEMINI.md, Cursor·Copilot 지시 파일에 brief 모드 권고 블록을 dry-run으로 확인한 뒤 설치합니다.

∴

안전한 텍스트 압축

JSON·diff·로그를 결정적으로 줄이고, 바이트 근거와 추정 token proxy를 구분해 표시합니다.

⌗

Tool/MCP 스키마 정리기

큰 tool/MCP catalog를 작업 query 기준 top-k 리포트로 줄이고, 전체 가림 처리된 schema는 로컬 요약 기록로 다시 조회합니다.

캐시 도구를 대체하지 않고, 그 앞단의 낭비를 줄입니다.

Provider 캐시는 안정적인 프롬프트 앞부분을 재사용하고, semantic cache는 같거나 비슷한 요청의 이전 답변을 재사용합니다. 프롬프트 압축은 이미 선택된 텍스트를 줄입니다. ContextGuard는 그보다 앞단에서 불필요한 입력을 걸러내는 로컬 가드레일입니다.

P

Provider prompt cache

안정적인 프롬프트 앞부분을 재사용합니다. ContextGuard는 자주 바뀌는 컨텍스트 뒷부분을 더 작고 깨끗하게 유지하도록 돕고, 감사로 volatile prefix 가능성을 알립니다.

S

Semantic response cache

같거나 비슷한 요청의 이전 답변을 재사용합니다. ContextGuard는 AI 답변 캐시를 제공하지 않습니다.

C

Prompt compression

이미 선택된 텍스트를 더 짧게 만듭니다. ContextGuard는 로컬 출력 축약과 요약을 제공하지만 무손실 의미 압축을 보장하지 않습니다.

G

ContextGuard

큰 파일, 긴 로그, 반복 실패, 과도한 출력을 AI 코딩 에이전트 컨텍스트에 들어가기 전에 줄이도록 안내하고, 직접 측정할 수 있는 전후 비교 근거를 남깁니다.

언제 특히 잘 맞을까요?

ContextGuard는 모든 작업에서 같은 절감률을 약속하지 않습니다. 대신 컨텍스트가 커지는 경로가 분명한 작업에서 측정 가능한 근거를 남깁니다.

✓

효과를 확인하기 쉬운 경우

  • 테스트·빌드 로그가 길고 실패 원인이 묻히는 프로젝트
  • 큰 파일에서 필요한 함수나 설정 일부만 자주 찾는 작업
  • 같은 실패 명령을 반복하는 디버깅 세션
  • Claude 대화 기록과 로컬 벤치마크에서 토큰·비용 집중 지점을 확인하려는 팀
!

효과가 제한적인 경우

  • 이미 작은 저장소에서 짧은 자연어 질문만 주고받는 경우
  • provider prompt cache 적중률이 이미 높고 입력이 안정적인 워크플로
  • 비슷한 질문의 답변 재사용이 핵심인 semantic cache 용도
  • 직접 측정 없이 고정된 토큰·비용 절감률을 기대하는 경우

설치와 활성화를 나눠서 시작하기

설치는 헬퍼를 준비하는 단계입니다. 프로젝트나 사용자 설정은 명시적인 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-guard
context-guard setup --agent codex --scope project --with-init --with-skill --plan

macOS / Homebrew

brew tap ictechgy/contextguard
brew install context-guard
formula 공개 전에는 npm/npx를 사용합니다.

기본값은 프로젝트 단위 설정입니다. 사용자 단위 설정은 --scope user와 명시적인 --agent가 필요하며, 지원되는 쓰기는 백업과 되돌리기 기록을 남깁니다.

세션 상태를 한눈에

상태표시줄은 모델, 저장소, 브랜치, 컨텍스트 사용률, 비용, 캐시 재사용 신호를 짧게 보여줍니다. cache와 reuse 값은 ContextGuard가 만든 절감률이 아니라 관측된 대화 기록·provider cache 신호입니다. 프롬프트 배치 감사도 휴리스틱 진단이며 청구 기준이 아닙니다.

[Sonnet] repo | main | ctx 86% ⚠ | cost $0.123 | cache 80% | reuse 8.0x
helpers
# 컨텍스트 관리 검사
./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 build --root . --source 'path=README.md,priority=100,lines=1:80' --budget-bytes 12000 --json

# tool/MCP catalog top-k 자문
./plugins/context-guard/bin/context-guard-tool-prune select --catalog tools.json --query "review failing tests" --json

과장하지 않는 도구

ContextGuard는 “항상 몇 퍼센트 절감” 같은 약속 대신, 줄일 수 있는 컨텍스트 팽창을 먼저 줄이고 직접 측정할 수 있는 증거를 남깁니다.

✓

측정 근거를 직접 남깁니다

벤치마크·감사·상태표시줄 신호로 실제 전후 변화를 측정하고, 절감 효과가 없으면 그대로 보고합니다.

!

고정 절감률을 보장하지 않습니다

저장소와 작업 방식에 따라 효과가 달라집니다. 벤치마크 도구로 직접 측정하세요.

↯

외부 AI로 작업을 보내지 않습니다

토큰을 줄이기 위해 작업을 다른 AI 서비스로 보내거나 대신 실행하지 않습니다. 헬퍼는 로컬에서 동작합니다.

?

실험 레이더는 제공 기능이 아닙니다

Experimental token-reduction radar는 앞으로 단계적으로 검증할 실험 후보를 기록합니다. provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다.

⌂

전역 설정을 자동 변경하지 않습니다

설정은 프로젝트 단위로, 사용자가 명시적으로 적용할 때만 반영됩니다.

↺

리브랜딩 호환성을 남겼습니다

예전 슬래시 명령은 별칭으로 제공하지 않지만, 기존 자동화를 위한 CLI 래퍼는 계속 제공합니다.