CC Sessions로 AI 코딩의 혼돈을 종식시키는 법

 

GitHub - GWUDCAP/cc-sessions: an opinionated approach to productive development with Claude Code

 

당신이 여기 오게 된 이유

이런 경험 있으신가요?

• 💭 LLM 프로그래밍 가능성에 설레어 Cursor/Cline/Claude Code를 설치했다
• 😬 처음엔 신기하고 좋았다. 컨텍스트 매니저 안 짜도 되니까!
• 🤮 근데 Claude가 이상한 짓을 하기 시작했다

Claude에게 한 함수에만 에러 핸들링 추가하라고 했더니:

• 파일의 모든 함수에 에러 핸들링을 추가함
• 에러 타입도 바꿈
• 로깅 형식도 바꿈
• 어째선지 들여쓰기도 달라짐

컨텍스트 윈도우 문제가 짜증나기 시작했다:

• 오늘만 다섯 번째로 똑같은 아키텍처 설명 중
• "데이터베이스를 찾아볼게요" - 야, 우리 지난 6시간 동안 PostgreSQL 쓰고 있었잖아. 방금 거기 있었는데?

CLAUDE.md가 실제 코드보다 길어졌다:

- NEVER use class components.
- ALWAYS use the existing auth middleware.
- DO NOT refactor unrelated code.
- REMEMBER we use PostgreSQL.

근데 Claude는 첫 줄만 읽고 나머지는 환각 상태로 들어간다.

코드베이스는 '완성'됐는데:

• 같은 DB 연결에 글로벌 클라이언트가 3개
• 그 중 2개는 환각으로 만든 환경변수 사용
• 유틸 함수가 4개 파일에 중복
• 코드의 20%는 "왜 이게 여기 없고 저기 있는지" 설명하는 주석

이제 뭐가 잘못됐는지도 모르겠고, 고치려면 내가 안 짠 코드를 내가 선택하지 않을 패턴으로 이해해야 한다.

CC Sessions가 해결한 것들

Claude Code Sessions(이하 CC Sessions)는 이 모든 문제를 규칙이나 프롬프트가 아닌 강제적인 후크(hook) 시스템으로 해결합니다.

목차

1. CC Sessions란?
2. 설치 및 초기 설정
3. 핵심 개념: 토론 모드 vs 실행 모드
4. 작업(Task) 생성 및 관리
5. 실전 예제: 버튼 인터페이스 수정하기
6. 고급 기능 및 커스터마이징

---

CC Sessions란?

CC Sessions는 Claude Code의 혼돈을 종식시키는 시스템입니다. 더 많은 규칙이나 문서, 프롬프팅 기법이 아니라 Claude가 우회할 수 없는 강제적인 후크를 통해 작동합니다.

당신이 바라던 것들

• ✅ Claude가 코드를 쓰기 전에 먼저 대화해서 500줄짜리 구현을 피한다
• ✅ 컨텍스트 윈도우가 죽어도 모든 것을 잃지 않고, 내일 돌아와도 작업을 기억한다
• ✅ 매 세션마다 아키텍처를 설명하지 않아도 되고, 이전 작업에서 이해한 내용을 상속받는다
• ✅ 버튼 추가하는데 멀쩡한 코드를 랜덤하게 리팩토링하지 않는다
• ✅ 5개 레포에서 어느 브랜치에 있는지 수동으로 확인 안 해도 되고, 잘못된 브랜치 편집을 막아준다
• ✅ 파일 건드릴 때마다 새로운 패턴을 발명하지 않고 코드베이스의 패턴을 따른다
• ✅ CLAUDE.md에 점점 더 절박한 규칙을 쓰지 않아도 되고, 일관된 행동을 강제한다

작동 원리

Sessions는 이 모든 것을 가능하게 합니다. 더 많은 규칙이나 문서가 아니라 에이전트 루프에 대한 독재적 통치를 통해서요.

핵심 메커니즘:

1. 후크(Hooks) - Claude가 우회할 수 없는 강제 시스템
2. 상태 관리(State) - 세션 간 지속되는 영구 상태
3. 태스크 시스템(Tasks) - 실제로 기억하는 작업 관리
4. 서브에이전트(Subagents) - 제대로 작동하는 전문 에이전트들

---

설치 및 초기 설정

필요한 것

• Claude Code (당연히 있겠죠?)
• Python 3 + pip (후크용)
• Git (아마도)
• 5분

설치 방법

NPM/NPX (TypeScript 개발자)

cd your-project
npx cc-sessions              # 일회성 설치
# 또는
npm install -g cc-sessions   # 글로벌 설치
cc-sessions                  # 프로젝트에서 실행

Pip/Pipx/UV (Python 개발자)

pipx install cc-sessions     # 격리된 설치 (추천!)
cd your-project
cc-sessions                  # 인스톨러 실행

# 또는
pip install cc-sessions      # 일반 pip

# 또는
uv pip install cc-sessions   # UV 패키지 매니저

직접 Bash ('빌드부터' 파이터)

git clone https://github.com/GWUDCAP/cc-sessions
cd your-project
/path/to/cc-sessions/install.sh

대화형 설치 과정

설치 프로그램이 물어볼 것들:

1. Git 설정

기본 Git 브랜치는? main
레포 타입은? monorepo

• 태스크 작업 시 자동으로 브랜치를 생성하고 완료 후 여기로 병합됩니다.

2. 커밋 설정

파일 스테이징: 모두 스테이징
커밋 메시지 스타일: 상세(detailed)
자동 병합: 활성화
푸시 확인: 물어보기

3. 안전 설정

읽기 전용 CLI 도구: z, cat, less 등 추가
쓰기 명령어: 토론 모드에서 항상 차단
알 수 없는 명령어: 자동으로 차단 (extra safe on)

4. 트리거 문구 커스터마이징

이것이 핵심입니다! 자신만의 트리거 문구를 설정할 수 있습니다:

실행 모드 전환: "yurt" (또는 원하는 문구)
토론 모드 전환: "SILENCE"
작업 생성: "mech"
작업 시작: "start↑"
작업 완료: "fenito"
컨텍스트 압축: "squish"

실전 팁: 일상 대화에서 절대 쓰지 않을 독특한 단어를 선택하세요. "yurt"나 "fenito" 같은 단어는 우발적으로 모드 전환이 발생하지 않습니다.

5. 추가 설정

상태 표시줄: 활성화
태스크 브랜치 외 편집 차단: 활성화
자동 Ultrathink: 활성화 (Pro 구독자 권장)
Nerd Fonts: 활성화 (터미널 지원 시)
컨텍스트 압축 경고: 85%, 90%

---

핵심 개념: DAIC (Discussion-Action-Implementation Control)

CC Sessions의 가장 혁명적인 특징은 DAIC 시스템입니다. 이는 단순한 모드 구분이 아니라 후크로 강제되는 행동 제약입니다.

토론 모드 (Discussion Mode) - 기본 모드

Sessions 이전:

사용자: auth flow에 에러 핸들링 추가해줘
Claude: 포괄적인 에러 핸들링을 추가하겠습니다!
[즉시 15개 파일 편집 시작]
[모든 함수에 try-catch 추가]
[에러 메시지 포맷 변경]
[로깅 라이브러리 리팩토링]
사용자: 잠깐 멈춰 멈춰 STOP
Claude: 코드베이스 전체의 에러 핸들링을 업데이트했어요!
사용자: [소리 지름]

Sessions 이후:

사용자: auth flow에 에러 핸들링 추가해줘
Claude: 먼저 현재 에러 패턴을 분석할게요...
[Claude가 auth 코드를 읽고 기존 에러 핸들링 검토]

Claude: 현재 에러 핸들링 패턴을 찾았습니다:
- 커스텀 AppError 클래스 사용 중
- 에러는 middleware/errorHandler.ts로 버블링
- Auth 에러는 401/403 상태코드 사용
- 프로덕션에서는 Sentry로 로깅

login과 refresh token 엔드포인트에 
기존 AppError 패턴을 따라 에러 핸들링을 추가하겠습니다. 
진행할까요?

사용자: 완벽해, 시작해
Claude: [이제 정확히 2개 파일만 올바른 패턴으로 수정]

차이점:

• 토론 모드에서는 후크가 Write/Edit 도구를 물리적으로 차단
• Claude는 승인 받기 전까지 코드를 수정할 수 없음
• 우회 불가능, 예외 없음, 깜짝 리팩토링 없음

실행 모드 (Implementation Mode)

• 트리거 문구로 전환 (예: "yurt", "go ahead", "ship it")
• Claude가 실제로 코드를 수정할 수 있음
• 파일 생성, 수정, Git 커밋 가능
• 여전히 브랜치 강제 및 패턴 준수는 유지

[상태 표시줄] DAIC: Discussion | ✎ 3 files | [4 open]
                    ↓ (트리거 문구)
[상태 표시줄] DAIC: Implementation | ✎ 5 files | [4 open]

Bypass 모드

빠른 실험이나 탐색용:

/sessions state mode off

• 토론/실행 경계 없음
• 모든 제약 해제
• 프로토타이핑에 유용
• 주의: 프로덕션 코드 작업 시 비추천!

왜 DAIC가 게임체인저인가?

전통적인 접근 (실패):

# CLAUDE.md (1,247줄)
## 절대 하지 마세요 (제발 따라주세요)
- NEVER use require(), we use import
- NEVER use callbacks, we use async/await  
- NEVER refactor working code
[... 200개의 NEVER 규칙 ...]

Claude는 첫 줄만 읽고 나머지는 잊어버립니다.

CC Sessions 접근 (성공):

# CLAUDE.md (< 100줄)
## 프로젝트 개요
AI waifu 플랫폼. Node + React + PostgreSQL.

## 행동 규칙
@CLAUDE.sessions.md

