Claude Code + Codex 에이전트 설정 시스템

Claude Code, Codex 및 기타 코딩 에이전트를 위한 실용적인 설정 키트입니다. 여기에는 아키텍처 원칙, 강제 적용 훅(enforcement hooks), 스킬, 드롭인 규칙, 스타터 템플릿 및 동적 워크플로우 명령이 포함되어 있습니다. 관련 부분을 프로젝트에 추가하여 에이전트가 매 세션마다 재발견하는 대신 검증된 작동 패턴에서 시작하도록 합니다.

이것은 팁 모음이 아닙니다. 이것은 여러분의 에이전트에게 어떻게 일해야 하는지를 가르치는 시스템입니다. 언제 하나의 에이전트를 사용할지 여러 개와 비교하여, 자체 출력을 어떻게 검증할지, 긴 세션에 걸쳐 컨텍스트를 어떻게 관리할지, 악성 패키지에 의해 오염되지 않도록 하는 방법을 알려줍니다.

참고 사항 (Notes)

규칙이나 훅을 생성한 사고 사례들을 여기에 작성합니다. 각 항목은 무엇이 측정되었는지, 추론(inference)은 무엇인지, 그리고 어떤 수정 사항이 다루지 못하는지를 명시합니다.

설치 (Installation)

필요한 것에 따라 세 가지 경로가 있습니다:

옵션 1: Claude Code 플러그인 (가장 빠름)

claude plugin install https://github.com/AnastasiyaW/claude-code-config

그런 다음 Claude Code 채팅에서:

Read AGENTS.md and pick the principles, hooks, and skills that match my project.

옵션 2: 전역 설치 (Global install) (모든 프로젝트에서 사용 가능한 훅 + 스킬)

git clone https://github.com/AnastasiyaW/claude-code-config ~/claude-code-config

# 항상 활성화된 안전 훅을 전역 설정에 복사합니다.
... 

표준 추적 체크아웃의 hooks/ 디렉터리는 전역 후크 스크립트를 저장합니다. ~/.claude/settings.json과 ~/.codex/hooks.json이 정확히 해당 소스를 등록합니다. 설치 프로그램은 두 번째 활성 ~/.claude/hooks/ 트리를 생성해서는 안 되며, 기존 매니페스트에 안전한 기본값을 병합하고 변경 전 백업을 유지해야 합니다.

옵션 3: 프로젝트 로컬 (이 프로젝트에서만 hooks/skills)

cd /your/project
git clone https://github.com/AnastasiyaW/claude-code-config .claude-config
python .claude-config/scripts/install_hooks.py --local
...

이렇게 하면 모든 것이 리포지토리 내의 .claude/ 아래에 유지되며, 전역적으로 적용되지 않습니다.

무엇을 설치할지 선택하기

설치 후 에이전트가 따르는 절차는 AGENTS.md를, 각 계층의 메커니즘은 HOW-IT-WORKS.md를, 실시간 검증 계약(live verification contract)은 docs/runtime-wiring.md를 참고하세요.

설정 파일을 새 기기나 계정으로 옮겼는데 대부분의 스킬이 제공되지 않는 경우? 오류가 발생하지 않습니다 — docs/skill-tree-recovery.md를 참조하고 python scripts/recover_skill_trees.py --report를 실행하세요.

이것이 제공하는 것들

아키텍처 원칙(Architectural Principles) - 각각은 실제 에이전트 워크플로우에서 관찰된 특정 실패 모드를 방지합니다:

• 자기 평가 편향(Self-evaluation bias)? Generator 에이전트와 Evaluator 에이전트를 분리합니다(Harness Design)

• 에이전트가 '완료'라고 주장하지만 작동하지 않나요? 지속 가능한 증거 아티팩트(proof artifacts)를 요구합니다(Proof Loop)

• 테스트가 반복적이거나 전문적인 게이트가 전체 과정을 막나요? 다음의 범용 후보 상태 시퀀스를 사용합니다: 집중 슬라이스, 위험 기반 검토, 완전한 매트릭스 하나, 그리고 관련 불변 후보 호환성 증명만(testing strategy)

