rpt-claudeArchitecture

SUMMARY

요약 및 핵심 가치

1. INTRO

• Situation : [현재 안정적인 상황 또는 배경]
• Complication : [문제가 발생하거나 변화가 필요한 지점]
• Question : [이 파일이 해결해야 할 핵심 질문]
• Answer : [이 파일이 제시하는 최종 결론 및 실행 방향]

2. Key Q&A (이 파일이 답변할 수 있는 것들)

• Q: [사용자가 이 노트를 다시 찾을 때 던질 법한 질문 1]
  • A: [요약된 답변]
• Q: [질문 2]
  • A: [요약된 답변]

INTRO

• SITUATION
• COMPLICATION
• QUESTION
• ANSWER

Claude 이해하기

Claude 아키텍처

- 무대 총괄: Harness = Claude Code 프로그램 본체. 입력 받아 → 모델(Claude)에 보내고 → 모델이 뱉은 tool 호출을 실제 실행 → hook 돌림. 
- 주연 배우: Claude
- 관객: User

1. Claude가 자기 턴에 직접 호출   → "tool"  (Read·Edit·Bash·Agent·Workflow + MCP 도구)
	├ 🛠️ Read · Edit · Bash · Write      내가 직접 하는 손
	├ 🛠️ Agent(subagent type)            → subagent 생성 = Claude 1명 새로 불러 시키기
	├ 🛠️ Workflow                        서브 여러 명을 '코드'로 지휘
	├ 🛠️ Skills                          skill(= 패키지된 지시·워크플로.) 발동
	└ 🛠️ MCP = tool의 출처(외부 서버)        (MCP 도구도 결국 그냥 tool)
2. 사용자가 명시 트리거           → "command" (/foo) → 보통 skill과 1:1 매칭
3. 이벤트가 트리거               → "hook"    Claude·사용자 호출 X. skill을 실행 가능. 
	├ Trigger: SessionStart·UserPromptSubmit·PreToolUse·PostToolUse·Stop…
	└ 예: caveman 모드 = hook (프롬프트마다 자동 주입)

호출주체

• 💁‍♂️ Command
• 🤖 Tool
  • DEF 메인 Claude가 호출하는 기능 한 개. 도구 목록에 박힌 실물. 이름+입력 있고, 호출하면 앱이 실행해 결과 반환.
  • LIST
    • Read, Edit, Bash
    • Agent( ) DEF 또 다른 Claude 즉, 서브에이전트(subagent)를 부르는 도구(Workflow에서도 사용)
      • 자기만의 깨끗한 문맥 → 일 끝내고 결과 한 덩이만 메인에 보고. “수십 에이전트”의 그 에이전트.
      • subagent_type
        • DEF Agent 도구 입력값. 서브 종류 고르기. 종류마다 성격(시스템 프롬프트)+쓸 도구가 미리 정해짐.
        • LIST
          • general-purpose DEF 내장. 범용. 기본값.
          • Explore DEF 내장. 읽기전용 검색 특화. 훑기만, 수정 X
          • cavecrew-* DEF caveman 플러그인. 출력 ~60% 압축.
            • investigator: 코드 위치, 읽기전용
            • builder: 1~2파일 수술편집
            • reviewer: diff 리뷰
    • Workflow + agent()
      • DEF Workflow=내장 도구. JS 스크립트로 서브 여러 명을 fan-out하여 루프·병렬 지휘.
        • WHY 제어흐름을 모델 판단 아닌 코드로 고정 → 재현 (Rule 5 동형)
          • 단, Workflow는 무상태 엔진임.
            • 무상태 DEF 세대·적합도 같은 누적 역사 개념이 없음. 한 번 돌고 결과만 반환. 다음 실행은 백지. 실행중단 복구용 메모만 저장.
      • 부품: agent("...") 스폰 / parallel·pipeline 분배 / schema 출력 강제 / 죽어도 resume
    • MCP (Model Context Protocol)
      • DEF AI ↔ 외부 도구서버를 잇는 표준 규약. Anthropic 공개 오픈 표준.
        • WHY Claude가 깃헙·슬랙·DB·브라우저랑 대화하려면 매번 전용 연결코드 필요 → 하나의 표준 잭으로 통일. (USB-C 비유: 기기마다 다른 단자 → 표준 하나)
        • 구조 MCP 서버(도구 제공자) ↔ MCP 클라이언트(Claude Code 앱). 클라가 서버에 “도구 뭐 있냐” 묻고 → 호출 → 결과 받음.
        • 내용물 서버가 3종 노출: tools(호출 함수) / resources(읽을 데이터·파일) / prompts(프롬프트 템플릿). 대부분 tools.
      • 어디서 도나 별도 프로세스. 로컬(네 맥의 프로그램) 또는 원격(URL). 앱 설정파일에 등록.
      • 이름 읽는 법 mcp__<서버>__<도구>. 예: mcp__plugin_ouroboros_ouroboros__ouroboros_evolve_step = 서버 ouroboros + 도구 evolve_step.
      • 함정 서버 = 외부 코드 = 신뢰 경계. 권한·시크릿 조심. 인증형 MCP는 headless/cron에서 빠질 수 있음.