규칙은 더 이상 제안이 아닙니다. 코드로 강제됩니다:

• 허가 없이 편집 불가? → 후크가 도구 차단
• 잘못된 브랜치? → 후크가 편집 차단
• 패턴 준수 필요? → 컨텍스트 매니페스트에 문서화됨
• PostgreSQL 기억? → 자동 로드되는 태스크 컨텍스트에 있음

당신의 문서는 프로젝트를 설명합니다. 후크는 행동을 강제합니다. Claude는 후크를 무시할 수 없습니다.

---

작업(Task) 생성 및 관리

작업 생성 워크플로우

1단계: 작업 생성

사용자: mech IO web 컴포넌트의 모든 버튼 인터페이스 정리.
       현재 인터페이스가 일관성 없고 예측 가능한 동작을 제공하지 않음.

Claude가 자동으로:

1. 작업 이름 제안: fix-button-link-interface
2. 작업 파일 생성 (.cc/tasks/fix-button-link-interface.md)
3. 프론트매터 작성:

---
name: fix-button-link-interface
branch: task/fix-button-link-interface
status: pending
created: 2025-10-31
submodules: [io-web]
---

2단계: 문제 정의

Claude가 작업 파일을 채웁니다:

## Problem
버튼 팩토리들이 일관되지 않은 인터페이스를 제공합니다.
URL 파라미터 처리가 불안정하고 외부 링크 처리가 명확하지 않습니다.

## Success Criteria
- [ ] 모든 버튼 팩토리가 통일된 URL 파라미터 지원
- [ ] 자동 외부 링크 감지 및 새 탭 열기
- [ ] 타입 안전성 확보
- [ ] 일관된 API 제공

3단계: 컨텍스트 수집 에이전트

여기가 마법이 일어나는 곳입니다!

Claude: 컨텍스트 수집 에이전트를 실행할까요?
사용자: yes

기존 서브에이전트의 문제:

• Claude가 필요한 모든 컨텍스트와 함께 에이전트를 호출하는 명확한 방법이 없음
• Claude가 어떻게 프롬프트하는지 보이지 않음
• 에이전트가 무엇을 했는지 (또는 왜 실패했는지) 불명확함
• 10분 동안 "코드 리뷰" 중 API 에러 발생 → 메인 스레드로 돌아와 설명 없음
• 다시 실행? 🤷

CC Sessions의 개선된 서브에이전트:

현재 3가지 전문 에이전트:

1. Context Gathering Agent (컨텍스트 수집 에이전트)

사용자: 캐싱 업그레이드 작업 시작하자
Claude: 알겠습니다! current-task.json을 업데이트하고
       컨텍스트 수집 에이전트로 캐싱 시스템을 분석하겠습니다.

[에이전트가 별도 컨텍스트에서 실행 - 메인 스레드 오염 없음]

에이전트 결과: 포괄적인 컨텍스트 매니페스트 생성 완료:

캐싱 아키텍처:
- Redis: 세션 캐시 (30분 TTL)
- PostgreSQL materialized views: 리포트용
- React Query: 클라이언트 캐싱 (5분 stale time)
- CDN: 정적 자산 캐싱

핵심 패턴:
- 캐시 키 포맷: {service}:{entity}:{id}:{version}
- 무효화: CacheManager.invalidate() 통해 처리
- 모든 캐시 작업은 cache_operations 테이블에 로깅

구현 위치:
- 서버 캐시: /lib/cache/redis-cache.ts
- 클라이언트 캐시: /hooks/useQueryWithCache.ts
- 캐시 무효화: /api/middleware/cache-invalidator.ts

[전체 컨텍스트 매니페스트가 태스크 파일에 저장 - 영구 보존]

에이전트는 컨텍스트 윈도우 걱정 없이 모든 것을 분석할 수 있었습니다.

2. Code Review Agent (코드 리뷰 에이전트)

[작업 완료 시 자동 실행]
Claude: 코드 리뷰 에이전트를 실행합니다...

발견 사항:
경고 1: 5개 버튼 팩토리에 코드 중복
경고 2: 도메인 인식 외부 링크 감지 고려
제안 3: 에러 핸들링 테스트 케이스 추가

사용자: it loop (대화형 리뷰!)
Claude: 경고 1 - 코드 중복을 처리할까요?
사용자: 나중에
Claude: 경고 2 - 도메인 인식 로직 추가할까요?
사용자: 스킵
...

3. Logging Agent (로깅 에이전트)

[컨텍스트 압축 시 자동 실행]

기존 방식: Claude가 세션의 중요한 내용을 다시 출력해야 함
개선 방식: 로깅 에이전트가 전체 대화 히스토리를 받아서
          자동으로 로그 작성 → 메인 스레드로 전달

서브에이전트의 특별한 점:

1. 격리된 실행: 각 에이전트는 별도 컨텍스트에서 실행
2. 대화 히스토리 보존: .claude/state/{agent-name}/에 저장
3. 재사용 가능: 에이전트가 전체 대화 컨텍스트 로드 가능
4. 투명성: 무엇을 했는지 명확히 보고

컨텍스트 수집 에이전트 결과:

• 전체 코드베이스 분석 완료
• 관련 파일 및 코드 패턴 추출
• 아키텍처 이해 완료
• 태스크 파일에 컨텍스트 매니페스트 생성

## Context Manifest
관련 파일:
- src/components/Button/factories.ts (라인 45-120)
- src/types/ButtonProps.ts (라인 12-34)
- docs/component-api.md (전체)

패턴:
- 팩토리 패턴 사용
- TypeScript strict 모드
- URL 처리는 utils/url.ts 사용

왜 이게 게임 체인저일까요?

• Claude가 매번 코드베이스를 탐색할 필요 없음 ← 토큰 절약
• 작업 시작 시 정확한 컨텍스트 제공 ← 정확성 향상
• 에이전트가 실패해도 메인 스레드 오염 없음 ← 안정성
• 작업이 실제로 무엇을 배웠는지 영구 기록 ← 지식 축적

작업 인덱스 관리

여러 작업을 그룹화할 수 있습니다:

.cc/tasks/
├── indexes/
│   ├── io-web-tasks.md       # IO web 관련 작업들
│   ├── backend-api.md         # 백엔드 API 작업들
│   └── custom-gpt.md          # GPT 관련 작업들
└── fix-button-interface.md
└── add-dark-mode.md
└── refactor-api-client.md

세션 시작 시 자동으로 모든 작업 인덱스를 표시:

=== 작업 인덱스 ===
📦 io-web-tasks (3개 대기 중)
📦 backend-api (1개 대기 중)
📦 custom-gpt (2개 대기 중)

---

실전 예제: 버튼 인터페이스 수정하기

실제로 작업을 진행해봅시다.

1. 작업 시작

사용자: start↑ @fix-button-link-interface

@ 구문으로 작업 파일을 직접 참조합니다.

Claude가 자동으로:

1. 작업 로드: 상태 변경

[상태 표시줄] DISCUSS | main → fix-button-link-interface

1. 브랜치 체크아웃: Git 브랜치 전환

[상태 표시줄] main → task/fix-button-link-interface

1. 컨텍스트 로드: 이전에 수집한 컨텍스트 읽기

Claude: IO web의 버튼 링크 인터페이스 수정을 위한 
       컨텍스트를 로드했습니다.

작업 계획:
1. ButtonFactory interface에 url 파라미터 추가
2. 모든 버튼 팩토리 함수 업데이트
3. 자동 외부 링크 감지 로직 추가
4. 테스트 케이스 작성
5. 문서 업데이트

2. 작업 실행

사용자: yurt (실행 모드 전환!)

Claude: 지금 수정 시작합니다!

첫 번째 수정 - 타입 정의

// src/types/ButtonProps.ts
export interface ButtonFactoryOptions {
  label: string;
  icon?: IconType;
  variant?: 'primary' | 'secondary' | 'ghost';
  url?: string;              // 새로 추가!
  openInNewTab?: boolean;    // 새로 추가!
}

두 번째 수정 - 팩토리 함수들

// src/components/Button/factories.ts
export function createPrimaryButton(
  options: ButtonFactoryOptions
): ButtonProps {
  return {
    ...baseButtonProps,
    variant: 'primary',
    label: options.label,
    // URL 자동 처리 로직
    ...(options.url && {
      as: 'a',
      href: options.url,
      target: isExternalUrl(options.url) 
        ? '_blank' 
        : '_self',
      rel: isExternalUrl(options.url) 
        ? 'noopener noreferrer' 
        : undefined,
    }),
  };
}

세 번째 수정 - 유틸리티 함수

// src/utils/url.ts
export function isExternalUrl(url: string): boolean {
  try {
    const urlObj = new URL(url, window.location.href);
    return urlObj.hostname !== window.location.hostname;
  } catch {
    return false;
  }
}

3. 실시간 피드백

Claude: 모든 버튼 팩토리가 이제 URL 파라미터를 지원합니다.
       자동으로 외부 링크를 감지하여 새 탭에서 열립니다.

사용자: 잘했어! 근데 <a> 태그에 text-decoration이 
       들어가 있네. 없애줄래?

Claude: 바로 수정하겠습니다!

스타일 수정

/* src/components/Button/Button.styles.css */
.button-as-link {
  text-decoration: none !important;
}

4. 작업 완료

사용자: fenito (작업 완료 트리거!)

자동 완료 프로세스:

단계 1: 성공 기준 체크

✓ 모든 버튼 팩토리가 URL 파라미터 지원
✓ 자동 외부 링크 감지 구현
✓ 타입 안전성 확보
✓ 일관된 API 제공
✓ 스타일 이슈 해결

단계 2: 코드 리뷰 에이전트 실행

Claude: 코드 리뷰를 실행합니다...

경고 1: 5개 버튼 팩토리에 코드 중복 발견
경고 2: 도메인 인식 외부 링크 감지 고려해볼 것

사용자: it loop (대화형 리뷰 모드!)

Claude: 경고 1을 처리할까요?
사용자: 아니, 스킵

Claude: 경고 2를 처리할까요?
사용자: 그것도 스킵. 나중에 할게.

it loop란?

• 리스트를 하나씩 순회하며 처리
• 스크롤 없이 깔끔한 UX
• 각 항목에 대해 즉시 결정

단계 3: Git 작업

1. 변경사항 스테이징
2. 커밋 생성 (상세 메시지 자동 생성)
3. task/fix-button-link-interface → main 병합
4. 태스크 브랜치 정리

자동 생성된 커밋 메시지:

feat(io-web): standardize button factory URL handling

- Added url and openInNewTab parameters to ButtonFactoryOptions
- Implemented automatic external link detection
- Updated all five button factories with consistent URL handling
- Added text-decoration: none to button links
- Created isExternalUrl utility function

Closes: fix-button-link-interface

단계 4: 작업 완료 문서화

## Completion Notes
완료 날짜: 2025-10-31
처리 시간: 15분
커밋: 3개
파일 변경: 4개

변경사항:
- ButtonFactoryOptions 인터페이스 확장
- 모든 버튼 팩토리 업데이트
- URL 유틸리티 함수 추가
- 스타일 이슈 수정

후속 작업:
- [ ] 버튼 팩토리 코드 중복 리팩토링 검토
- [ ] 도메인 화이트리스트 기반 외부 링크 감지 고려

상태 표시줄 최종:

[상태 표시줄] IMPLEMENT | main | no-task

완벽하게 정리되고 병합된 상태로 돌아왔습니다!

---

고급 기능 및 커스터마이징

1. OP급 자동 컨텍스트 압축

긴 작업을 하다 보면 컨텍스트가 가득 찹니다.

자동 경고 시스템:

[금요일 오후 4시 - 결제 시스템 구현 중]

██████░░░░ 75.0% (120k/160k) | Task: m-payment-integration
⚠️  컨텍스트 75% - 곧 마무리 고려하세요

[계속 작업...]

████████░░ 90.2% (144k/160k) | Task: m-payment-integration  
🚨 컨텍스트 90% - 지금 압축하세요!

사용자: 가야 돼, 압축하고 나중에 다시 하자

압축 프로세스:

Claude: 좋아요, context-compaction.md 프로토콜을 실행합니다.
       먼저 로깅 에이전트를 호출해서 세션 태스크 로그를 작성할게요...

[로깅 에이전트가 전체 대화 히스토리 분석]
[중요 내용을 태스크 파일에 구조화되게 기록]
[다음 단계를 명확히 문서화]

압축 완료! 태스크 파일에 모든 진행사항 저장됨.
/clear 입력하면 컨텍스트가 깔끔해집니다.

사용자: /clear
[노트북 닫음, 주말 보냄]

월요일 아침 재개:

[월요일 오전 9시]

사용자: /clear
사용자: 계속하자

Claude: 다시 오신 것을 환영합니다! 
       m-payment-integration 작업을 재개합니다.

지난 세션에서 완료한 것:
✓ Stripe 체크아웃 플로우 통합
✓ 결제 이벤트용 웹훅 핸들러 추가
✓ 결제 상태 추적 생성

현재 상태: 웹훅 시그니처 테스트 중
다음 단계: 실패한 웹훅을 위한 재시도 로직 추가

재시도 로직 구현을 계속하겠습니다.
[즉시 작업 재개 - 컨텍스트 재구성 제로]

압축 전:

[대화 내역 500줄]
[코드 변경 히스토리]
[디버깅 로그]
[시행착오 과정]
[임시 실험들]
= 컨텍스트 윈도우 90% 사용

압축 후 (태스크 파일에 저장):

## Session Log - 2025-10-28

### Completed
- Stripe API 통합 (checkout.session.completed)
- 웹훅 엔드포인트: /api/webhooks/stripe
- 결제 상태: payments 테이블에 저장
- 시그니처 검증: STRIPE_WEBHOOK_SECRET 사용

### Current State
- 웹훅 시그니처 검증 작동 확인
- 로컬 테스트: Stripe CLI로 이벤트 전달 성공

### Next Steps
1. 실패한 웹훅 재시도 로직 구현
2. exponential backoff 패턴 사용
3. 최대 3회 재시도
4. 재시도 실패 시 admin 알림

### Key Files Modified
- api/webhooks/stripe.ts (웹훅 핸들러)
- lib/payments/stripe-client.ts (Stripe 클라이언트)
- db/schema/payments.sql (테이블 스키마)

= 컨텍스트 윈도우 12% 사용 (새 세션 시작)

이점:

• 🎯 제로 컨텍스트 재구성 - 정확히 어디서 멈췄는지 알고 있음
• 💰 엄청난 토큰 절약 - 아키텍처 재설명 불필요
• 🧠 지식 축적 - 모든 세션이 다음 세션에 기여
• ⏰ 시간 절약 - "우리 뭐하고 있었지?" 제로

2. Sessions API 사용하기

단일 슬래시 커맨드로 모든 것을 제어:

# 도움말 보기
/sessions help

# 상태 관리
/sessions state mode off      # 바이패스 모드 (제한 없음)
/sessions state mode no       # 토론 모드
/sessions state mode go       # 실행 모드

# 작업 관리
/sessions tasks list          # 모든 작업 보기
/sessions tasks idx io-web    # 특정 인덱스 작업 보기
/sessions tasks current       # 현재 작업 상세 정보

# 설정 관리
/sessions config show         # 현재 설정 보기
/sessions config phrases      # 트리거 문구 보기

3. 상태 표시줄 (Statusline)

Claude Code 창 하단에 두 줄로 모든 것을 보여줍니다:

기본 상태:

██████░░░░ 45.2% (72k/160k) | Task: m-payment-integration
DAIC: Discussion | ✎ 3 files | [4 open]

해석:

• ██████░░░░ - 진행 표시줄 (컨텍스트 사용량)
• 45.2% - 정확한 퍼센티지
• 72k/160k - 사용 토큰 / 총 토큰
• Task: m-payment-integration - 현재 작업
• DAIC: Discussion - 현재 모드
• ✎ 3 files - 수정된 파일 수
• [4 open] - 열린 파일 수

실행 모드로 전환 후:

██████░░░░ 47.1% (75k/160k) | Task: m-payment-integration
DAIC: Implementation | ✎ 5 files | [4 open]
         ^^^^^^^^^^^^^^

컨텍스트 경고 (빨간색):

████████░░ 78.3% (125k/160k) | Task: m-payment-integration
^^^^^^^^^^ [주황색으로 변함]

████████▓▓ 90.1% (144k/160k) | Task: m-payment-integration  
^^^^^^^^^^ [빨간색으로 변함]
DAIC: Discussion | ✎ 12 files | [4 open]

색상 규칙:

• 🟢 녹색: < 50%
• 🟠 주황색: 50-79%
• 🔴 빨간색: ≥ 80%

작업 없을 때:

██░░░░░░░░ 12.1% (19k/160k) | Task: None
DAIC: Discussion | ✎ 0 files | [4 open]

왜 중요한가?

• 한눈에 모든 상황 파악
• 컨텍스트 압박 조기 경고
• 어느 모드인지 항상 명확
• 무엇을 작업 중인지 명확

4. 브랜치 강제 (Branch Enforcement)

문제 상황:

[작업: m-fix-auth, 
 브랜치: feature/fix-auth에 있어야 함]

사용자: 로그인 검증 업데이트해줘
Claude: 로그인 검증을 업데이트하겠습니다. 
       현재 구현을 확인할게요.

[Claude가 src/auth/login.ts 수정 시도]

❌ 차단됨: 브랜치 불일치!
- 작업 요구 브랜치: feature/fix-auth
- 현재 브랜치: main

다음 명령어를 실행하세요:
git checkout feature/fix-auth

Claude: git checkout feature/fix-auth
[브랜치 전환 완료]

Claude: [이제 올바른 브랜치에서 안전하게 파일 수정 가능]

후크가 차단하는 상황:

• ✋ 작업 브랜치가 아닌 곳에서 편집 시도
• ✋ main/master에 직접 커밋 시도
• ✋ 잘못된 레포지토리에서 작업 시도

이점:

• 🛡️ 실수로 main 브랜치 수정 방지
• 🎯 항상 올바른 브랜치에서 작업
• 🔒 멀티 레포 환경에서도 안전
• 📋 Git 히스토리 깔끔하게 유지

5. Ultrathink & API 모드

Sessions는 기본적으로 모든 메시지에 Claude의 심층 사고 모드를 활성화합니다.

Max Mode (기본값) - Claude.ai 구독자:

사용자: [아무 메시지]
[Claude 자동으로 최대 사고 예산 사용]
[토큰 2-3배 더 쓰지만 추론 능력 향상]
[$20-200/월 정액제 - 마음껏 사용]

API Mode (토큰 절약) - API 사용자:

# 설치 중:
"토큰 절약을 위한 API 모드 활성화? (y/n)"

# 또는 나중에 토글:
/api-mode

API 모드에서:

• Ultrathink 기본 비활성화 (토큰 50-67% 절약)
• 필요할 때만 수동으로 활성화:

[[ ultrathink ]] 이 어려운 문제 풀어줘

• 다른 모든 Sessions 기능은 그대로 토큰 절약

사실: API 사용자도 Sessions로 토큰 절약

• 컨텍스트 영속성: 작업당 -2000 토큰 (재설명 불필요)
• 자동 로딩: 세션당 -500 토큰 ("뭐하고 있었지?" 없음)
• DAIC 강제: 작업당 -1000 토큰 (실패한 시도 없음)
• 전문 에이전트: -3000 토큰 (최소 컨텍스트에서 작업)

