Dissertation-Simulator-AgenticWorkflow: Instructions file for Claude Code

AgenticWorkflow

Claude Code 기반의 에이전트 워크플로우 자동화 프로젝트.

최종 목표

1. 워크플로우 설계: 복잡한 작업을 Research → Planning → Implementation 3단계 구조의 workflow.md로 설계
2. 워크플로우 실행: workflow.md에 정의된 에이전트·스크립트·자동화 구성을 실제로 구현

워크플로우를 만드는 것은 중간 산출물이다. 워크플로우에 기술된 내용이 실제로 동작하는 것이 최종 목표다.

존재 이유 — DNA 유전

AgenticWorkflow는 또 다른 agentic workflow system을 낳는 부모 유기체다. workflow-generator 스킬이 생산 라인이며, 자식 시스템은 부모의 전체 게놈(헌법·구조·검증·안전·기억·비판·투명)을 내장한다. 상세: soul.md §0.

절대 기준

모든 설계·구현·수정 의사결정에 적용되는 최상위 규칙. 아래 모든 원칙보다 상위.

절대 기준 1: 최종 결과물의 품질

속도, 토큰 비용, 작업량, 분량 제한은 완전히 무시한다. 유일한 기준은 최종 결과물의 품질이다.

절대 기준 2: 단일 파일 SOT + 계층적 메모리 구조

모든 공유 상태는 단일 파일(SOT)에 집중. SOT 쓰기는 Orchestrator/Team Lead만. 병렬 에이전트의 동일 파일 동시 수정 금지.

절대 기준 3: 코드 변경 프로토콜 (CCP) — MANDATORY

이 규칙은 절대 기준과 동급의 강제 사항이다. 예외 없이 반드시 준수한다. 코드를 작성·수정·추가·삭제하기 전에 반드시 3단계를 내부적으로 수행한다. 이 프로토콜을 건너뛴 코드 변경은 무효다.

[CCP-1] 의도 파악: 변경 목적·제약을 1-2문장으로 정의.

[CCP-2] 영향 범위 분석 (표준 이상 변경 시 반드시 수행):

• 직접 의존 + 호출 관계 (caller/callee)
• 구조적 관계 (상속, 합성, 참조)
• 데이터 모델/스키마/타입 연쇄
• 테스트, 설정, 문서, API 스펙
• P1 자동 지원: ccp_ripple_scanner.py가 Edit/Write 시 의존성을 자동 발견하여 제공
• ⚠ 강결합·샷건 서저리 위험 → 사전 고지 후 사용자 협의 필수

[CCP-3] 변경 설계: 코드 터치 전에 단계별 변경 계획 제안:

• Phase 1: 어떤 파일/함수부터 수정
• Phase 2: 의존성/호출자 전파
• Phase 3: 테스트/문서/설정 정합
• 결합도↓ 응집도↑ 기회 발견 시 함께 제안 (실행은 사용자 승인 후)

변경 규모	적용 깊이
경미 (오타, 주석)	CCP-1만 — "파급 없음" 확인 후 즉시 실행
표준 (함수/로직)	전체 3단계
대규모 (아키텍처, API)	전체 3단계 + 사전 사용자 승인 필수

Coding Anchor Points (CAP): CAP-1 (Think before coding), CAP-2 (Simplicity first), CAP-3 (Goal-driven execution), CAP-4 (Surgical changes). When conflicting with Absolute Standard 1, quality wins.

상세 프로토콜: AGENTS.md §2 절대 기준 3 (완전 정의) / docs/protocols/code-change-protocol.md (상세 명세)

절대 기준 간 우선순위

절대 기준 1(품질)이 최상위. 절대 기준 2(SOT)와 3(CCP)은 품질을 보장하기 위한 동위 수단.

---

프로젝트 구조

AgenticWorkflow/
├── CLAUDE.md                        ← 이 파일 (Claude Code 지시서 — 경량 TOC)
├── AGENTS.md                        ← 모든 AI 에이전트 공통 지시서 (Hub — 방법론 SOT)
├── GEMINI.md                        ← Gemini CLI 전용 (Spoke)
├── soul.md                          ← DNA 유전 정의
├── DECISION-LOG.md                  ← 설계 결정 로그 (ADR)
├── DISSERTATION-SIMULATOR-ARCHITECTURE-AND-PHILOSOPHY.md  ← 자식 시스템 아키텍처
├── DISSERTATION-SIMULATOR-USER-MANUAL.md                  ← 자식 시스템 사용자 매뉴얼
├── AGENTICWORKFLOW-USER-MANUAL.md                         ← 부모 프레임워크 사용법
├── AGENTICWORKFLOW-ARCHITECTURE-AND-PHILOSOPHY.md         ← 부모 프레임워크 설계 철학
├── docs/protocols/                  ← 상세 프로토콜 (on-demand 참조)
│   ├── autopilot-execution.md       (워크플로우 실행 체크리스트 + NEVER DO)
│   ├── quality-gates.md             (L0-L2 5계층 + L1.7 pCCS + P1 검증 24항목 상세)
│   ├── ulw-mode.md                  (ULW 강화 규칙 3개 + 런타임 메커니즘)
│   ├── context-preservation-detail.md (Hook 내부 메커니즘 + D-7 인스턴스)
│   └── code-change-protocol.md      (CCP 3단계 + CAP + 비례성 규칙)
├── .claude/
│   ├── settings.json                ← Hook 설정
│   ├── agents/                      ← Sub-agent 정의 (58개: 기반 11 + 논문 46 + 통합 1)
│   │   ├── translator.md            (영→한 번역, glossary 기반)
│   │   ├── translation-verifier.md  (번역 품질 검증, 독립 Layer 2 pACS)
│   │   ├── reviewer.md              (적대적 리뷰어, Enhanced L2)
│   │   ├── fact-checker.md          (사실 검증, claim-by-claim, Incremental Mode)
│   │   ├── code-reviewer.md         (개발 도메인 코드 리뷰어, Adversarial Dialogue)
│   │   ├── micro-verifier.md        (경량 스팟체크, haiku 모델 — RLM micro-verification)
│   │   ├── failure-predictor.md     (Predictive Debugging Phase B-1 — cross-domain 실패 예측)
│   │   ├── failure-critic.md        (Predictive Debugging Phase B-2 — 예측 교차 검증, adversarial)
│   │   ├── claim-quality-evaluator.md (pCCS Phase B-1 — claim 시맨틱 품질 평가, sonnet)
│   │   ├── claim-quality-critic.md  (pCCS Phase B-2 — claim 품질 적대적 교차 검증, sonnet)
│   │   ├── thesis-orchestrator.md   (논문 워크플로우 총괄 — Wave/Gate/HITL 관리)
│   │   └── ... (48개 논문 전문 에이전트 — 문헌 검색·분석·연구 설계·작성·출판)
│   ├── commands/                    ← Slash Commands (31개: 시스템 4 + 라우터 1 + 논문 26)
│   │   ├── start.md                 (/start — 자연어 시작 트리거 → 스마트 라우터)
│   │   ├── install.md               (/install — Setup Init 검증)
│   │   ├── maintenance.md           (/maintenance — 건강 검진)
│   │   ├── predict-failures.md      (/predict-failures — Predictive Debugging 전체 스캔)
│   │   ├── self-improve.md          (/self-improve — KBSI 자기 개선 분석)
│   │   └── thesis-*.md (26개)       (/thesis-init, /thesis-start, /thesis-status, /thesis-translate 등 — 논문 워크플로우)
│   ├── hooks/scripts/               ← Hook + 검증 스크립트 (67개 프로덕션 + 8개 모듈 + 49개 테스트)
│   │   ├── context_guard.py         (통합 디스패처)
│   │   ├── _context_lib.py          (공유 라이브러리 — 파싱·생성·검증·압축)
│   │   ├── _claim_patterns.py       (Claim ID 정규식 SOT — 모든 스크립트 공유 모듈)
│   │   ├── _core_lib.py             (Foundation — sot_paths·SOT_FILENAMES·MIN_OUTPUT_SIZE·extract_remediations·validate_sot_schema + core 상수, _context_lib에서 추출 ADR-076)
│   │   ├── _validation_lib.py       (품질게이트 P1 검증기 — pacs·traceability·review·translation·verification·domain-knowledge·workflow·L0, _core_lib 의존 ADR-076)
│   │   ├── _capture_lib.py          (세션 캡처 — transcript 파싱·SOT/git/completion-state·ULW·phase 분류, _core_lib 의존 ADR-077)
│   │   ├── _snapshot_lib.py         (스냅샷 생성·압축·decision/quality-gate 추출, _core_lib+_capture_lib 의존 ADR-078)
│   │   ├── _facts_lib.py            (세션 facts 추출·Knowledge Archive 관리, _core+_capture+_validation+_snapshot 의존 ADR-079)
│   │   ├── _diagnosis_lib.py        (Predictive Debugging — 실패 진단·risk 점수·hypothesis 우선순위·diagnosis-log 검증, _core 의존 ADR-080)
│   │   ├── save_context.py          (SessionEnd/PreCompact 저장)
│   │   ├── restore_context.py       (SessionStart 복원 + RLM + QO-1~4 품질 최적화)
│   │   ├── update_work_log.py       (PostToolUse 9개 도구 추적)
│   │   ├── generate_context_summary.py (Stop 증분 스냅샷 + 안전망)
│   │   ├── diagnose_context.py      (Abductive Diagnosis 사전 분석)
│   │   ├── validate_diagnosis.py    (AD1-AD10 사후 검증)
│   │   ├── validate_pacs.py         (PA1-PA7 + L0 검증)
│   │   ├── validate_review.py       (R1-R5 리뷰 검증)
│   │   ├── validate_traceability.py (CT1-CT5 추적성 검증)
│   │   ├── validate_domain_knowledge.py (DK1-DK7 도메인 지식)
│   │   ├── validate_translation.py  (T1-T9 번역 구조 검증)
│   │   ├── verify_translation_terms.py (T10-T12 번역 용어·숫자·인용 검증 — P1 결정론적)
│   │   ├── validate_verification.py (V1a-V1e 검증 로그 — V1d 증거 품질, V1e 복합 기준 탐지)
│   │   ├── validate_workflow.py     (W1-W9 DNA 유전 검증)
│   │   ├── validate_retry_budget.py (RB1-RB3 재시도 예산)
│   │   ├── setup_init.py            (인프라 건강 검증 + SOT 쓰기 안전)
│   │   ├── setup_maintenance.py     (주기적 건강 검진)
│   │   ├── block_destructive_commands.py (위험 명령+네트워크+시스템 차단, exit 2)
│   │   ├── block_test_file_edit.py  (TDD Guard, .tdd-guard 토글)
│   │   ├── predictive_debug_guard.py (위험 파일 경고, exit 0)
│   │   ├── ccp_ripple_scanner.py    (CCP-2 P1 의존성 자동 발견, exit 0)
│   │   ├── output_secret_filter.py  (시크릿 탐지, 3-tier 추출, 25+ 패턴, 2-패스 스캔)
│   │   ├── run_mypy_check.py        (mypy 타입 검증 훅 — Phase 1 strict, 비엄격 warn-only, exit 0)
│   │   ├── security_sensitive_file_guard.py (보안 민감 파일 경고, 12 패턴)
│   │   ├── query_workflow.py        (워크플로우 관측성 — dashboard/weakest/retry/blocked/error-trends/pccs)
│   │   ├── checklist_manager.py     (논문 SOT 관리 — init/advance/advance-group/gate/HITL/checkpoint/set-substep/register-search-cache/is-search-cached)
│   │   ├── validate_grounded_claim.py (GroundedClaim 스키마 검증 — 47개 prefix)
│   │   ├── guard_sot_write.py       (SOT 쓰기 보호 — 병렬 에이전트 충돌 방지)
│   │   ├── validate_thesis_output.py (논문 산출물 품질 검증)
│   │   ├── validate_wave_gate.py    (Wave/Gate 교차 검증)
│   │   ├── validate_step_sequence.py (스텝 순서 검증 — 의존성 적용)
│   │   ├── validate_task_completion.py (태스크 완료 검증 — CLI-only, Orchestrator 호출)
│   │   ├── validate_srcs_threshold.py (SRCS 임계값 검증)
│   │   ├── compute_srcs_scores.py   (SRCS 4축 점수 계산)
│   │   ├── fallback_controller.py   (3-tier Fallback — CLI-only, Orchestrator 호출)
│   │   ├── teammate_health_check.py (팀메이트 건강 점검 — CLI-only, Orchestrator 호출)
│   │   ├── build_bilingual_manifest.py (EN/KO 쌍 검증 — P1 결정론적)
│   │   ├── check_format_consistency.py (챕터 간 서식 일관성 검증 — P1 결정론적)
│   │   ├── detect_self_plagiarism.py (n-gram 자기표절 탐지 — P1 결정론적)
│   │   ├── extract_references.py    (인용 추출·정렬 — P1 결정론적)
│   │   ├── format_grounded_claims.py (GroundedClaim YAML 포맷팅 — P1 결정론적)
│   │   ├── generate_thesis_outline.py (마크다운 기반 목차 추출 — P1 결정론적)
│   │   ├── validate_fork_safety.py  (Fork 안전성 P1 검증 — FS-1~FS-5 결정론적, CLI 도구)
│   │   ├── validate_criteria_evidence.py (VE1-VE5 할루시네이션 교차 검증 — P1 결정론적, CLI 도구)
│   │   ├── validate_dialogue_state.py (DA1-DA5 Adversarial Dialogue 상태 검증 — P1 결정론적)
│   │   ├── validate_claim_inheritance.py (CI1-CI4 Claim 상속 검증 — P1 결정론적, Research 도메인)
│   │   ├── validate_team_synthesis.py (TS1-TS5 Agent Team 합성 완전성 검증 — P1 결정론적, CLI 도구)
│   │   ├── validate_agent_dna.py    (DA1-DA7 에이전트 DNA 구조 검증 — P1 결정론적, CLI 도구)
│   │   ├── scan_code_structure.py   (Predictive Debugging Phase A — F1-F7 코드 구조 스캔, P1 결정론적)
│   │   ├── extract_json_block.py    (Predictive Debugging Phase B→C 핸드오프 — LLM 응답에서 JSON 결정론적 추출, P1)
│   │   ├── validate_failure_predictions.py (Predictive Debugging Phase C — FP1-FP7 예측 검증, P1 결정론적)
│   │   ├── generate_failure_report.py (Predictive Debugging Phase D — 보고서+SOT 생성+H-3 파일 검증, P1 결정론적)
│   │   ├── compute_pccs_signals.py  (pCCS Phase A — P1 signal 추출, claim-map 생성)
│   │   ├── validate_pccs_assessment.py (pCCS Phase C — CA1-CA5 LLM 평가 검증, P1 결정론적)
│   │   ├── generate_pccs_report.py  (pCCS Phase D — P1 합성, 최종 pCCS 점수 계산)
│   │   ├── validate_pccs_output.py  (pCCS PC1-PC7 구조 검증, P1 결정론적)
│   │   ├── pccs_calibration.py      (pCCS 교정 delta 계산 — fact-checker/L1 기반, P1 결정론적)
│   │   ├── run_pccs_pipeline.py     (pCCS P1 Pipeline Runner — DEGRADED/FULL 모드 단일 진입점, 할루시네이션 방지)
│   │   ├── query_step.py           (Step Execution Registry — H-1~H-8 결정론적 step→agent/tier/critic/pCCS/consolidation/invocation/writing-standard 매핑, P1)
│   │   ├── self_improve_manager.py  (KBSI SOT 관리 — register/apply/reject/status/apply-to-agents-md/sync-claude-md/queue-change)
│   │   ├── validate_self_improvement.py (SI-1~SI-6 insight 검증 — P1 결정론적)
│   │   ├── validate_skill_output.py (SK-1~SK-5 스킬 산출물 구조 검증 — P1 결정론적, CLI 도구)
│   │   ├── verify_step_output.py   (VO-1~VO-8 Step 산출물 검증 — P1 결정론적, 할루시네이션 방지 + DW 품질 + 검색캐시참조)
│   │   ├── determine_dialogue_outcome.py (대화 루프 탈출 결정 — P1 결정론적, 할루시네이션 방지)
│   │   ├── run_academic_search.py (학술 검색 Pre-fetch — --auto-from-sot P1 결정론적 쿼리, sot_registration_command 출력)
│   │   ├── merge_ko_to_docx.py     (한국어 번역본 → pandoc .docx 병합 — P1 결정론적, exit 0)
│   │   └── _test_*.py (49개)        (유닛 테스트 — 각 프로덕션 스크립트 대응)
│   ├── context-snapshots/           ← 런타임 (gitignored)
│   └── skills/
│       ├── workflow-generator/      (워크플로우 설계·생성)
│       ├── doctoral-writing/        (박사급 학술 글쓰기)
│       ├── skill-creator/           (스킬 메타 생성기)
│       └── subagent-creator/        (에이전트 메타 생성기)
├── tests/e2e/                       ← E2E 통합 테스트 (5 Track, 108+ 테스트)
│   ├── conftest.py                  (공유 Fixture — run_cm, run_qw, read_sot)
│   ├── test_e2e_lifecycle.py        (Track 1: 전체 라이프사이클)
│   ├── test_e2e_sot_integrity.py    (Track 2: SOT 무결성)
│   ├── test_e2e_cross_component.py  (Track 3: 컴포넌트 간 통합)
│   ├── test_e2e_cli_flags.py        (Track 4: CLI 플래그 완전성)
│   └── test_e2e_error_recovery.py   (Track 5: 에러 복구)
├── translations/glossary.yaml       ← 번역 용어 사전
├── prompt/                          ← 프롬프트 자료
└── coding-resource/                 ← 이론적 기반 자료