• 🧨 Hook DEF 이벤트 기반 도구

호출대상

• 📝 Skills DEF 작업 지시서
  • LIST
    • 커스텀 스킬
    • /code-review — 적대적 검증(패턴3)을 굳힌 제품. (내장 skill)
      • 단계: effort low~max(로컬) / ultra(클라우드 다중) / --comment(PR 코멘트) / --fix(작업트리 적용)
      • 함정: git repo 필수. ultra는 너만 트리거·과금, AI 자동 X
    • /ouroboros:evaluate·/ouroboros:ralph — plugin ouroboros가 제공하는 skill.

패키지

• 📦 플러그인 (plugin)
  • DEF Claude Code에 여러 기능을 묶어 까는 설치 패키지. (marketplace·git에서 설치)
  • 담는 것 (한 번에 여러 개): skills(슬래시·자동 워크플로), subagent types(cavecrew-*), hooks(이벤트 자동동작), MCP 서버(선택) 등
  • List
    • caveman
      • DEF 압축·서브에이전트 플러그인. cavecrew 3종 + 출력 caveman 압축 제공.
      • 부품
        • skills, subagents(cavecrew), hooks.
        • MCP 서버 없음 → cavecrew 도구가 mcp__ 아닌 이유.
    • ouroboros
      • DEF 진화 전용 플러그인
      • WHY 유상태(event-sourcing으로 계보·적합도·goal-drift 추적). 무상태 tool Workflow로 안 됨.
        • 단, 자동 fitness 없으면 무의미 → oracle부터
        • 유상태 DEF 이벤트 로그 저장 → 이벤트 스토어 ~/.ouroboros/ouroboros.db
          • db schema: events one table: 7,591행, append 전용(덮어쓰기 X, 사건 계속 추가)
            • 행 1개 = 사건 1개: {id, 무엇에 대한(aggregate), 사건종류(event_type), 내용(payload JSON), 시각}
            • 실제 event_type 예: orchestrator.progress.updated(2868), execution.tool.started(1348), mcp.job.failed…
          • 활용
            • query_events(이벤트 조회)
            • query_projection(재생해 만든 현재 뷰)
            • lineage_status
            • evolve_rewind(과거로 되감기) 존재
      • 부품
        • skill(/ouroboros:* ;/ouroboros:evolve·:ralph·:evaluate)
        • MCP tool(ouroboros_evolve_step·_auto…)
    • context-mode = MCP 서버 + skills + hooks.
  • 판별 도구 이름에 mcp__ 있으면 그 플러그인이 MCP 서버 포함. 없으면 skill·subagent로만 동작.

부가 용어

• barrier (집결선)
  • DEF 병렬 작업이 전부 끝날 때까지 기다리는 동기화 지점. “여기 다 모여”.
  • WHY 다음 단계가 모든 앞 결과를 한꺼번에 필요로 할 때 (전체 dedup·합산·“0건이면 중단”).
  • 비유 단체관광 버스 — 전원 탑승해야 출발. 한 명 늦으면 전체 대기.
  • 비용 제일 느린 놈이 전체 속도 결정(꼬리 지연) → 꼭 필요할 때만.
  • 매핑 parallel() = barrier 있음 / pipeline() = 없음(먼저 끝난 조각 바로 다음 단계).
• event-sourcing (이벤트 소싱)
  • DEF 현재 상태만 저장 대신, 일어난 모든 사건(event)을 순서대로 기록하고 상태는 재생(replay)해 도출.
  • 대조 은행 통장: 보통 DB = 최신 잔액만 덮어씀 / 이벤트소싱 = 모든 거래(+100,−30…) 기록 → 잔액은 합산.
  • WHY ouroboros가 진화는 계보·적합도 이력이 필요 → 최신상태만이면 역사 잃음. 이벤트 쌓으면 계보·drift·되감기(evolve_rewind) 가능.
  • 이득 완전한 감사추적·과거 임의시점 재구성·되돌리기.
  • 함정 저장량↑·읽을 때 재생비용. 단순 작업엔 과함.
• fan-out DEF 작업을 의존성 없는 N조각으로 쪼개 동시 스폰.
  • 이유: 벽시계 압축 (순차 100분 → 병렬 ~10분)
  • TYPE
    1. parallel() = barrier (N개 다 끝나야 다음)
    2. pipeline() = barrier 없음 (조각별 독립 흐름, 기본값)
  • 함정: 조각끼리 의존 있으면 불가. 합류 비용(통합 부채).
• worktree DEF git 기능. 한 repo를 여러 작업 디렉토리로 동시에 펼침.
  • .git 히스토리 공유 + 작업 폴더만 따로 → full clone보다 가벼움.
  • 우리 맥락: Workflow의 isolation:'worktree' 옵션 = 병렬 워커마다 격리 사본 → 동시편집 충돌(clobber) 방지. 끝나면 정리, 안 바뀌면 자동 삭제.

Claude 잘 쓰기

INTRO

• “에이전트 수 ≠ 생산성”
  • 병목: 생성(generation)이 아니라 검증(verification)
  • Regime
    • 단 에이전트 깊은 trace
      • 언제: 순차적·맥락의존·통합 무거움 (대부분 실제 기능 개발)
      • 검증: 인간
    • 다 에이전트 fan-out
      • 언제: 분해 가능 + 출력이 싸게 검증됨
      • 검증: 테스트/컴파일/점수/판정 에이전트
• AI를 잘 쓴다는 것: 퍼지한 goal을 [검증가능한 척추 + 내가 소유하는 판단층]으로 분해하고, oracle을 먼저 짓는 능력
  1. 작업이 어느 regime인지 분류하는 습관 (순차 통합 vs 병렬+검증가능).
  2. 작은 것부터: Workflow로 서브에이전트 2-3기 + verify 단계 한 번 짜보고, 단일 trace보다 실제로 나은지 측정.
  3. oracle 먼저: 테스트/메트릭/린터가 오버나잇 런을 의미있게 만드는 전부. army 전에 oracle.

BODY

Structure — 패턴 굴리는 법 (카테고리 규율)

• THEOREM “병렬화 가능 ⟺ 의존성 없음 + 검증 가능”.
  • 상위 원리: 분산 map-reduce + ML search-with-fitness/loss.

Pattern

• assetPattern-AI-BestOfN — N개 시도 → judge 채점 → 최고 채택
• assetPattern-AI-EmbarrassinglyParallel — 독립 파일 N개 병렬 수정
• assetPattern-AI-Adversarial — 회의론자 N 반박 → 과반이면 폐기
• assetPattern-AI-LoopUntilDry — 안 나올 때까지 finder 반복
• assetPattern-AI-Evolve — 생성→평가→선택→변이 (유상태)

Projects

• 메타 파이프라인:
  1. 💁‍♂️ ORACLE 하네스: 테스트/린터/메트릭
  2. 💁‍♂️ SPEC/TAXONOMY/SCOPE
  3. 🤖 Fan Out
     • INVENTORY ← fan-out. 검증: 카운트/커버리지
     • EXTRACT ← fan-out. 검증: 모든 추출은 source note 인용
     • DEDUP/MERGE ← barrier (전체 필요)
  4. 💁‍♂️ +🤖 SYNTHESIZE ← 단일 trace. 검증: 사람 + 인용 무결성