Context Audit
이 컨벤션을 채택한 리포지토리는 적은 수의 지속성 파일을 유지하여 에이전트가 매 세션마다 같은 내용을 다시 유도하지 않도록 합니다. 즉, 프로젝트 관례(AGENTS.md), 이미 결정된 사항과 그 이유(memory.md), 그리고 코드베이스의 대략적인 구조(.agent/graph.md)입니다. 이 스킬은 이러한 파일이 존재하고 최신인지 확인한 후에 신뢰하거나 수동으로 리포지토리를 스캔하는 대신 사용할 수 있도록 합니다.
트리거 구문
세션 시작 / 신뢰 확인
- "이 리포지토리에 대해 알려줘"
- "이 프로젝트에 대해 무엇을 알고 있니?"
- "AGENTS.md / memory.md를 신뢰해도 될까?"
- "컨텍스트 파일이 최신인가?"
- "컨텍스트 확인" / "컨텍스트 감사"
오래됨
- "AGENTS.md가 오래되었나?" / "memory.md가 오래되었나?"
- "마지막 동기화 이후 몇 개의 커밋이 있었나?"
- "내 에이전트 파일이 최신인가?"
- "컨텍스트가 오래되었는지 확인"
토큰 비용
- "컨텍스트 파일이 얼마나 절약해주나?"
- "토큰 절감" / "컨텍스트 비용"
- "토큰 절감 벤치마크"
- "기준 대비 큐레이션된 토큰"
설정 / 온보딩
- "AGENTS.md 스캐폴드" / "컨텍스트 초기화"
- "ctx-audit 설치" / "컨텍스트 후크 연결"
- "AI 컨텍스트 설정" / "이 프로젝트가 AI 준비되었나?"
CI / 자동화
- "CI에 ctx-audit 추가"
- "푸시 전 후크 추가"
- "CI에서 컨텍스트 최신성 강제"
아키텍처
- "아키텍처 맵이 있나?"
- "graph.md 생성" / "graphify 실행"
실행 방법
ctx-audit을 실행하는 권장 방법:
npx ctx-audit
또는 스킬로 설치된 경우:
node <path-to-this-skill-folder>/../scripts/audit.mjs
플래그:
--json— 기계 판독 가능 출력 (결과를 프로그래밍 방식으로 처리하려는 경우 사용).--strict— 누락되거나 오래된 항목이 있으면 종료 코드 1 반환.--ci—--strict --json의 별칭.--help— 사용법 표시 후 종료.
하위 명령어
# AGENTS.md + memory.md 스캐폴드 (대화형 — 파일을 리포지토리 루트에 직접 작성)
npx ctx-audit init
# 한 번 설치: 스킬을 ~/.claude/skills/에 복사하고 CLAUDE.md에 등록
npx ctx-audit install
# Git 후크: 모든 푸시 시 --strict 감사 실행
npx ctx-audit hook install
npx ctx-audit hook status
npx ctx-audit hook uninstall
# 프로젝트 CLAUDE.md: 에이전트용 명령 블록 추가
npx ctx-audit claude install
npx ctx-audit claude uninstall
# 토큰 절감 보고서 (집중적이고 공유 가능한 형식)
npx ctx-audit benchmark
에이전트 결정 테이블
| 상태 | 의미 | 조치 |
|---|---|---|
| FRESH | 마지막 동기화 이후 커밋 수가 오래됨 임계값의 절반 미만 | 파일 신뢰 — 원시 소스를 스캔하는 대신 읽기 |
| STALE? | 임계값에 근접 (오래되었을 가능성) | 약간의 주의 — 중요한 주장을 의존하기 전에 교차 확인 |
| STALE! | 임계값 초과, 실패로 간주 | 주장을 검증되지 않은 것으로 처리; 실제 코드와 교차 확인; 세션 후 업데이트 |
| STALE | 상당히 뒤쳐짐, 실패로 간주 | STALE!과 동일하지만 더 긴급; 세션 직후 업데이트 |
| MISSING (필수) | 파일 없음 | npx ctx-audit init 실행; 컨벤션이 적용된 것처럼 진행하지 않음 |
| absent (선택) | 선택적 파일 없음 | 허용 가능; graph.md 생성을 위해 /graphify 실행 고려 |
| over budget | 토큰 수가 maxTokens 초과 | 파일이 비대해짐 — 정리 필요; 읽는 비용이 절감보다 클 수 있음 |
| dead reference | 파일의 백틱 경로 또는 dir/file.ext가 디스크에 없음 | 참조 업데이트; 파일이 오래된 구조를 문서화 |
| SHA bumped | last_synced_commit이 업데이트되었지만 본문 변경 없음 | 파일이 실제로 최근 변경 사항을 반영하는지 확인; 단순한 기계적 업데이트일 수 있음 |
결과 해석
- MISSING (필수 파일): 컨벤션이 적용된 것처럼 진행하지 않음.
작업 없이 진행하거나 기존의 "모든 것을 수동으로 탐색" 방식을 조용히 사용하는 대신,
시작 파일을 스캐폴드(
npx ctx-audit init실행)하도록 제안. - FRESH: 파일이 최신 상태. 원시 소스를 스캔하는 대신 읽기.
- STALE? (오래되었을 가능성): 임계값에 근접. 중요한 주장을 교차 확인.
- STALE! (오래되었을 가능성 높음): 해당 주장을 검증되지 않은 것으로 처리.
중요한 내용을 실제 코드와 교차 확인하고, 세션 후 파일과
last_synced_commit을 업데이트. - STALE: 상당히 뒤쳐짐. STALE!과 동일한 처리이지만 더 긴급.
- 토큰 수는 약 3.5자/토큰 휴리스틱 — 방향성은 유용하지만 정확하지 않음. 파일이 "over budget"으로 표시되면, 읽는 비용이 절감하려던 비용을 초과할 정도로 비대해진 것이므로 정리 제안.
- Dead reference 경고: 컨텍스트 파일에서 언급된 경로가 디스크에 더 이상 존재하지 않음. 파일이 오래된 구조를 참조하고 있음을 나타냄.
실제 예제
세션 시작 시 기본 감사:
npx ctx-audit
CI 게이트 (컨텍스트가 오래된 경우 빌드 실패):
# .github/workflows/ctx-audit.yml
- name: 컨텍스트 최신성 감사
run: npx ctx-audit --strict
프로그래밍 방식 사용을 위한 JSON 출력:
npx ctx-audit --json | jq '.checks[] | {file, stalenessLevel, stale}'
한 번의 명령으로 온보딩:
npx ctx-audit install # 스킬 복사, CLAUDE.md에 등록
npx ctx-audit hook install # 푸시 전 가드 추가
npx ctx-audit claude install # 프로젝트 CLAUDE.md에 노트 추가
npx ctx-audit init # AGENTS.md + memory.md 스캐폴드
프론트매터를 통한 특정 하위 시스템 오래됨 확인:
---
last_synced_commit: abc1234
watches: src/auth/**, src/api/**
---
이 파일의 오래됨 여부는 src/auth/ 또는 src/api/에 영향을 미치는 커밋만 카운트됩니다.
토큰 절감 벤치마크:
npx ctx-audit benchmark
설정
리포지토리 루트에 .ctx-audit.json을 배치하여 동작을 사용자 정의:
{
"files": [{ "id": "...", "file": "...", "label": "...", "maxTokens": N, "required": true }],
"sourceDirs": ["src", "packages/core"],
"staleThreshold": 10,
"baselineFileCap": 300
}
프론트매터
각 컨텍스트 파일은 프론트매터로 시작해야 합니다:
---
last_synced_commit: <git sha>
watches: src/auth/**, src/api/**
---
watches 필드(선택 사항)는 모든 소스 디렉토리 대신 해당 경로에 영향을 미치는 커밋만으로 오래됨 확인 범위를 제한합니다.
필수 파일이 누락된 경우 — 스캐폴드
npx ctx-audit init을 실행하여 템플릿을 생성합니다. TTY에서는 리포지토리 루트에 직접 파일을 작성하고, 파이프된 경우 stdout으로 출력합니다. 레거시 --init 플래그도 하위 호환 별칭으로 지원됩니다.
AGENTS.md — 안정적인 프로젝트 관례: 빌드/테스트/린트 명령어, 파일 레이아웃 규칙, 에이전트가 절대 해서는 안 되는 사항. 거의 변경되지 않아야 합니다.
memory.md — 현재 코드의 재진술이 아닌 실행 중인 결정 로그. 각 항목: 시도한 것, 결정한 것, 이유, 상황이 바뀌면 재고해야 할 사항. 역사를 다시 쓰지 말고 추가하세요.
.agent/graph.md (리포지토리가 커지면 권장되지만 선택 사항) — 주요 모듈당 한 단락으로 책임과 통신하는 대상을 설명. 파일 내용이 아니며, 완전한 트리가 아닙니다. 에이전트가 모든 것을 다시 읽지 않고 탐색할 수 있을 정도면 충분합니다. 팁: 수동으로 작성하는 대신 /graphify를 실행하여 코드베이스에서 자동 생성하세요.
이러한 파일을 스캐폴드하거나 업데이트한 후에는 last_synced_commit을 현재 HEAD로 업데이트하여 다음 감사에서 즉시 오래된 것으로 표시되지 않도록 하세요.