pedrohcgs/claude-code-my-workflow

활발하게 유지 관리되고 있습니다. 학술 작업(슬라이드, 논문, 데이터 분석 등)에 Claude Code를 사용하는 방법에 대한 요약이며, 여러분의 연구를 위해 포크(fork)할 수 있도록 패키징되어 있습니다. 최신 변경 사항은 CHANGELOG.md를 참조하세요.

라이브 사이트: psantanna.com/claude-code-my-workflow

AI 지원 학술 작업을 위한 즉시 포크 가능한 기반입니다. 강의 슬라이드, 연구 논문, 데이터 분석, 재현 패키지 등 원하는 내용을 설명하면 Claude가 접근 방식을 계획하고, 특화된 에이전트(agents)를 실행하며, 문제를 해결하고, 품질을 검증하며, 결과를 제시합니다. 마치 전체 업무를 처리하는 계약업자와 같습니다. 실제 박사 과정(PhD course)에서 추출되어 성장하는 커뮤니티에 의해 확장되었습니다.

시작하기 전에: Claude Code와 git은 최소 요구 사항입니다. 포함된 HelloWorld 데모를 엔드 투 엔드(end-to-end)로 실행하려면 XeLaTeX (Beamer 샘플)와 Quarto (Quarto 샘플)도 필요합니다. R과 GitHub CLI 사용을 권장합니다. 일부 내부 스크립트(check-palette-sync.py, check-tikz-prevention.py)에는 Python 3가 사용되며, 이는 macOS/Linux에 사전 설치되어 있습니다. 전체 목록은 아래의 필수 요구 사항(Prerequisites)을 참조하세요. 가장 빠른 방법은 먼저 클론(clone)한 다음 ./scripts/validate-setup.sh를 실행하는 것입니다. 설치 링크와 함께 누락된 사항을 정확히 보고해 줍니다.

Python/R/markdown만 필요한 경우? XeLaTeX나 Quarto는 필요하지 않습니다. 에이전트(agents), 규칙(rules), 기술(skills) 및 오케스트레이션(orchestration) 패턴은 모든 텍스트/코드 산출물에 작동합니다. HelloWorld 데모는 건너뛰고 바로 /data-analysis, /review-paper, /lit-review 또는 /review-r로 이동하세요.

세션 2부터: MEMORY.md (커밋됨)는 모든 포커(forker)들에게 도움이 되는 일반적인 [LEARN] 항목을 수집합니다. .claude/state/personal-memory.md (.gitignore 처리됨)는 머신별 노트를 위한 것입니다. 차이점에 대해서는 .claude/rules/meta-governance.md를 참조하세요.

# GitHub에서 이 저장소를 포크(Fork)한 다음(저장소 페이지에서 "Fork" 클릭):
git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project
cd my-project
...

YOUR_USERNAME을 귀하의 GitHub 사용자 이름으로 바꾸세요.

claude

VS Code를 사용 중인가요? 대신 Claude Code 패널을 여세요. 모든 기능은 동일하게 작동합니다. 자세한 내용은 전체 가이드를 참조하세요.

프롬프트 피로 (prompt fatigue)를 방지하세요. 기본 설정 상태에서 Claude Code는 모든 도구 호출 (tool invocation) 시마다 권한을 요청합니다. 처음 몇 번의 승인 후에는 Auto-accept edits 모드를 토글하거나 (단축키 사용; 가이드의 권한 모드 섹션 참조), claude --permission-mode acceptEdits를 실행하세요.

신뢰할 수 있는 저장소 (repo)에서 완전히 자율적인 실행을 원한다면, Bypass 모드를 통해 프롬프트를 완전히 건너뛸 수 있습니다. 템플릿의 .claude/settings.json은 약 100개의 일반적인 Bash 및 Edit/Write 패턴을 미리 승인해 두었으므로, 기본 권한 설정에서도 대부분의 작업은 무인으로 진행됩니다.

그 다음, 프로젝트 세부 정보를 채워 가이드의 시작 프롬프트 (starter prompt)를 붙여넣으세요:

나는 이 저장소의 [PROJECT NAME] 작업을 시작하려고 합니다. [프로젝트에 대해 2~3문장으로 설명하세요.] 나는 Claude Code 학술 워크플로우를 설정했습니다... 구성 파일들을 읽고 내 프로젝트에 맞게 조정해 주세요. 계획 모드 (plan mode)로 진입하여 시작하세요.

전체 가이드에는 모든 세부 사항이 포함된 완전한 시작 프롬프트가 있습니다.

이 작업이 수행하는 내용: Claude가 모든 구성 파일을 읽고, 귀하의 프로젝트 이름, 소속 기관 및 선호도를 채운 다음, 계약자 모드 (contractor mode)로 진입합니다. 즉, 계획을 세우고, 구현하며, (귀하가 호출한 기술 범위 내에서) 검토 및 확인 (review + verify) 루프를 실행합니다. 귀하는 계획을 승인하고 기술을 호출하기만 하면 되며, 해당 기술이 그 범위 내에서 나머지를 처리합니다.

비학술적 프로젝트를 위해 CLAUDE.md를 대폭 수정해야 하나요? Anthropic의 내장 명령인 /init은 귀하의 코드베이스로부터 시작점으로 사용할 CLAUDE.md를 다시 도출합니다. 이 템플릿에 포함된 CLAUDE.md는 이미 학술 설정을 다루고 있으므로, 귀하의 포크 (fork)가 크게 다른 경우(예: LaTeX나 Quarto를 사용하지 않는 Python/ML 프로젝트)에만 /init이 필요합니다.

실제 강의 자료를 만들기 전에 환경이 작동하는지 확인하세요:

./scripts/validate-setup.sh # XeLaTeX, Quarto, Python, git 등을 확인합니다.

그 다음 Claude 내부에서:

/compile-latex HelloWorld # Slides/HelloWorld.tex를 PDF로 컴파일합니다.
/deploy HelloWorld # Quarto/HelloWorld.qmd를 HTML로 렌더링합니다.

두 작업 모두 성공하면 Slides/HelloWorld.tex와 Quarto/HelloWorld.qmd를 삭제하고 실제 작업을 시작합니다.

완벽한 프롬프트를 작성하는 것이 아닙니다. 목표를 명시하고, 그 목표를 향해 게이트(gates) 아래에서 작업 루프가 진행되도록 하는 것입니다. 전문 에이전트들이 노동을 수행하고; 게이트 적용이 언제 충분히 좋은지 결정하며; 사용자가 그 과정에서 발생하는 이견들을 판정합니다. 신뢰할 수 있게 만드는 세 가지 요소가 있습니다:

1. 리마인더가 아닌 실제 게이트(Real gates, not reminders). 버전 관리된 pre-commit hook (한 번만 실행: ./scripts/install-hooks.sh)은 모든 커밋마다 surface-sync + quality (≥80) 검사를 수행합니다. 이는 기술이 더 이상 우회할 수 없게 만듭니다. git-guardrails hook은 파괴적인 git 명령어 (reset --hard, clean -f, push --force, add -A)를 차단하며; 리뷰 런타임은 어떤 검토자가 도입한

). 그 기술은 내부적으로 오케스트레이터 런타임(orchestrator runtime) — 구현(implement), 검증(verify), 리뷰(review), 수정(fix), 재검증(re-verify), 점수 산정(score) — 을 실행하며, 작업이 품질 표준을 충족하면 요약본을 반환합니다. "just do it"이라고 말하면 전체 루프를 실행합니다. 커밋(commit)은 여전히 명시적인 /commit 명령이 필요하며 (이후 pre-commit hook이 이를 제어합니다).

하나의 범용 리뷰어 대신, 18개의 특화된 에이전트(agents)가 각각 하나의 차원을 점검합니다. 대표적인 예시는 다음과 같습니다:

proofreader— 문법/오타
slide-auditor— 시각적 레이아웃
pedagogy-reviewer— 교육 품질
r-reviewer— R 코드 품질
domain-reviewer— 분야별 정확성, 슬라이드 (템플릿 — 해당 분야에 맞춰 커스텀 가능)
domain-referee/methods-referee/editor— 원고 피어 리뷰(peer-review) 파이프라인 (/review-paper --peer)

각 에이전트는 범용 모델보다 자신의 좁은 작업에 더 능숙합니다. /slide-excellence 기술은 슬라이드 리뷰 에이전트들을 병렬로 실행하며, /review-paper --peer는 논문 리뷰 파이프라인을 실행합니다. 동일한 패턴은 원고, 데이터 파이프라인, 제안서와 같은 모든 학술적 결과물(academic artifact)로 확장됩니다.

두 에이전트는 서로 대립하며 작동합니다: critic은 Beamer와 Quarto를 모두 읽고 가혹한 결과물을 만들어냅니다. fixer는 critic이 찾아낸 내용을 정확히 구현합니다. 이들은 **더 이상 나올 것이 없을 때까지 루프(loop until dry)**를 돌며 — 더 이상 새로운 이슈가 발견되지 않을 때 수렴합니다 (5회 루프 제한은 기본 설정일 뿐, 주요 중단 조건은 아닙니다). 이를 통해 단일 패스(single-pass) 리뷰에서 놓치는 오류를 잡아냅니다.

모든 결과물은 점수(0–100)를 받습니다. 임계값(threshold) 미만의 점수는 워크플로우를 중단시키고 결과물을 노출합니다 — 사용자는 이를 수정할지 또는 명시적으로 무시(override)할지 결정합니다:

80— 커밋 임계값
90— PR 임계값
95— 탁월함 (지향점)

정직한 프레이밍: 임계값은 하네스(harness) 레벨에서 권고 사항입니다 — /commit 기술은 품질 검사를 실행하고 실패 시 중단됩니다. v2.0 기준으로, ./scripts/install-hooks.sh를 한 번 실행하면 실제 pre-commit hook (.githooks/pre-commit)이 설치됩니다.

)가 매 커밋(every commit)마다 surface-sync 및 품질(≥80) 게이트를 실행하므로, 기술(skill)을 우회하더라도 리뷰를 우회할 수는 없습니다. SKIP_QUALITY_GATE=1 또는 git commit --no-verify를 사용하여 커밋별로 옵트아웃(Opt out)할 수 있습니다.

계획, 사양(specifications), 세션 로그는 자동 압축(auto-compression) 및 세션 경계를 넘어 유지됩니다. PreCompact 훅(hook)은 Claude의 자동 압축이 트리거되기 전에 컨텍스트 스냅샷을 저장하여 중요한 결정이 절대 유실되지 않도록 보장합니다. MEMORY.md는 세션 전반에 걸쳐 학습 내용을 축적하므로, 한 세션에서 발견된 패턴이 향후 작업에 반영됩니다.

강제 압축(긴 파이프라인, 계획 중간 단계의 인수인계)의 경우, /compress-session (v1.9.0)은 자동 압축(auto-compaction)에 의해 내용이 잘려 나가는 대신, 대화 내용을 결정 사항, 다음 작업, 그리고 **노이즈로 간주되어 폐기된 내용(discarded-as-noise)**을 포함한 구조화된 노트로 증류(distil)합니다. /promote-memory (v1.9.0)는 .gitignore 처리된 personal-memory.md로부터 일반적인 학습 내용을 주기적으로 수집하여, 5인의 비평가 위원회(five-critic council)를 통해 커밋된 MEMORY.md로 옮깁니다.

제출 전 다음과 같은 여러 상호 보완적인 검증 레이어가 실행됩니다:

/verify-claims (v1.7.0) — 초안을 본 적이 없어 스스로 확인할 수 없는 포크된 검증기(forked verifier)를 사용하는 검증 체인(Chain-of-Verification)입니다. v1.9.0에서는 HIGH/MED/LOW-WARN 심각도 계층이 추가되었습니다. HIGH-WARN(조작된 인용, 수치적 모순)은 /verify-claims 및 /commit을 게이트 거부(gate-refuse)합니다.

/audit-reproducibility (v1.7.0; Stata 커버리지 v1.9.0) — 원고의 모든 수치적 주장은 해당 수치를 생성한 스크립트 출력값과 교차 검증됩니다. v1.9.0에서는 passport.yaml이 추가되었습니다. 이는 논문별 YAML 상태 파일로, 각 주장(claim)에 대해 PASS/FAIL/STALE/UNVERIFIED 상태를 나타냅니다.

/detect-ai-voice (v1.9.0) — 제출 전 AI 특유의 말투(상투적인 전환구, 헤징(hedging)의 중첩, 아첨(sycophancy))를 감지합니다. 설계상 읽기 전용이며, 자동 재작성(auto-rewriting)은 품질을 저하시킵니다.

/humanize (v1.9.0) — 샘플링된 성향을 가진 N명의 심사위원을 실행하고, 단일 추정치(point estimate)가 아닌 /review-paper --variance N을 통한 **결정 분포(decision distribution)**를 보고합니다. 이는 결정의 37%가 순수하게 성향 샘플링에 따라 달라진다는 AgentReview (ACL 2024)의 연구 결과에 착안하였습니다.

포괄적인 설명을 원하시면 전체 가이드(또는 소스 확인)를 읽어보세요.

다음 내용을 다룹니다:

