smorky850612/Aurakit / skills/aura
aura
VerifiedAll-in-one fullstack dev engine. /aura: 46 modes (build/fix/clean/deploy/review/spec/lore/ax/experiment/payment/debug/qa/orchestrate/escalate+), 6-layer security with 32 hooks, tiered models (ZERO/ECO/PRO/MAX), 8 languages, 16 specialized agents, SPEC/EARS/TRUST5/XLOOP/RALF/Autopus absorbed. ~55% token savings.
resources/cache-engineering.md
View on GitHub# Cache Engineering — CACHE-RULE-01~07
> AuraKit LEAKFORGE v7.0.0 | NERVE 모듈
> 캐시 엔지니어링은 토큰 절감의 숨겨진 20%를 담당한다.
> Anthropic은 캐시 히트율을 업타임처럼 모니터링하며 떨어지면 SEV(장애) 선언한다.
---
## 캐시 작동 원리
Claude Code의 캐시는 **prefix match** 방식이다:
- prefix 어디든 **한 글자**가 바뀌면 그 이후 **전체 캐시 무효화**
- 캐시 순서 (정적 → 동적):
```
[1] 정적 시스템 프롬프트 + 도구 정의 ← 가장 안정적, 캐시 효과 최대
[2] CLAUDE.md ← 변경 빈도 낮음
[3] 세션 컨텍스트 ← 중간 안정성
[4] 대화 히스토리 ← 가장 동적, 캐시 효과 제한적
```
캐시 히트 시: **입력 토큰 비용 90% 절감** (Anthropic 공식 캐시 요금)
---
## CACHE-RULE-01: 정적 콘텐츠 prefix 최상단 배치
**규칙**: 변하지 않는 콘텐츠는 항상 컨텍스트의 최상단에 위치해야 한다.
**적용**:
- SKILL.md, 보안 규칙, 에이전트 정의 → 세션 시작 시 1회 로딩
- 동적 콘텐츠(타임스탬프, 사용자 입력) → 대화 하단에 배치
- 공통 프로토콜(B-0~B-5) → 세션 첫 턴에만 실행, 이후 캐시 활용
**위반 시 토큰 손실 추정**: 시스템 프롬프트 11~14K 토큰 전체 캐시 미스 → **~$0.03~0.04/세션** 추가 비용
---
## CACHE-RULE-02: 시스템 프롬프트 동적 값 삽입 금지
**규칙**: 시스템 프롬프트에 타임스탬프, 날짜, 세션 ID 등 변하는 값을 직접 삽입하지 않는다.
**금지 패턴**:
```
❌ 시스템 프롬프트: "현재 시각: 2026-04-01 09:30:00"
❌ 시스템 프롬프트: "세션 ID: sess_abc123"
```
**대안**:
```
✅ 동적 값은 다음 턴의 <system-reminder> 태그로 전달
✅ 또는 user message의 첫 줄에 컨텍스트 추가
```
**위반 시 토큰 손실 추정**: 매 턴마다 11~14K 토큰 캐시 미스 → **세션당 ~50K 토큰 추가 비용**
---
## CACHE-RULE-03: 세션 중간 도구 추가/제거 금지
**규칙**: 도구 정의(tools)를 세션 도중에 추가하거나 제거하면 캐시 전체가 무효화된다.
**금지 패턴**:
```
❌ 세션 중 새 MCP 도구 활성화
❌ 세션 중 disallowed-tools 목록 변경
❌ 세션 중 모드 전환 시 도구 교체
```
**대안 — Plan Mode 패턴**:
```
✅ 상태 전환은 도구 교체가 아닌 도구 호출로 처리
✅ EnterPlanMode 도구 호출 → Plan Mode 진입 (도구 세트 불변)
✅ 무거운 도구는 defer_loading: true 스텁으로 유지 (CACHE-RULE-05 참조)
```
**위반 시 토큰 손실 추정**: 도구 정의 ~5K 토큰 + 시스템 프롬프트 14K → **~19K 토큰 즉시 캐시 미스**
---
## CACHE-RULE-04: 세션 중 모델 변경 금지
**규칙**: 세션 도중 메인 모델을 변경하면 캐시 컨텍스트 전체가 새 모델 기준으로 재계산된다.
**금지 패턴**:
```
❌ 세션 중 /model 명령으로 haiku → sonnet 전환
❌ 세션 중 tier 변경 (ECO → PRO)
```
**대안**:
```
✅ 다른 모델이 필요한 작업 → 서브에이전트(Agent 도구)로 위임
✅ /aura escalate 명령 → Opus 서브에이전트 실행 후 메인 세션 복귀
✅ 티어 변경은 새 세션 시작 시 적용
```
**위반 시 토큰 손실 추정**: 대화 히스토리 전체 재처리 → **세션 규모에 따라 10K~100K 토큰 손실**
---
## CACHE-RULE-05: defer_loading 스텁 사용
**규칙**: 무거운 도구는 이름만 로드하고, 실제 스키마는 필요할 때만 ToolSearch로 로드한다.
**패턴**:
```
✅ defer_loading: true → 도구 이름만 prefix에 포함 (스키마 제외)
✅ 사용 시점에 ToolSearch("select:ToolName") 호출 → 풀 스키마 로드
```
**AuraKit 적용**:
- Sanity MCP, Vercel MCP 등 대형 MCP 도구 → 스텁으로 유지
- SKILL.md 리소스 → 해당 모드 실행 시만 로딩 (Progressive Load)
**위반 시 토큰 손실 추정**: MCP 도구 스키마 ~1K/도구 × N도구 → **대형 MCP 세트에서 ~5~10K 토큰 낭비**
---
## CACHE-RULE-06: 컴팩션 시 부모 prefix 완전 일치 유지
**규칙**: 컴팩션(자동 요약) 시 시스템 프롬프트·도구·초기 히스토리 prefix를 동일하게 유지해야 캐시가 살아남는다.
**올바른 컴팩션 방식**:
```
✅ 시스템 프롬프트: 동일 유지
✅ 도구 정의: 동일 유지
✅ 히스토리 prefix: 동일 유지
✅ 요약 요청: user message로 추가 (prefix 뒤에)
```
**잘못된 컴팩션 방식**:
```
❌ 시스템 프롬프트 수정 후 컴팩션
❌ 도구 일부 제거 후 컴팩션
```
**AuraKit 대응**: `pre-compact-snapshot.sh` → 컴팩션 전 상태 저장, `post-compact-restore.sh` → 복원
**위반 시 토큰 손실 추정**: 컴팩션 후 전체 재처리 → **11~14K 시스템 프롬프트 캐시 미스**
---
## CACHE-RULE-07: --resume 후 캐시 미스 경고
**규칙**: `claude --resume`으로 세션을 복구하면 대화 히스토리 전체가 캐시 미스된다.
시스템 프롬프트(11~14K)만 캐시되고, 나머지는 재처리된다.
**사용자 알림 트리거**:
- `--resume` 플래그 감지 → 사용자에게 캐시 미스 상황 알림
- 긴 대화 히스토리 복구 시 예상 추가 비용 표시
**알림 예시**:
```
⚠️ CACHE-RULE-07: --resume 감지
대화 히스토리 캐시 미스 (시스템 프롬프트 11-14K만 캐시됨)
예상 추가 비용: ~$0.02~0.10 (히스토리 길이에 따라)
새 세션 시작 권장 (긴 대화 복구 시)
```
**대안**:
- 짧은 세션 → --resume 사용 OK (캐시 손실 미미)
- 긴 세션 복구 → 새 세션 + `.aura/snapshots/current.md`로 컨텍스트 복원
**위반 시 토큰 손실 추정**: 히스토리 규모에 따라 **10K~500K 토큰 추가 캐시 미스**
---
## 캐시 히트율 목표
| 상황 | 목표 히트율 | 비고 |
|------|-----------|------|
| 일반 세션 (ECO/PRO) | ≥ 90% | 시스템 프롬프트 + 도구 안정 |
| QUICK 모드 | ≥ 95% | 단일 턴, 히스토리 최소 |
| --resume 직후 | ~50% | CACHE-RULE-07 적용 |
| 도구 변경 후 | 0% → 회복 중 | CACHE-RULE-03 위반 시 |
---
## SKILL.md 연결
- **BUILD 모드**: Sonnet Amplifier v2 Step 5 "Cache Impact Check"에서 이 규칙 참조
- **FIX 모드**: HEALER Phase 1~3 실행 시 캐시 영향 최소화 전략 적용
- **DEPLOY 모드**: 도구 정의 불변 유지 확인
- **cache-guard.js 훅**: CACHE-RULE-03/04 위반 감지 → 자동 차단
---
*Reference: LEAKFORGE v7.0.0 — Anthropic Claude Code 소스맵 분석 기반 (2026-03-31)*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |