Everything Claude Code

hahhhm·2026년 3월 4일

https://github.com/affaan-m/everything-claude-code

Affaan Mustafa(@affaanmustafa)의 Shorthand Guide + Longform Guide를 한국어로 취합 정리한 글이다. 10개월 이상 매일 Claude Code를 사용하며 Anthropic 해커톤에서 우승한 개발자의 실전 노하우를 담았다.

저자 소개: Affaan Mustafa

everything-claude-code GitHub 레포 51,000+ 스타 — Claude Code 리소스 중 가장 유명
Anthropic x Forum Ventures 해커톤 우승 (Zenith 프로젝트, @DRodriguezFX와 함께)
20살에 학위 3개 (UCSD Math-CS + Business Econ, Bellevue College AA)
AgentShield 개발 — Claude Code 설정 보안 스캐너 (1,282개 테스트, 102개 규칙)

원문 출처:

Part 1: Shorthand Guide — 기초 인프라 구축

Shorthand Guide는 "뭘 설치하고 어떻게 설정하나"에 대한 가이드다. Skills, hooks, subagents, MCPs, plugins의 설정 패턴을 다룬다.

1. Skills & Commands

Skills이란?

Skills은 특정 스코프와 워크플로우에 제한된 규칙처럼 동작한다. 특정 워크플로우를 실행할 때 프롬프트의 축약어(shorthand) 역할을 한다.

Opus 4.5로 긴 코딩 세션을 끝내고 데드 코드와 불필요한 .md 파일을 정리하고 싶다면? /refactor-clean을 실행하면 된다. 테스트가 필요하면? /tdd, /e2e, /test-coverage. 여러 커맨드를 하나의 프롬프트에서 체인으로 연결할 수도 있다.

Skills vs Commands

둘은 겹치지만 저장 위치가 다르다:

Skills: ~/.claude/skills — 더 넓은 워크플로우 정의
Commands: ~/.claude/commands — 빠르게 실행 가능한 프롬프트 (슬래시 커맨드로 실행)

디렉토리 구조 예시

~/.claude/skills/
  pmx-guidelines.md      # 프로젝트 특화 패턴
  coding-standards.md     # 언어 베스트 프랙티스
  tdd-workflow/           # 멀티파일 스킬 (README.md 포함)
  security-review/        # 체크리스트 기반 스킬
  codemap-updater.md      # 체크포인트마다 코드맵 업데이트

코드맵 업데이트 스킬

코드맵 업데이트 스킬을 만들면 Claude가 컨텍스트를 탐색에 태우지 않고도 코드베이스를 빠르게 탐색할 수 있다. 체크포인트마다 자동으로 코드맵을 갱신하는 방식이다.

2. Hooks

Hooks이란?

Hooks은 특정 이벤트에 트리거되는 자동화다. Skills과 달리 도구 호출과 라이프사이클 이벤트에 제한된다.

Hook 타입 총정리

Hook	트리거 시점	활용 예시
`PreToolUse`	도구 실행 전	검증, 리마인더, 위험 명령 차단
`PostToolUse`	도구 실행 후	포매팅, 피드백 루프, 타입 체크
`UserPromptSubmit`	메시지 전송 시	프롬프트 전처리
`Stop`	Claude 응답 완료 시	최종 감사, console.log 체크
`PreCompact`	컨텍스트 압축 전	중요 정보 보존
`Notification`	권한 요청 시	알림 커스터마이즈

실전 예시: 장시간 명령 전 tmux 리마인더

{
  "PreToolUse": [
    {
      "matcher": "tool == \"Bash\" && tool_input.command matches \"(npm|pnpm|yarn|cargo|pytest)\"",
      "hooks": [
        {
          "type": "command",
          "command": "if [ -z \"$TMUX\" ]; then echo '[Hook] Consider tmux for session persistence' >&2; fi"
        }
      ]
    }
  ]
}

npm, yarn 등 장시간 실행될 수 있는 명령을 쓸 때, tmux 세션 안이 아니면 리마인더를 띄워주는 훅이다.

💡 팁: hookify 플러그인을 사용하면 JSON을 직접 작성하지 않고 대화형으로 훅을 생성할 수 있다. /hookify를 실행하고 원하는 걸 설명하면 된다.

3. Subagents (서브에이전트)

서브에이전트란?

오케스트레이터(메인 Claude)가 제한된 스코프로 작업을 위임할 수 있는 프로세스다. 백그라운드 또는 포그라운드에서 실행되며, 메인 에이전트의 컨텍스트를 절약해준다.

서브에이전트는 스킬과 잘 어울린다 — 특정 스킬의 부분 집합만 실행할 수 있는 서브에이전트를 만들어 위임하면, 그 스킬들을 자율적으로 사용한다. 도구 권한으로 샌드박싱도 가능하다.

디렉토리 구조

~/.claude/agents/
  planner.md             # 기능 구현 계획 수립
  architect.md           # 시스템 설계 결정
  tdd-guide.md           # 테스트 주도 개발
  code-reviewer.md       # 품질/보안 리뷰
  security-reviewer.md   # 취약점 분석
  build-error-resolver.md # 빌드 에러 해결
  e2e-runner.md          # Playwright 테스트
  refactor-cleaner.md    # 데드 코드 제거
  doc-updater.md         # 문서 동기화 유지

핵심: 서브에이전트마다 허용된 도구, MCP, 권한을 별도 설정해서 적절한 스코핑을 해야 한다.

4. Rules & Memory

Rules이란?

.rules 폴더에 .md 파일로 Claude가 항상 따라야 하는 베스트 프랙티스를 저장한다.

두 가지 접근법

방법 1: 단일 CLAUDE.md — 모든 것을 한 파일에 (유저 또는 프로젝트 레벨)

방법 2: Rules 폴더 — 관심사별로 모듈화된 .md 파일

~/.claude/rules/
  security.md      # 하드코딩된 시크릿 금지, 입력 검증
  coding-style.md  # 불변성 우선, 파일 구성 규칙
  testing.md       # TDD 워크플로우, 80% 커버리지
  git-workflow.md  # 커밋 포맷, PR 프로세스
  agents.md        # 서브에이전트 위임 규칙
  performance.md   # 모델 선택, 컨텍스트 관리