Ultrathink를 잃지만 다른 모든 곳에서 토큰 효율성을 얻습니다.

6. 트리거 문구 추가하기

/sessions config phrases add go "do it now"

이제 "do it now"로도 실행 모드 전환 가능!

사용자: 이 버그 고쳐줄래?
Claude: [분석...]
사용자: do it now!
[상태 표시줄] DISCUSS → IMPLEMENT

7. 작업 중 새 작업 생성

작업 중 새로운 작업을 발견하는 것은 자연스러운 일입니다:

[현재 작업: fix-button-interface]

사용자: mech 다크모드 지원 추가
       현재 버튼이 다크모드에서 대비가 낮음

Claude: 새 작업 'add-dark-mode-support' 생성 완료!
       현재 작업 완료 후 진행하시겠습니까?

사용자: 응, 일단 현재 작업 마무리할게

작업이 완료되면:

사용자: fenito
[현재 작업 완료]

사용자: start↑ @add-dark-mode-support
[새 작업 시작!]

8. 시스템 커스터마이징 (Claude Code로 Sessions 수정하기)

CC Sessions는 수정을 위해 설계되었습니다. Claude Code 자체를 사용해서 Sessions를 개선하거나 워크플로우에 맞게 조정할 수 있습니다.

지식 파일 구조:

sessions/knowledge/claude-code/
├── hooks-reference.md       # 후크 작동 원리 및 수정 방법
├── subagents.md            # 에이전트 능력 및 커스터마이징
├── tool-permissions.md     # 도구 차단 설정
└── slash-commands.md       # 커맨드 시스템 레퍼런스

커스터마이징 예시:

사용자: @sessions/knowledge/claude-code/hooks-reference.md를 사용해서
       DAIC 강제를 수정해서 토론 모드에서도 Bash 명령어를 허용하도록 해줘

Claude: [hooks-reference.md 읽기]
       [.claude/hooks/ 파일 수정]
       [변경사항 테스트]
       완료! 이제 토론 모드에서도 Bash 명령어 실행 가능합니다.

수정 가능한 것들:

1. 트리거 문구 변경

// sessions/sessions-config.json
"trigger_phrases": {
  "go": ["make it so", "ship it", "do the thing"],
  "no": ["SILENCE", "wait", "hold up"],
  "create": ["mech", "new task"],
  "start": ["start↑", "begin"],
  "complete": ["fenito", "done", "finish"],
  "compact": ["squish", "compress"]
}

2. 차단 도구 조정

// sessions/sessions-config.json
"blocked_tools": ["Edit", "Write"]  
// MultiEdit를 허용하려면 리스트에서 제거

3. 에이전트 프롬프트 수정

.claude/agents/
├── context-gathering.md  # 컨텍스트 수집 방식 변경
├── code-review.md        # 리뷰 기준 조정
└── logging.md            # 로그 포맷 변경

4. 워크플로우 프로토콜 업데이트

sessions/protocols/
├── task-creation.md      # 작업 생성 프로세스
├── task-startup.md       # 작업 시작 단계
├── task-completion.md    # 작업 완료 체크리스트
└── context-compaction.md # 압축 전략

실전 커스터마이징:

사용자: 작업 완료 시 Slack 알림 추가하는 태스크 생성해줘

Claude: [태스크 생성]
       [sessions/protocols/task-completion.md 수정]
       [Slack webhook 통합 추가]
       [테스트]
       
완료! 이제 작업 완료 시 자동으로 Slack에 알림이 갑니다.

커스터마이징 팁:

• Sessions는 sessions/CLAUDE.md 자체 문서를 가지고 있음
• 지식 파일로 시스템을 깊이 이해하세요
• 별도 브랜치에서 변경사항 먼저 테스트
• 후크는 단순한 Python - 필요시 로깅 추가
• 커스터마이징을 문서화하세요

코드 구조의 특별함:

모든 파일이 **폴드(fold)**로 정리되어 있습니다:

# 1. Imports (표준 라이브러리, 서드파티, 로컬)
# 2. Globals (전역 설정)  
# 3. Execution Paths (실행 경로)
# 4. Functions (각각 폴드로 정리)

LLM이 파싱하기 매우 쉽게 설계되었습니다. 모듈이나 extra 스크립트 없이 주석 폴드만 사용합니다.

메타 작업: Sessions로 Sessions를 개선할 수 있습니다! 자기 자신을 수정하는 시스템입니다.

Claude Code 창 하단에 두 줄로 모든 것을 보여줍니다:

기본 상태:

██████░░░░ 45.2% (72k/160k) | Task: m-payment-integration
DAIC: Discussion | ✎ 3 files | [4 open]

해석:

• ██████░░░░ - 진행 표시줄 (컨텍스트 사용량)
• 45.2% - 정확한 퍼센티지
• 72k/160k - 사용 토큰 / 총 토큰
• Task: m-payment-integration - 현재 작업
• DAIC: Discussion - 현재 모드
• ✎ 3 files - 수정된 파일 수
• [4 open] - 열린 파일 수