• 프롬프트/기술(skill)/설정(config)을 개선해야 하나요? 자동 읽기-변경-테스트 루프(Autoresearch)

• LLM이 복잡한 워크플로우에서 단계를 건너뛰나요? 기계적 작업을 위한 셸 스크립트와 단계별 실행(Deterministic Orchestration)

• 잘못된 디버깅 결론을 내리나요? 구조화된 전제-추적(Premises-Trace)-결론 형식(Structured Reasoning)

• 작업이 하나의 에이전트에게 너무 큰가요? 코디네이터와 전문화된 서브 에이전트(Multi-Agent Decomposition)

• 긴 세션에서 컨텍스트가 저하되나요? CLAUDE.md를 문서(docs)가 아닌 런타임 설정(runtime config)으로 취급합니다(Codified Context)

• 공급망 공격(Supply chain attack)? 7일 미만 패키지를 차단하는 두 개의 설정 라인(Supply Chain Defense)

• repo/MCP/web을 통한 프롬프트 주입(Prompt injection)? 실제 CVE를 포함한 6계층 방어(Agent Security)

• 문서가 더 이상 존재하지 않는 파일을 참조하나요? 세션 시작 후크(SessionStart hook)가 모든 참조를 검증합니다(Documentation Integrity) - 작동하는 검증기 스크립트와 함께 제공

• 다중 에이전트 인프라 오버헤드? 느슨한 프로비저닝(lazy provisioning)을 통해 손과 분리된 두뇌를 갖춥니다(Managed Agents)

• 에이전트가 중요한 규칙을 무시하나요? 사고 기록과 함께 절대 금지 사항(Red Lines)

• 장기 프로젝트의 이력을 잃었나요? 인수인계와 함께 프로젝트별 요약 타임라인(Project Chronicles)

• 기술이 하나의 거대한 텍스트 벽인가요? 방향(Direction), 청사진(Blueprints), 솔루션으로 분할(DBS Framework)

• 병렬 채팅들이 GPU를 두고 싸우거나 서로의 상태를 덮어쓰나요? 추가 전용 인수인계 + 잠금 파일 조정(Multi-Session Coordination)

• 한 채팅이 다른 채팅에 특정 요청을 보내야 하나요? 이메일 스타일 스레딩 및 배달 영수증이 있는 파일 기반 메일함(Inter-Agent Communication)

• AI 지원 코드 검토 결과가 다음 PR에서 재발견되나요? 검토 결과 → 회귀 테스트(regression test) → 불변성(invariant) → 교차 참조(Knowledge Base Enforcement)

• 소스 트리 깊숙이 숨겨진 제로데이 취약점이 있나요? LLM + 규칙 + SAST 파이프라인(Vulnerability Detection Pipeline)

• 사용자가 시각적 옵션(UI, 디자인, 다이어그램) 중에서 선택해야 하나요? HTML 조각 서버 + 파일 기반 이벤트 큐(Visual Context Pattern)

• *출력이 일반 기본값(Inter 폰트, SELECT , 등)으로 계속 되돌아가나요? 안티-어트랙터 절차 + 3단계 강제(Anti-pattern as Config)

• 병합 충돌이 '논리적으로' 해결되어 작업의 절반을 잃었나요? 두 에이전트 격리 조정 + 검증된 데이터 우선순위(Merge Conflict Resolution)

• 조정 원시 요소(coordination primitive)를 처음부터 구축했나요? 고전적 유사체(Chubby lease, WAL, SMTP)에 매핑하고 30년간의 실패 모드 문헌(Coordination Primitives Mapping)을 상속받으세요.
• 버그 수정이 "나보다 먼저 이미 망가져 있었다"는 상황으로 변질되었나요? 다섯 가지 유효한 연기 사유와 필수적인 영구 증명 아티팩트(No-Pre-Existing Evasion)를 활용하세요.
• 장기간 프로젝트의 범위와 진행 상황이 30회 이상의 인수인계에 걸쳐 분산되었나요? WIP=1 불변성(invariant)과 L1/L2/L3 증거 요구 사항을 갖춘 세 가지 아티팩트 기반 하네스(PROBLEMS.md + feature_list.json + init.sh)를 사용하세요(Feature Tracking).
• 기능의 근거가 6주 만에 git 로그에서 사라지나요? ULTRAPACK 스타일의 task.md, 자동 할당된 F-NNN ID, 하이퍼링크화된 불변성을 갖춘 3계층 지식 기반(KB) (글로벌 -> 레이어 -> 기능 서사)을 사용하세요(Feature-Layer Architecture).
• 잔차(residual)/델타(delta) 작업에서 모델이 "0 예측"으로 붕괴되나요? 네 차례의 실제 실패로부터 얻은 저신호 학습(low-signal training)을 위한 함정과 수정 방법(오버레이 맵, 디노이즈 델타, 색상 보정 잔차)을 적용하세요(Low-Signal Residual Training).
• 심층 연구 결과가 대화와 함께 사라지나요? 구조화된 발견 사항을 수신 폴더에 저장하고 -> 검토한 후 -> 지식 기반 파이프라인(knowledge base pipeline)을 거치세요(Research Pipeline).
• 두 번째 진실 공급원 없이 사람이 탐색 가능한 메모리 뷰가 필요한가요? 개인 아카이브 위에 선택적인 Obsidian 호환 마크다운 허브를 사용하세요(Obsidian Mind adoption note).
• 반복 가능한 주장 검증 또는 로컬 UI/CLI 하네스가 필요한가요? 선택적으로 채택된 Cursor Team Kit 패턴을 사용하세요: verify-this, control-cli, control-ui, deslop 및 옵트인 엄격 품질 검토.

• 새 에이전트를 구축하는데 무엇부터 결정해야 할지 모르겠나요? 자율성 수준 -> 도구 위험 등급 -> 권한 매트릭스 -> 예산 -> 평가(evals) -> 출시 체크리스트의 15개 섹션 MVP 청사진: MVP Agent Blueprint

더 작은 진단 명령어 출력이 필요한가요? 선택적 RTK 통합은 고정되어 있고(pinned), 체크섬으로 검증되며, 실패 시 개방(fail-open)되며, 안전 후크와는 별도로 테스트되었습니다. docs/rtk-integration.md 및 scripts/rtk_integration.py를 참조하세요. 이는 원시 증거(raw evidence)를 절대 대체할 수 없습니다.

규칙을 기계적으로, 확률적으로가 아닌 방식으로 강제하는 바로 사용 가능한 후크 (설치 방법: scripts/install_hooks.py; 전체 맵 및 우회 키는 rules/safety-hooks.md 참조):

동적 워크플로우 명령어 (Dynamic workflow commands) (workflows/) - Claude Code의 동적 워크플로우를 위한 즉시 사용 가능한 .js 오케스트레이션 스크립트(deep-review-flow, research-cn-ru)와 EFFECTIVE-AGENTS.md가 준비되어 있습니다 - 측정된 비용 교훈 (하나의 agent()는 약 95k~150k 토큰; 주요 경제 레버로 재개).**

크로스-하네스 설정 (Cross-harness setup) (rules/cross-harness-agents-md.md) - Claude Code, Gemini CLI, Codex 간에 프로젝트당 하나의 AGENTS.md를 심볼릭 링크 없이 공유합니다: Claude는 @AGENTS.md를 통해 가져오고, Gemini는 context.fileName을 통해 읽으며, Codex는 네이티브로 처리합니다. 보조 스킬 gemini-delegate는 다중 계정 Gemini CLI 위임(할당량 사다리, 계정 전환기 scripts/gemini-switch.sh, 신뢰 경계)을 다룹니다.

순차적인 Claude/Codex 핸드오프를 위해서는 cross-harness-continuation 계약을 사용합니다. 이 계약은 Git 기준선, 주장된 파일, 승인된 결정, 거부된 접근 방식 및 검증 결과를 기록합니다. 가드 블록(guard blocks)은 무음 재작성(silent rewrites)과 범위 표류(scope drift)를 방지하며, 의도적인 재설계는 명시적이고 근거가 제시된 replan 모드를 사용해야 합니다.

에이전트가 적합한 접근 방식을 선택합니다. alternatives/ 디렉토리는 각 문제에 대해 2~5가지 접근 방식을 비교하며, 장점, 단점 및