이 워크플로우가 존재하는 이유— 문제점과 비전
시작하기— 포크(fork)하고, 프롬프트 하나를 붙여넣으면 Claude가 나머지를 설정합니다
작동 중인 시스템— 특화된 에이전트(agents), 적대적 QA (adversarial QA), 품질 점수 산정 (quality scoring)
구성 요소 (Building Blocks)— CLAUDE.md, 규칙 (rules), 기술 (skills), 에이전트 (agents), 훅 (hooks), 메모리 (memory)
워크플로우 패턴— 슬라이드, 연구, 재현성 (reproducibility), 발표 수사학 (presentation rhetoric), 순차적 적대적 감사 (sequential adversarial audits) 등
생태계— clo-author, claudeblattman, MixtapeTools, autoresearch, ClaudeCodeTools에 의한 확장 기능 및 성장하는 커뮤니티
도메인별 맞춤 설정— 자신만의 리뷰어(reviewers) 및 지식 베이스(knowledge bases) 생성

가이드는 Claude Code의 최신 기능들을 다룹니다:

모델 라인업—
Fable 5(claude-fable-5, /model fable을 통해 옵트인하거나 best 별칭 사용)는 가장 유능한 Claude Code 모델입니다: Mythos-class, GA 2026-06-09, MTok당 $10/$50, 1M 컨텍스트 (최대 출력 128k), 장기적 에이전트 작업 (long-horizon agentic work)을 위해 구축되었습니다. 사이버/바이오 관련 플래그가 지정된 콘텐츠의 경우 Opus 4.8로 폴백(fallback)되며, Claude Code ≥ 2.1.170 버전이 필요합니다.
Opus 4.8(claude-opus-4-8)은 API/계정 기본값으로 유지됩니다 (GA 2026-05-28, MTok당 $5/$25, 1M 컨텍스트, 기본값은 high 노력 수준). 또한 이 템플릿의 라우팅된 고판단(high-judgment) 티어로 유지됩니다 (이유는 model-routing.md 참조).
Sonnet 4.6은 주력 모델(1M 컨텍스트)이며, Haiku 4.5는 빠른 티어입니다. Sonnet 4와 기존 Opus 4는 2026-06-15에 은퇴하므로 Sonnet 4.6 / Opus 4.8로 마이그레이션하십시오. (2026-06-10 Anthropic 문서 기준 확인됨.)

노력 수준 (Effort levels)— /effort는 비용 대 철저함(low / medium / high / xhigh / max)을 설정합니다.

Opus 4.8의 기본값— Opus 4.8의 high는 4.7의 xhigh가 수행하던 작업을 더 적은 토큰으로 대략 수행하므로, xhigh는 확장된 탐색을 위해 남겨두고, ultracode (xhigh + 동적 워크플로우)는 가장 큰 규모의 자율 실행(autonomous runs)을 위해 사용하십시오. (v1.9.0; Anthropic 2026년 5월) — 빠른 모델이 조건이 유지됨을 확인할 때까지 턴(turns)을 거쳐 작업을 계속하십시오. /goal <verifiable condition> 및 /commit과 함께 사용됩니다.

검증된 최종 상태 실행을 위한 품질 게이트 (quality gates) (v1.9.0; Anthropic 2026년 5월) — 병렬 리뷰 작업을 위한 단일 화면 (claude agents dashboard/review-paper --peer, /slide-excellence).비용 효율적인 구성 (Cost-Conscious Composition)— 프롬프트 캐시 (prompt-cache) TTL (API 키의 경우 기본 5분; Claude 구독 시 1시간 자동 적용), 70/20/10 모델 라우팅 (Haiku/Sonnet/Opus), /cost 및 /usage 모니터링, Agent SDK 크레딧 풀 (credit-pool) 분할 (2026-06-15).스킬 프론트매터 (Skill frontmatter)— effort, context: fork, agent, hooks, disable-model-invocation (v1.8.0+), disallowed-tools (실제 도구 제한 — allowed-tools는 사전 승인만 수행), paths (glob 범위 자동 활성화), 그리고 동적 콘텐츠 ($ARGUMENTS, !command 구문).권한 모드 (Permission modes)— Normal, Auto-accept, Plan, Auto (분류기 게이트 적용; Team / Enterprise / API에서 사용 가능하며 Max로 확대 중; Opus 4.6+ 또는 Sonnet 4.6 필요), Bypass.훅 핸들러 유형 (Hook handler types)— 20개 이상의 훅 이벤트(hook events)를 포함하는 command, prompt, HTTP 핸들러; 훅은 effort.level 및 $CLAUDE_EFFORT를 참조할 수 있습니다.