규칙 예시

코드베이스에 이모지 금지
프론트엔드에서 보라색 계열 자제
배포 전 항상 코드 테스트
메가파일보다 모듈러 코드 우선
console.log 절대 커밋 금지

5. MCPs (Model Context Protocol)

MCP란?

MCP는 Claude를 외부 서비스에 직접 연결한다. API의 대체가 아니라, API 주변에 프롬프트 기반 래퍼를 씌워서 정보 탐색에 더 유연성을 제공하는 것이다.

예시: Supabase MCP를 쓰면 Claude가 특정 데이터를 가져오거나, SQL을 직접 실행할 수 있다. 복사-붙여넣기 없이

Chrome in Claude: 내장 플러그인 MCP로, Claude가 자율적으로 브라우저를 제어한다 — 클릭하면서 어떻게 동작하는지 확인하는 방식

⚠️ 치명적: 컨텍스트 윈도우 관리

"200k 컨텍스트 윈도우가 너무 많은 도구가 활성화되면 실질적으로 70k까지 줄어든다. 성능이 심각하게 저하된다."

황금 규칙:

설정에 20~30개 MCP를 등록하되
활성화는 10개 미만
활성 도구는 80개 미만 유지

/plugins로 이동하거나 /mcp를 실행해서 현재 상태를 확인할 수 있다.

6. Plugins

플러그인이란?

수동 설정의 번거로움 대신 도구를 쉽게 설치할 수 있게 패키징한 것이다. 스킬 + MCP 조합이거나, 훅/도구를 번들로 묶은 형태

설치 방법

# 마켓플레이스 추가
claude plugin marketplace add https://github.com/mixedbread-ai/mgrep

# Claude에서 /plugins 실행 → 새 마켓플레이스 찾기 → 설치

LSP 플러그인

에디터 밖에서 Claude Code를 자주 실행한다면 특히 유용하다. Language Server Protocol이 IDE 없이도 실시간 타입 체크, go-to-definition, 자동 완성을 제공한다.

typescript-lsp@claude-plugins-official  # TypeScript 지능
pyright-lsp@claude-plugins-official     # Python 타입 체크
hookify@claude-plugins-official         # 대화형 훅 생성
mgrep@Mixedbread-Grep                   # ripgrep보다 강력한 검색

⚠️ MCP와 마찬가지로 컨텍스트 윈도우를 주시할 것.

7. Tips & Tricks

키보드 단축키

단축키	기능
`Ctrl+U`	전체 줄 삭제 (백스페이스 연타보다 빠름)
`!`	빠른 bash 명령 접두사
`@`	파일 검색
`/`	슬래시 커맨드 시작
`Shift+Enter`	멀티라인 입력
`Tab`	thinking 표시 토글
`Esc Esc`	Claude 중단 / 코드 복원

병렬 워크플로우

/fork — 대화를 분기해서 겹치지 않는 작업을 병렬로 처리. 큐에 메시지를 쌓는 것보다 효율적.

Git Worktrees — 겹치는 병렬 Claude 인스턴스들이 충돌 없이 작업할 수 있도록.

git worktree add ../feature-branch feature-branch
# 각 워크트리에서 별도의 Claude 인스턴스 실행

tmux — 장시간 실행 명령 관리:

tmux new -s dev
# Claude가 여기서 명령 실행, detach/reattach 가능
tmux attach -t dev

mgrep > grep

mgrep는 ripgrep/grep보다 상당한 개선이다. 플러그인 마켓플레이스로 설치 후 /mgrep 스킬 사용.

mgrep "function handleSubmit"              # 로컬 검색
mgrep --web "Next.js 15 app router changes" # 웹 검색

기타 유용한 커맨드

커맨드	기능
`/rewind`	이전 상태로 되돌리기
`/statusline`	브랜치, 컨텍스트 %, 할 일 등으로 커스터마이즈
`/checkpoints`	파일 레벨 undo 포인트
`/compact`	수동 컨텍스트 압축 트리거

GitHub Actions CI/CD

PR에 코드 리뷰를 GitHub Actions로 설정할 수 있다. Claude가 자동으로 PR을 리뷰하도록 구성 가능.

샌드박싱

위험한 작업에는 샌드박스 모드를 사용한다 — Claude가 실제 시스템에 영향을 주지 않는 제한된 환경에서 실행된다.

--dangerously-skip-permissions는 반대로 Claude에게 자유를 주는 것인데, 주의하지 않으면 파괴적일 수 있다.

8. 에디터 연동

Zed (Affaan의 선택)

Rust 기반 에디터로 가볍고 빠르며, 대규모 코드베이스에서도 렉이 없다.

Zed가 Claude Code와 잘 맞는 이유:

Agent Panel 통합 — Claude가 편집하는 파일 변경을 실시간 추적. 에디터를 떠나지 않고 Claude가 참조하는 파일 사이를 점프
성능 — Rust로 작성되어 즉시 열리고 대규모 코드베이스도 렉 없이 처리
CMD+Shift+R 커맨드 팔레트 — 커스텀 슬래시 커맨드, 디버거, 도구에 검색 가능한 UI로 빠르게 접근
최소 리소스 사용 — 무거운 작업 중에도 Claude와 시스템 리소스를 경쟁하지 않음
Vim 모드 — 풀 vim 키바인딩 지원

에디터 연동 팁:

화면 분할 — 한쪽에 터미널(Claude Code), 다른 쪽에 에디터
Ctrl+G — Claude가 현재 작업 중인 파일을 Zed에서 즉시 열기
Following Mode — Zed 우하단의 불스아이(bullseye) 아이콘으로 Claude가 편집하는 파일을 자동 따라감
Auto-save 활성화 — Claude의 파일 읽기가 항상 최신 상태
Git 통합 — 에디터의 git 기능으로 Claude의 변경 사항을 커밋 전에 리뷰
File watcher — 대부분의 에디터가 변경된 파일을 자동 리로드하는데, 활성화 확인

VSCode / Cursor

터미널 포맷으로 쓸 수도 있고(\ide로 에디터 자동 동기화 + LSP 기능 — 플러그인이 있는 지금은 다소 중복), 익스텐션으로 더 통합된 UI를 쓸 수도 있다.

참고: code.claude.com/docs/en/vs-code

9. Affaan의 실제 셋업 공개

플러그인 (동시에 4~5개만 활성화)

ralph-wiggum@claude-code-plugins        # 루프 자동화
frontend-design@claude-code-plugins     # UI/UX 패턴
commit-commands@claude-code-plugins     # Git 워크플로우
security-guidance@claude-code-plugins   # 보안 체크
pr-review-toolkit@claude-code-plugins   # PR 자동화
typescript-lsp@claude-plugins-official  # TS 지능
hookify@claude-plugins-official         # 훅 생성
code-simplifier@claude-plugins-official # 코드 단순화
feature-dev@claude-code-plugins         # 기능 개발
explanatory-output-style@claude-code-plugins  # 설명적 출력 스타일
code-review@claude-code-plugins         # 코드 리뷰
context7@claude-plugins-official        # 라이브 문서
pyright-lsp@claude-plugins-official     # Python 타입 체크
mgrep@Mixedbread-Grep                   # 강화된 검색

MCP 서버 (14개 설정, 프로젝트당 5~6개만 활성화)

{
  "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
  "firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"] },
  "supabase": {
    "command": "npx",
    "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_REF"]
  },
  "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  },
  "vercel": { "type": "http", "url": "https://mcp.vercel.com" },
  "railway": { "command": "npx", "args": ["-y", "@railway/mcp-server"] },
  "cloudflare-docs": { "type": "http", "url": "https://docs.mcp.cloudflare.com/mcp" },
  "cloudflare-workers-bindings": {
    "type": "http", "url": "https://bindings.mcp.cloudflare.com/mcp"
  },
  "cloudflare-workers-builds": {
    "type": "http", "url": "https://builds.mcp.cloudflare.com/mcp"
  },
  "cloudflare-observability": {
    "type": "http", "url": "https://observability.mcp.cloudflare.com/mcp"
  },
  "clickhouse": { "type": "http", "url": "https://mcp.clickhouse.cloud/mcp" },
  "AbletonMCP": { "command": "uvx", "args": ["ableton-mcp"] },
  "magic": { "command": "npx", "args": ["-y", "@magicuidesign/mcp@latest"] }
}

프로젝트별 비활성화 (~/.claude.json의 projects.[path].disabledMcpServers):

{
  "disabledMcpServers": [
    "playwright",
    "cloudflare-workers-builds",
    "cloudflare-workers-bindings",
    "cloudflare-observability",
    "cloudflare-docs",
    "clickhouse",
    "AbletonMCP",
    "context7",
    "magic"
  ]
}

"14개 MCP를 설정해두지만, 프로젝트당 5~6개만 활성화한다. 이게 컨텍스트 윈도우를 건강하게 유지하는 핵심이다."

핵심 Hooks

{
  "PreToolUse": [
    { "matcher": "npm|pnpm|yarn|cargo|pytest", "hooks": ["tmux 리마인더"] },
    { "matcher": "Write && .md file", "hooks": ["README/CLAUDE 외 .md 생성 차단"] },
    { "matcher": "git push", "hooks": ["에디터에서 리뷰 열기"] }
  ],
  "PostToolUse": [
    { "matcher": "Edit && .ts/.tsx/.js/.jsx", "hooks": ["prettier --write"] },
    { "matcher": "Edit && .ts/.tsx", "hooks": ["tsc --noEmit"] },
    { "matcher": "Edit", "hooks": ["console.log 경고"] }
  ],
  "Stop": [
    { "matcher": "*", "hooks": ["수정된 파일에서 console.log 감사"] }
  ]
}

Rules 구조

~/.claude/rules/
  security.md      # 필수 보안 체크
  coding-style.md  # 불변성, 파일 크기 제한
  testing.md       # TDD, 80% 커버리지
  git-workflow.md  # Conventional Commits
  agents.md        # 서브에이전트 위임 규칙
  patterns.md      # API 응답 포맷
  performance.md   # 모델 선택 (Haiku vs Sonnet vs Opus)
  hooks.md         # 훅 문서화

Shorthand Guide 핵심 요약

과도하게 복잡하게 만들지 마라 — 설정은 아키텍처가 아니라 미세 조정처럼 대해라
컨텍스트 윈도우는 소중하다 — 안 쓰는 MCP와 플러그인은 비활성화
병렬 실행 — /fork로 대화 분기, git worktrees 활용
반복을 자동화 — 포매팅, 린팅, 리마인더용 훅
서브에이전트의 스코프를 제한 — 도구가 적을수록 집중된 실행

Part 2: Longform Guide — 실전 운영 테크닉

Longform Guide는 "설정한 걸 어떻게 잘 굴리나"에 대한 가이드다. 토큰 경제학, 메모리 지속성, 검증 패턴, 병렬화 전략, 재사용 워크플로우의 복리 효과를 다룬다.

전제조건: Shorthand Guide의 skills, agents, hooks, MCPs가 이미 설정되어 있어야 한다.

10. 컨텍스트 & 메모리 관리

세션 간 기억 유지: 세션 요약 파일 패턴

Claude Code는 세션이 끝나면 기억을 잃는다. 이를 해결하는 가장 좋은 방법:

세션 끝에 Claude가 현재 상태를 .tmp 파일로 요약 저장
다음 날 그 파일 경로만 제공하면 이어서 작업
세션마다 새 파일 생성 — 옛날 컨텍스트가 새 작업을 오염시키지 않도록

파일에 반드시 포함할 내용:

성공한 접근법 (증거 포함)
시도했지만 실패한 접근법
아직 시도하지 않은 접근법
남은 할 일

~/.claude/sessions/2026-03-04-buryit-auth.tmp
~/.claude/sessions/2026-03-04-buryit-mapbox.tmp
~/.claude/sessions/2026-03-05-buryit-graphql.tmp