실행 모드로 전환 후:

██████░░░░ 47.1% (75k/160k) | Task: m-payment-integration
DAIC: Implementation | ✎ 5 files | [4 open]
         ^^^^^^^^^^^^^^

컨텍스트 경고 (빨간색):

████████░░ 78.3% (125k/160k) | Task: m-payment-integration
^^^^^^^^^^ [주황색으로 변함]

████████▓▓ 90.1% (144k/160k) | Task: m-payment-integration  
^^^^^^^^^^ [빨간색으로 변함]
DAIC: Discussion | ✎ 12 files | [4 open]

색상 규칙:

• 🟢 녹색: < 50%
• 🟠 주황색: 50-79%
• 🔴 빨간색: ≥ 80%

작업 없을 때:

██░░░░░░░░ 12.1% (19k/160k) | Task: None
DAIC: Discussion | ✎ 0 files | [4 open]

왜 중요한가?

• 한눈에 모든 상황 파악
• 컨텍스트 압박 조기 경고
• 어느 모드인지 항상 명확
• 무엇을 작업 중인지 명확

---

실전 팁 & 베스트 프랙티스

작은 작업으로 나누기

❌ 나쁜 예: "전체 앱 리팩토링"
✅ 좋은 예: 
   - "Button 컴포넌트 타입 정리"
   - "Form validation 로직 분리"
   - "API 클라이언트 에러 처리 개선"

명확한 성공 기준 설정

## Success Criteria
✓ 명확하고 검증 가능한 기준
- [ ] 모든 버튼이 URL 파라미터 지원
- [ ] 테스트 커버리지 80% 이상
- [ ] 타입 에러 0개

컨텍스트 수집은 필수

작업 생성 후 항상:
"컨텍스트 수집 에이전트를 실행할까요?"
→ yes!

코드 리뷰를 건너뛰지 마세요

it loop으로 항목별 검토
급하더라도 최소한 훑어보기
나중에 찾을 버그를 미리 방지

트리거 문구는 독특하게

일상 대화에서 쓰지 않을 단어
예: yurt, fenito, mech, squish

---

마무리: 워크플로우를 정리하세요

CC Sessions는 단순한 도구가 아니라 AI와 협업하는 새로운 방식입니다.

뭘 얻게 되나요?

설치하면 바로 얻는 것들:

• ✅ 구현 전 토론을 강제하는 후크
• ✅ 세션 간 지속되는 상태
• ✅ 실제로 작동하는 태스크 관리
• ✅ 쓸모 있는 에이전트들
• ✅ Git 브랜치 강제
• ✅ 컨텍스트 죽기 전 토큰 경고
• ✅ 6개월 후에도 유지보수 가능한 코드

설치는 5분

# Python
pipx install cc-sessions
cd your-project
cc-sessions

# Node
npx cc-sessions

인스톨러가 물어볼 것들:

• 이름 (Claude가 실망시킬 대상)
• 상태 표시줄 원하는지 (당연히 YES)
• 실행 모드 트리거 ('go ahead', 'ship it', 뭐든)
• 기타 설정 (그냥 엔터 쳐도 됨)

Claude Code 재시작. 끝.

첫 태스크 만들기

Claude에게 말하기:

Create a task for:
[태스크 설명]

Claude가 할 것:
- 올바른 구조로 태스크 파일 생성
- 컨텍스트 수집 에이전트로 코드베이스의 필요한 모든 정보 수집
- 컨텍스트 매니페스트 구축 (다시는 잊어버리지 않음)
- 태스크를 현재 포커스로 설정

그 다음 let's work on [task-name] 말하고 Claude가 구현 전에 토론하는 걸 지켜보세요.

복잡한 프로세스 없음

이건 복잡하지 않습니다. 무거운 프로세스도 아닙니다. 그냥 Claude가 절벽에서 떨어지는 걸 막는 보이지 않는 가드레일입니다.

자연어로 원하는 것을 설명하세요. Claude는 여전히 코드를 작성합니다. 하지만 이제는 쓰레기를 만들어내지 않는 방식으로 작동합니다.

같은 속도로 코딩하되, 다음 3시간을 Claude가 방금 한 짓을 고치는 데 쓰지 않게 됩니다.

누가 만들었나요?

CC Sessions는 GWUDCAP과 Three AIrrows Capital이 제공하는 **공공재(public good)**입니다.

커뮤니티에 의해, 커뮤니티를 위해 만들어졌습니다. 오픈소스이며, 무료이고, 개선 가능하도록 설계되었습니다.

---

참고 자료

• 📦 CC Sessions GitHub
• 📖 공식 문서
• 💬 이슈 & 토론

---

이제 할 일: 설치하고, 태스크 만들고, 실제로 작동하는 AI 코딩을 경험하세요.

더 이상 CLAUDE.md에 절박한 규칙을 추가하지 마세요. 그냥 후크가 강제하게 두세요. 🚀