세션 로그 예시: everything-claude-code/examples/sessions/

전략적 컨텍스트 정리

auto compact를 끄고, 논리적 분기점에서 수동으로 /compact를 실행한다.

왜?

Auto-compact는 아무 때나 발동 — 한창 작업 중간에 컨텍스트를 날릴 수 있음
전략적 compact는 논리적 단계 사이에서 발동:
- 탐색 끝 → 실행 시작 전에 compact
- 마일스톤 완료 → 다음 시작 전에 compact

Strategic Compact Skill

PreToolUse 훅에 걸어서 도구 호출 50번마다 "compact 고려해봐"라고 알려주는 스크립트:

#!/bin/bash
# Strategic Compact Suggester
# PreToolUse on Edit/Write operations에 연결

COUNTER_FILE="/tmp/claude-tool-count-$$"
THRESHOLD=${COMPACT_THRESHOLD:-50}

if [ -f "$COUNTER_FILE" ]; then
  count=$(cat "$COUNTER_FILE")
  count=$((count + 1))
  echo "$count" > "$COUNTER_FILE"
else
  echo "1" > "$COUNTER_FILE"
  count=1
fi

if [ "$count" -eq "$THRESHOLD" ]; then
  echo "[StrategicCompact] $THRESHOLD tool calls reached - consider /compact if transitioning phases" >&2
fi

고급: 동적 시스템 프롬프트 주입

CLAUDE.md나 .claude/rules/에 모든 걸 넣는 대신, CLI 플래그로 동적으로 컨텍스트를 주입하는 패턴이다.

claude --system-prompt "$(cat memory.md)"

왜 @파일 참조와 다른가?

방법	작동 방식	우선순위
`@memory.md` 또는 `.claude/rules/`	대화 중 Read 도구로 읽음	도구 결과 (가장 낮음)
`--system-prompt`	대화 시작 전 시스템 프롬프트에 주입	시스템 레벨 (가장 높음)

LLM의 지시 우선순위: 시스템 프롬프트 > 유저 메시지 > 도구 결과

절대 지켜야 하는 규칙이나 프로젝트 제약사항은 시스템 프롬프트에 넣는 게 더 확실하다.

실용적 설정 — 상황별 alias:

# 일반 개발
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'

# PR 리뷰 모드
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'

# 리서치/탐색 모드
alias claude-research='claude --system-prompt "$(cat ~/.claude/contexts/research.md)"'

dev.md → 구현에 집중
review.md → 코드 품질/보안에 집중
research.md → 행동 전 탐색에 집중

단, Affaan 본인도 인정하듯 "대부분의 경우 차이가 미미하고, 오히려 설정 오버헤드가 더 클 수 있다."

메모리 지속성 훅: 세션 라이프사이클 자동화

대부분이 모르거나 활용하지 않는 훅들을 체인으로 연결:

세션 1                              세션 2
─────────                          ─────────
[시작]                              [시작]
  │                                   │
  ▼                                   ▼
SessionStart 훅                    SessionStart 훅 ← 이전 컨텍스트 자동 로드
  │ (읽을 것 없음)                     │
  ▼                                   ▼
[작업 중]                           [작업 중] (정보 있는 상태!)
  │
  ▼
PreCompact 훅 → 압축 전에 중요 상태 저장
  │
  ▼
[압축됨]
  │
  ▼
Stop 훅 → ~/.claude/sessions/에 영구 저장 ──────►

Hook 설정:

{
  "hooks": {
    "PreCompact": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/memory-persistence/pre-compact.sh"
      }]
    }],
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/memory-persistence/session-start.sh"
      }]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/memory-persistence/session-end.sh"
      }]
    }]
  }
}

각 스크립트의 역할:

pre-compact.sh — 압축 이벤트를 로그하고, 활성 세션 파일을 타임스탬프로 업데이트
session-start.sh — 최근 7일 세션 파일을 확인하고, 사용 가능한 컨텍스트와 학습된 스킬을 알려줌
session-end.sh — 일일 세션 파일을 템플릿으로 생성/업데이트, 시작/종료 시간 추적

이 세 개를 체인으로 연결하면 수동 개입 없이 세션 간 기억이 지속된다.

11. 지속적 학습 시스템

문제

"코르티솔이 치솟으면서 전 세션에서 이미 하지 말라고 했던 걸 Claude가 또 하는 걸 보며 답답하게 소리 지르는 상황."

토큰 낭비, 컨텍스트 낭비, 시간 낭비.

해결: Continuous Learning Skill

Claude Code가 사소하지 않은 것을 발견하면 — 디버깅 기법, 우회법, 프로젝트 특화 패턴 — 그 지식을 새 스킬로 저장한다. 다음에 비슷한 문제가 나오면 자동으로 로드.

작동 방식:

Stop 훅으로 세션 끝에 자동 실행. 세션을 분석해서 추출할 가치가 있는 패턴(에러 해결, 디버깅 기법, 우회법 등)을 ~/.claude/skills/learned/에 저장.

왜 Stop 훅인가? (UserPromptSubmit 대신)

UserPromptSubmit은 매 메시지마다 실행 — 모든 프롬프트에 지연이 생기고 과도한 오버헤드. Stop은 세션 끝에 한 번만 실행 — 가볍고, 전체 세션을 한꺼번에 평가할 수 있어서 더 효과적.

설치:

mkdir -p ~/.claude/skills/continuous-learning
curl -sL https://raw.githubusercontent.com/affaan-m/everything-claude-code/main/skills/continuous-learning/evaluate-session.sh \
  > ~/.claude/skills/continuous-learning/evaluate-session.sh
chmod +x ~/.claude/skills/continuous-learning/evaluate-session.sh

Hook 설정:

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning/evaluate-session.sh"
      }]
    }]
  }
}

수동 추출: /learn 커맨드

세션 끝까지 기다릴 필요 없다. /learn 커맨드로 세션 중간에 "방금 해결한 거 기록해"를 할 수 있다. 패턴을 추출하고, 스킬 파일 초안을 작성하고, 확인 후 저장.

세션 로그 패턴

~/.claude/sessions/YYYY-MM-DD-topic.tmp — 세션당 하나. 현재 상태, 완료 항목, 차단 요소, 핵심 결정, 다음 세션을 위한 컨텍스트를 포함.

다른 사람들의 자기 개선 메모리 패턴

@RLanceMartin의 "일기(Diary)" 패턴:

세션 로그를 반성(reflection)해서 유저 선호를 추출한다. 매 세션 후 reflection agent가 잘 된 것, 실패한 것, 수정한 것을 추출 → memory 파일을 업데이트 → 다음 세션에 자동 로드.

출처: rlancemartin.github.io/2025/12/01/claude_diary/

@alexhillman의 선제적 제안 패턴:

15분마다 시스템이 선제적으로 개선점을 제안 → 승인/거부 → 시간이 지나면서 승인 패턴 자체를 학습.

12. 토큰 최적화

핵심 전략: 서브에이전트 아키텍처로 모델 비용 최소화

작업별로 가장 저렴하면서 충분한 모델을 배정하는 것이 가장 중요하다.

상황	모델	이유
일반 코딩 90%	Sonnet	기본값
첫 시도 실패, 5개+ 파일 수정, 아키텍처, 보안	Opus	어려운 작업
반복적, 지시 명확, 멀티에이전트 워커	Haiku	싸고 빠름

비용 분석:

Sonnet 4.5: 입력 $3/M, 출력 $15/M
Opus 4.5: 입력 $5/M, 출력 $25/M
Sonnet vs Opus = 1.67배 가격 차이 → 절대적으로는 절약이지만 상대적으로 미미
Haiku vs Opus = 5배 가격 차이 → 진짜 유의미한 절약
Affaan의 결론: "Sonnet 4.5는 현재 애매한 포지션이다. Haiku + Opus 조합이 가장 합리적"

에이전트 정의에서 모델 지정:

---
name: quick-search
description: Fast file search
tools: Glob, Grep
model: haiku  # 싸고 빠름
---

벤치마킹으로 모델 선택 검증 (선택적, 더 깊은 접근)

잘 정의된 목표와 작업이 있는 레포를 준비한다. 각 git worktree에 하나의 모델만 할당:

각 워크트리에서 모든 서브에이전트를 하나의 모델로 통일
작업이 완료될 때마다 계획과 태스크에 로그
모든 서브에이전트를 최소 한 번은 사용
전체 패스 완료 후 중단하고 진행 상황 감사
diff 비교, 균일한 유닛/통합/E2E 테스트를 모든 워크트리에서 실행
통과/실패 케이스 수로 수치적 벤치마크 산출
모두 통과하면 → 엣지 케이스를 추가하거나 테스트 복잡도를 높임

이 과정이 가치 있는지는 본인의 비용 민감도에 달려 있다.

도구별 최적화

grep → mgrep 교체: 다양한 작업에서 토큰 소비가 평균 절반으로 줄어든다.

출처: github.com/mixedbread-ai/mgrep

백그라운드 프로세스: Claude가 전체 출력을 스트리밍할 필요 없으면 tmux로 밖에서 돌리고, 필요한 부분만 복사해서 넘겨준다. 입력 토큰을 대폭 절약.

비용의 대부분은 입력 토큰에서 나온다고 생각하기 쉽지만, Opus 4.5 기준 입력 $5/M vs 출력 $25/M으로 출력이 5배 비싸다. 그래도 입력 볼륨이 훨씬 크기 때문에 입력 토큰 절약이 여전히 중요하다.

모듈러 코드베이스 = 더 싼 토큰

파일이 수천 줄이면:

Claude가 읽는 데만 여러 도구 호출 필요
중간에 "파일이 매우 길어서 계속 읽겠다"고 알림
이 과정에서 정보를 잃을 수 있음
멈추고 다시 읽는 데 추가 토큰 소비

파일을 수백 줄 단위로 모듈화하면 토큰 비용 절감 + 첫 시도 성공률 증가.

추천 모듈러 구조:

src/
├── apps/               # 진입점 (API, CLI, Workers)
│   ├── api-gateway/
│   └── cron-jobs/
├── modules/            # 핵심 시스템
│   ├── ordering/       # 자체 완결 모듈
│   │   ├── api/        # 다른 모듈을 위한 공개 인터페이스
│   │   ├── domain/     # 비즈니스 로직 (순수)
│   │   ├── infrastructure/  # DB, 외부 클라이언트
│   │   ├── use-cases/  # 애플리케이션 로직 (오케스트레이션)
│   │   └── tests/
│   ├── catalog/
│   └── identity/
├── shared/             # 모든 모듈이 공유
│   ├── kernel/         # 베이스 클래스
│   ├── events/         # 글로벌 이벤트 버스
│   └── utils/          # 범용 헬퍼
└── main.ts

린 코드베이스 = 더 싼 토큰

코드베이스가 린할수록 토큰 비용이 줄어든다. 스킬과 커맨드로 지속적으로 리팩토링하고 데드 코드를 제거하는 것이 중요하다.

시스템 프롬프트 슬리밍 (극한 최적화)

Claude Code의 시스템 프롬프트가 약 18k 토큰 (~200k의 9%). 패치로 ~10k까지 줄일 수 있다 — 정적 오버헤드의 41% 절약.

YK Sugi의 system-prompt-patches 참고. 단, Affaan 본인은 "나는 안 함"이라고.

13. 검증 루프 & 평가(Evals)

관측성(Observability)

tmux 프로세스를 thinking 스트림에 연결 → 스킬 트리거 시 추적
PostToolUse 훅으로 Claude가 정확히 뭘 했는지, 변경과 출력이 뭔지 로깅

벤치마킹 워크플로우: A/B 비교

같은 작업을 두 워크트리에서 돌려서 비교:

        [같은 작업]
            │
     ┌──────┴──────┐
     ▼              ▼
  워크트리 A      워크트리 B
  (스킬 있음)     (스킬 없음)
     │              │
     ▼              ▼
  [결과 A]        [결과 B]
     │              │
     └──────┬───────┘
            ▼
       [git diff]
            │
     로그, 토큰 사용량,
     출력 품질 비교

평가 패턴 두 가지

체크포인트 기반 Eval:

[작업 1] → [체크포인트 #1: 검증] → 통과? → [작업 2] → [체크포인트 #2] → ...
                                    실패? → 수정 → 재검증

명확한 마일스톤이 있는 기능 구현에 적합

연속 Eval:

[작업] → [타이머/변경 감지] → [테스트 + 린트 실행]
                                  통과 → 계속
                                  실패 → 멈추고 수정

장시간 세션, 탐색적 리팩토링에 적합

어떤 걸 선택해야 하나? 기능 구현처럼 단계가 명확하면 체크포인트 기반, 탐색적 리팩토링이나 유지보수처럼 마일스톤이 불명확하면 연속 기반.

Affaan: "약간의 개입으로, 검증 접근법은 대부분의 기술 부채를 피하기에 충분하다. Claude가 작업 완료 후 스킬과 PostToolUse 훅으로 검증하게 하고, 지속적인 코드맵 업데이트가 변경 로그 역할을 한다. 엄격한 규칙을 세우면 Claude가 무작위 .md 파일을 만들거나 중복 파일, 데드 코드의 황무지를 남기는 것도 방지된다."

핵심 지표: pass@k vs pass^k

지표	의미	k=1	k=3	k=5
pass@k	k번 중 하나라도 성공	70%	91%	97%
pass^k	k번 전부 성공	70%	34%	17%

pass@k → "일단 되기만 하면 된다" (대부분의 개발 작업)
pass^k → "일관성이 중요하다" (결정론적 출력이 필요할 때)

평가자(Grader) 유형 (Anthropic 가이드)

유형	방법	장점	단점
코드 기반	문자열 매칭, 이진 테스트, 정적 분석	빠르고 싸고 객관적	유효한 변형에 취약
모델 기반	루브릭 채점, 자연어 단언, 쌍 비교	유연하고 뉘앙스 처리	비결정적, 비쌈
인간	SME 리뷰, 크라우드소싱, 샘플 체크	골드 스탠다드	비싸고 느림

Eval 로드맵 구축 (Anthropic 가이드)

일찍 시작 — 실제 실패에서 20~50개 간단한 태스크
유저 보고 실패를 테스트 케이스로 전환
모호하지 않은 태스크 작성 — 전문가 두 명이 같은 판단을 내릴 수 있어야
균형 잡힌 문제 세트 — 동작해야 하는 경우와 하지 않아야 하는 경우 모두 테스트
견고한 하네스 — 매 시도마다 깨끗한 환경에서 시작
에이전트가 생산한 결과를 채점, 경로가 아니라
많은 시도의 트랜스크립트를 읽어라
100% 통과율 = 테스트 추가 필요

출처: Anthropic — Demystifying evals for AI agents (2026.01)

14. 병렬화 전략

Affaan의 핵심 견해: 최소한의 병렬화로 최대한

"Boris가 로컬 5개 + 웹 5개를 제안했는데, 임의로 터미널 수를 정하는 것에 반대한다. 터미널 추가는 진짜 필요와 목적이 있을 때만."

"스크립트로 해결되면 스크립트를 써라. 메인 채팅에서 tmux로 인스턴스를 띄울 수 있으면 그렇게 해라. 목표는: 최소한의 병렬화로 얼마나 많이 해낼 수 있나."

입문자: 단일 인스턴스를 완전히 마스터한 후에 병렬화 시작
Affaan 본인도 대부분 2~3개만 사용, 최대 4개

Affaan의 선호 패턴

메인 채팅: 실제 코드 변경
포크된 채팅: 코드베이스 질문, 외부 문서 리서치, GitHub 검색, 일반 조사

코드 변경은 메인에서만 하고, 포크는 정보 수집용으로만.

캐스케이드 메서드

여러 Claude를 돌릴 때의 조직 패턴:

새 작업은 오른쪽 탭에 열기
왼쪽 → 오른쪽으로 스윕 (오래된 것 → 새로운 것)
일관된 방향 흐름 유지
필요할 때 특정 작업 체크
동시에 집중하는 건 최대 3~4개 — 그 이상은 멘탈 오버헤드가 생산성보다 빨리 증가

병렬 인스턴스 확장 시 필수사항

겹치는 코드를 건드리는 인스턴스가 여러 개면:

반드시 git worktrees 사용
각 워크트리마다 명확한 계획 필요
/rename <이름>으로 모든 채팅에 이름 붙이기 — 어떤 워크트리가 뭔지 헷갈리지 않도록

git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b
git worktree add ../project-refactor refactor-branch

# 각 워크트리에서 별도의 Claude 인스턴스
cd ../project-feature-a && claude

장점: git 충돌 없음, 깨끗한 작업 디렉토리, 출력 비교 용이, 같은 작업을 다른 접근으로 벤치마크 가능.

15. 프로젝트 시작 — Groundwork

Two-Instance Kickoff 패턴

새 프로젝트를 시작할 때 빈 레포에서 2개의 Claude 인스턴스로 시작:

인스턴스 1: 스캐폴딩 에이전트 (왼쪽 터미널)

프로젝트 구조 생성
설정 파일 세팅 (CLAUDE.md, rules, agents — Shorthand Guide의 모든 것)
컨벤션 확립
뼈대 코드 작성

인스턴스 2: 딥 리서치 에이전트 (오른쪽 터미널)

모든 서비스 연결, 웹 검색 등
상세 PRD(제품 요구사항 문서) 작성
아키텍처 Mermaid 다이어그램 생성
실제 문서에서 레퍼런스 클립 수집

시작 셋업: 왼쪽 터미널 = 코딩, 오른쪽 터미널 = 질문. /rename과 /fork 활용.

최소한으로 시작하는 게 더 빠르다. Context7을 매번 쓰거나 링크를 스크래핑하거나 Firecrawl MCP를 쓰는 건, 이미 깊이 파고든 상태에서 Claude가 문법을 틀리거나 구식 함수/엔드포인트를 쓸 때 효과적이다.

llms.txt 패턴

많은 문서 사이트가 LLM에 최적화된 깔끔한 문서 버전을 제공한다:

https://www.helius.dev/docs/llms.txt
https://docs.anthropic.com/llms.txt

문서 페이지의 URL 끝에 /llms.txt를 붙여보면 된다. 있으면 Claude에게 바로 먹일 수 있는 최적화된 버전을 얻을 수 있다.

16. 서브에이전트 고급 운영

서브에이전트 컨텍스트 문제

서브에이전트는 컨텍스트를 아끼려고 요약을 반환하지만, 오케스트레이터가 가진 "왜 이걸 하는지"라는 맥락을 모른다. 서브에이전트는 문자 그대로의 쿼리만 알지, 요청 뒤의 목적/이유를 모른다.

@PerceptualPeak의 비유: "상사가 너를 회의에 보내서 요약해오라고 한다. 네가 요약하면 상사는 10번 중 9번은 추가 질문을 한다. 네 요약에는 상사가 알아야 할 모든 게 포함되지 않는다 — 상사의 암묵적 맥락이 없으니까."

해결: 반복적 검색 패턴

오케스트레이터 (맥락 있음)
    │ 쿼리 + 목적(objective)과 함께 전달
    ▼
서브에이전트 (맥락 없음)
    │ 요약 반환
    ▼
평가: 충분한가?
    ├─ YES → 수락
    └─ NO → 후속 질문
              │
              ▼
         서브에이전트가 다시 조사 → 반환
              (최대 3사이클, 무한 루프 방지)

핵심: 쿼리만 주지 말고 broader objective도 같이 전달해야 서브에이전트가 요약에서 뭘 우선할지 안다.

오케스트레이터 순차 페이즈 패턴

Phase 1: RESEARCH (Explore agent)
  → 컨텍스트 수집, 패턴 식별
  → Output: research-summary.md

Phase 2: PLAN (planner agent)
  → research-summary.md 읽기
  → 구현 계획 작성
  → Output: plan.md

Phase 3: IMPLEMENT (tdd-guide agent)
  → plan.md 읽기
  → 테스트 먼저 작성
  → 코드 구현
  → Output: 코드 변경

Phase 4: REVIEW (code-reviewer agent)
  → 모든 변경 리뷰
  → Output: review-comments.md

Phase 5: VERIFY (build-error-resolver)
  → 테스트 실행
  → 이슈 수정
  → Output: 완료 or Phase 3으로 루프백

규칙:

각 에이전트는 하나의 입력 → 하나의 출력
출력이 다음 단계의 입력
페이즈를 건너뛰지 말 것 — 각각이 가치를 더함
에이전트 사이에 /clear 로 컨텍스트 신선하게
중간 출력은 파일로 저장 (메모리만 의존 X)

에이전트 추상화 티어리스트 (@menhguin)

Tier 1: 바로 효과 (쉬움)

패턴	설명
서브에이전트	컨텍스트 오염 방지 + 즉석 전문화. 멀티에이전트의 절반 효과지만 복잡도는 훨씬 낮음
메타프롬프팅	"3분 프롬프팅으로 20분짜리 작업을 안정적으로." 가정을 검증하고 안정성 향상
시작 시 질문 많이 받기	Plan 모드에서 질문에 답하면 됨. 일반적으로 효과적

Tier 2: 숙련 필요 (어려움)

패턴	주의점
장시간 에이전트	15분 vs 1.5시간 vs 4시간 작업의 형태와 트레이드오프 이해 필요. 긴 시행착오
병렬 멀티에이전트	분산이 매우 높음. 고복잡도 OR 잘 분리된 작업에서만 유용. "2개 작업이 10분 걸리는데 프롬프팅이나 병합에 시간을 쓰면 역효과"
역할 기반 멀티에이전트	"모델이 너무 빨리 진화해서 하드코딩된 휴리스틱이 의미 없어진다." 테스트 어려움
컴퓨터 사용 에이전트	매우 초기 패러다임. 길들이기 필요

핵심: Tier 1을 마스터하고 나서, 진짜 필요할 때만 Tier 2로.

17. MCP를 CLI로 대체하는 토큰 절약법

문제

GitHub, Supabase, Vercel, Railway 같은 MCP들은 대부분 해당 플랫폼의 CLI를 래핑한 것일 뿐이다. MCP는 편리한 래퍼지만 컨텍스트 비용이 따른다.

해결

MCP 기능을 스킬과 커맨드로 번들화한다. MCP가 노출하는 쉬운 도구들을 커맨드로 변환.

# GitHub MCP 대신
/gh-pr    # gh pr create를 선호 옵션으로 래핑

# Supabase MCP 대신
/db-query  # Supabase CLI를 직접 사용하는 스킬

기능은 같고, 편의성도 비슷한데, 컨텍스트 윈도우가 해방된다.

현재 상황 (2026년 초)

최근 Claude Code가 MCP 지연 로딩(lazy loading)을 도입해서 컨텍스트 윈도우 문제는 많이 개선되었다. 이전에는 MCP가 시작부터 윈도우를 잡아먹었지만 이제는 아니다.

그러나 토큰 사용량과 비용은 여전히 CLI + 스킬 방식이 유리하다. 특히 DB 쿼리나 배포 같은 무거운 MCP 작업에서 CLI로 실행하면 토큰 사용이 상당히 줄어든다.

18. 철학: 재사용 가능한 패턴에 투자하라

@omarsar0의 통찰

"초기에 재사용 가능한 워크플로우/패턴을 만드는 데 시간을 썼다. 만들 때는 지루했지만, 모델과 에이전트 하네스가 개선될수록 미친 복리(compounding) 효과가 있었다."

투자할 것

서브에이전트
스킬
커맨드
플래닝 패턴
MCP 도구
컨텍스트 엔지니어링 패턴

왜 복리인가

"이 워크플로우들은 Codex 같은 다른 에이전트에도 그대로 전환 가능하다."

한 번 만들면 모델 업그레이드에도 그대로 작동한다. 패턴에 투자 > 특정 모델 트릭에 투자.

전체 요약

Shorthand Guide (기초 인프라)

구성 요소	역할	핵심
Skills	워크플로우 축약어	`~/.claude/skills/`
Commands	슬래시로 실행하는 스킬	`~/.claude/commands/`
Hooks	이벤트 트리거 자동화	PreToolUse, PostToolUse, Stop
Subagents	제한된 스코프의 위임 에이전트	`~/.claude/agents/`
Rules	항상 따르는 규칙	`~/.claude/rules/` 또는 CLAUDE.md
MCPs	외부 서비스 연결	활성화 10개 미만 유지
Plugins	도구 패키지	동시 활성화 4~5개

Longform Guide (실전 운영)

테크닉	핵심
세션 요약 파일	세션마다 .tmp에 상태 저장 → 다음 세션에 로드
전략적 compact	auto 끄고 논리적 분기점에서 수동 /compact
동적 시스템 프롬프트	--system-prompt로 상황별 컨텍스트 주입
메모리 지속성 훅	PreCompact → Stop → SessionStart 체인
지속적 학습	Stop 훅으로 세션 분석 → 스킬 자동 생성
토큰 최적화	Haiku+Opus 조합, mgrep, 모듈러 코드, 백그라운드 프로세스
검증 루프	체크포인트 기반 vs 연속 기반 eval
병렬화	최소한의 인스턴스, 메인=코드/포크=리서치, 캐스케이드
프로젝트 시작	Two-Instance Kickoff (스캐폴딩 + 딥 리서치)
서브에이전트 고급	반복적 검색 패턴, 순차 페이즈, Tier 1부터
MCP→CLI 대체	CLI+스킬로 토큰 절약, 기능은 동일
복리 투자	패턴에 투자 > 모델 트릭에 투자

참고 자료

Shorthand Guide 원문 (X)
Longform Guide 원문 (X)
everything-claude-code (GitHub)
Anthropic: Demystifying evals for AI agents (2026.01)
Anthropic: "Claude Code Best Practices" (2025.04)
Fireworks AI: "Eval Driven Development with Claude Code" (2025.08)
YK Sugi: 32 Claude Code Tips (2025.12)
Addy Osmani: "My LLM coding workflow going into 2026"
@PerceptualPeak: Sub-Agent Context Negotiation
@menhguin: Agent Abstractions Tierlist
@omarsar0: Compound Effects Philosophy
RLanceMartin: Session Reflection Pattern
@alexhillman: Self-Improving Memory System
Claude API Pricing
mgrep (GitHub)

이 글은 Affaan Mustafa(@affaanmustafa)의 Shorthand Guide와 Longform Guide를 한국어로 취합 정리한 것입니다. 2026년 3월 기준.

출처

https://roboco.io/posts/everything-claude-code-distilled/
https://digitalbourgeois.tistory.com/2636

hahhhm

이전 포스트

Claude Code 실전 워크플로우 총정리

다음 포스트

Everything Claude Code

저자 소개: Affaan Mustafa

목차

Part 1: Shorthand Guide — 기초 인프라 구축

목차

Part 1: Shorthand Guide — 기초 인프라 구축

Part 2: Longform Guide — 실전 운영 테크닉

Part 1: Shorthand Guide — 기초 인프라 구축

1. Skills & Commands

Skills이란?

Skills vs Commands

디렉토리 구조 예시

코드맵 업데이트 스킬

2. Hooks

Hooks이란?

Hook 타입 총정리

실전 예시: 장시간 명령 전 tmux 리마인더

3. Subagents (서브에이전트)

서브에이전트란?

디렉토리 구조

4. Rules & Memory

Rules이란?

두 가지 접근법

규칙 예시

5. MCPs (Model Context Protocol)

MCP란?

⚠️ 치명적: 컨텍스트 윈도우 관리

6. Plugins

플러그인이란?

설치 방법

LSP 플러그인

7. Tips & Tricks

키보드 단축키

병렬 워크플로우

mgrep > grep

기타 유용한 커맨드

GitHub Actions CI/CD

샌드박싱

8. 에디터 연동

Zed (Affaan의 선택)

VSCode / Cursor

9. Affaan의 실제 셋업 공개

플러그인 (동시에 4~5개만 활성화)

MCP 서버 (14개 설정, 프로젝트당 5~6개만 활성화)

핵심 Hooks

Rules 구조

Shorthand Guide 핵심 요약

Part 2: Longform Guide — 실전 운영 테크닉

10. 컨텍스트 & 메모리 관리

세션 간 기억 유지: 세션 요약 파일 패턴

전략적 컨텍스트 정리

Strategic Compact Skill

고급: 동적 시스템 프롬프트 주입

메모리 지속성 훅: 세션 라이프사이클 자동화

11. 지속적 학습 시스템

문제

해결: Continuous Learning Skill

수동 추출: /learn 커맨드

세션 로그 패턴

다른 사람들의 자기 개선 메모리 패턴

12. 토큰 최적화

핵심 전략: 서브에이전트 아키텍처로 모델 비용 최소화

벤치마킹으로 모델 선택 검증 (선택적, 더 깊은 접근)

도구별 최적화

모듈러 코드베이스 = 더 싼 토큰

린 코드베이스 = 더 싼 토큰

시스템 프롬프트 슬리밍 (극한 최적화)

13. 검증 루프 & 평가(Evals)

관측성(Observability)

벤치마킹 워크플로우: A/B 비교

평가 패턴 두 가지

핵심 지표: pass@k vs pass^k

평가자(Grader) 유형 (Anthropic 가이드)

Eval 로드맵 구축 (Anthropic 가이드)

14. 병렬화 전략

Affaan의 핵심 견해: 최소한의 병렬화로 최대한

Affaan의 선호 패턴

캐스케이드 메서드

병렬 인스턴스 확장 시 필수사항

15. 프로젝트 시작 — Groundwork