Claude Code, Codex 및 기타 코딩 에이전트 (coding agents)를 위한 실용적인 설정 키트입니다. 여기에는 아키텍처 원칙 (architectural principles), 강제 실행 훅 (enforcement hooks), 기술 (skills), 즉시 적용 가능한 규칙 (drop-in rules), 스타터 템플릿 (starter templates) 및 동적 워크플로 명령 (dynamic-workflow commands)이 포함되어 있습니다. 관련 부분을 프로젝트에 넣으면, 에이전트가 매 세션마다 패턴을 새로 발견하는 대신 검증된 작동 패턴으로부터 시작할 수 있습니다.

이것은 단순한 팁 모음이 아닙니다. 에이전트에게 어떻게 일해야 하는지를 가르치는 **시스템 (system)**입니다. 즉, 언제 하나의 에이전트를 사용할지 대 여러 개를 사용할지, 어떻게 자신의 출력을 검증할지, 긴 세션 동안 컨텍스트 (context)를 어떻게 관리할지, 그리고 악성 패키지 (malicious packages)에 의해 오염되지 않는 방법 등을 가르칩니다.

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

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.

git clone https://github.com/AnastasiyaW/claude-code-config ~/claude-code-config
# 항상 활성화되는 안전 훅 (safety hooks)을 전역 설정 (global config)에 복사합니다
python ~/claude-code-config/scripts/install_hooks.py --global
...

~/.claude/hooks/는 훅 스크립트 (hook scripts)를 저장하며, ~/.claude/settings.json은 이들이 등록되는 곳입니다. 설치 스크립트는 안전한 기본값 (safe defaults)을 기존 설정에 병합합니다.

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를 참조하십시오.

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

자기 평가 편향 (Self-evaluation bias)? 생성자(Generator)와 평가자(Evaluator) 에이전트를 분리 (Harness Design)
에이전트가 "완료"라고 주장하지만 실제로는 작동하지 않음? 지속 가능한 증거 아티팩트(Proof artifacts) 요구 (Proof Loop)
프롬프트/기술/설정을 개선해야 함? 자동화된 읽기-변경-테스트 루프 (Automated Read-Change-Test loop (Autoresearch))
복잡한 워크플로우에서 LLM이 단계를 건너뜀? 기계적인 작업을 위해 쉘 스크립트(Shell scripts)를 사용하여 한 번에 한 단계씩 수행 (Deterministic Orchestration)
잘못된 디버깅 결론? 구조화된 전제-추적-결론(Premises-Trace-Conclusions) 형식 (Structured Reasoning)
단일 에이전트가 처리하기에 작업이 너무 큼? 코디네이터(Coordinator) + 특화된 하위 에이전트 (Multi-Agent Decomposition)
긴 세션에서 컨텍스트(Context)가 저하됨? CLAUDE.md를 문서가 아닌 런타임 설정(Runtime config)으로 취급 (Codified Context)
공급망 공격 (Supply chain attack)? 7일 미만의 패키지를 차단하는 두 줄의 설정 (Supply Chain Defense)
리포지토리/MCP/웹을 통한 프롬프트 인젝션 (Prompt injection)? 실제 CVE를 반영한 6단계 방어 (Agent Security)
문서가 더 이상 존재하지 않는 파일을 참조함? SessionStart 훅이 모든 참조를 검증 (Documentation Integrity) - 작동하는 검증 스크립트 포함
멀티 에이전트 인프라 오버헤드? 지연 프로비저닝(Lazy provisioning)을 통해 두뇌와 손을 분리 (Managed Agents)
에이전트가 중요한 규칙을 무시함? 사고 이력을 포함한 절대적 금지 사항 (Red Lines)
장기 프로젝트의 이력이 유실됨? 인수인계와 병행하여 프로젝트별 압축된 타임라인 제공 (Project Chronicles)
기술(Skill)이 거대한 텍스트 덩어리임? 방향(Direction), 청사진(Blueprints), 솔루션(Solutions)으로 분할 (DBS Framework)
병렬 채팅이 GPU를 두고 경쟁하거나 상태를 덮어씀? 추가 전용(Append-only) 인수인계 + 잠금 파일(Lock-file) 조정 (Multi-Session Coordination)
한 채팅이 다른 채팅에 특정 요청을 보내야 함? 이메일 스타일의 스레딩 및 수신 확인 기능이 있는 파일 기반 메일박스 (Inter-Agent Communication)
AI 지원 코드 리뷰 결과가 다음 PR에서 다시 발견됨? 리뷰 결과 → 회귀 테스트(Regression test) → 불변량(Invariant) → 상호 참조 (Knowledge Base Enforcement)
소스 트리 내에 숨겨진 제로데이 취약점? LLM + 규칙 + SAST 파이프라인 (Vulnerability Detection Pipeline)
**사용자가

시각적 옵션(UI, 디자인, 다이어그램) 사이에서 선택해야 하나요?**HTML fragment server + 파일 기반 이벤트 큐 (Visual Context Pattern)
*출력이 계속 일반적인 기본값(Inter 폰트, SELECT 등)으로 되돌아가나요?**안티-어트랙터(Anti-attractor) 절차 + 3계층 강제 적용 (Anti-pattern as Config)
**논리에 의해 병합 충돌(Merge conflict)이 해결되어 작업의 절반을 잃었나요?**2-에이전트 격리 화해(Two-agent isolated reconciliation) + 검증된 데이터 우선순위 (Merge Conflict Resolution)
**조정 프리미티브(Coordination primitive)를 처음부터 구축했나요?**먼저 고전적인 아날로그 모델(Chubby lease, WAL, SMTP)에 매핑하여 30년 동안 축적된 실패 모드 문헌을 상속받으세요 (Coordination Primitives Mapping)
**버그 수정이 "이건 전부터 이미 망가져 있었어요"라는 식으로 우회되었나요?**5가지 유효한 유예 사유 + 필수적인 내구적 증거 아티팩트 (No-Pre-Existing Evasion)
**장기 프로젝트의 범위와 진행 상황이 30회 이상의 인수인계 과정에서 흩어졌나요?**WIP=1 불변량과 L1/L2/L3 증거 요구사항을 갖춘 3가지 아티팩트 하네스 (PROBLEMS.md + feature_list.json + init.sh) (Feature Tracking)
**6주가 지나면 기능의 근거(Feature rationale)가 git log 속으로 증발하나요?**ULTRAPACK 스타일의 task.md, 자동 할당된 F-NNN ID, 하이퍼링크된 불변량을 갖춘 3계층 지식 베이스 (Global -> Layer -> Feature narrative) (Feature-Layer Architecture)
**잔차/델타(residual/delta) 작업에서 모델이 "0을 예측"하는 것으로 붕괴하나요?**4회의 실제 실패 사례로부터 얻은 저신호 학습을 위한 트랩 및 수정 방법 (오버레이 맵, 델타 노이즈 제거, 잔차 색상 교정) (Low-Signal Residual Training)
**심층 연구 결과가 대화와 함께 증발하나요?**구조화된 조사 결과를 인커밍 폴더에 저장 -> 검토 -> 지식 베이스 파이프라인으로 연결 (Research Pipeline)
**완전히 새로운 에이전트를 구축 중인데 무엇부터 결정해야 할지 모르겠나요?**15개 섹션으로 구성된 MVP 청사진: 자율성 수준 -> 도구 위험 클래스 -> 권한 매트릭스 -> 예산 -> 평가(evals) -> 출시 체크리스트 (MVP Agent Blueprint)

더 작은 진단 명령 출력(diagnostic command output)이 필요하신가요? 선택 사항인 RTK 통합은 고정(pinned)되어 있으며, 체크섬 검증(checksum-verified)을 거치고, 실패 시 개방(fail-open) 방식으로 작동하며, 안전 후크(safety hooks)와는 별도로 테스트됩니다. docs/rtk-integration.md 및 scripts/rtk_integration.py를 참조하세요.

; 이는 결코 가공되지 않은 증거(raw evidence)를 대체할 수 없습니다.

확률적이 아닌 기계적으로 규칙을 강제하는 즉시 사용 가능한 후크(Ready-to-use hooks) (scripts/install_hooks.py를 통해 설치; 우회 키(bypass keys)가 포함된 전체 맵은 rules/safety-hooks.md에 있음):

기존 테스트에 @skip, .only(), @Ignore를 추가하는 것을 차단함 |
| backup-retention-cleanup | Stop |
오래된 백업 브랜치를 정리함 (14일 보관 정책) |
| file-cohesion-guard | PreToolUse |
권고: 영구적인 파일이 프로젝트 구조가 아닌 임시 위치(홈 루트, 데스크톱, 다운로드, /tmp)에 작성될 때 경고함 |
| human-confirmation-guard | PreToolUse |
삭제 의도가 포함된 모든 명령 실행 전 사용자의 명시적인 확인을 요구함 |
| ask-question-guard | PreToolUse |
되돌릴 수 있는 작업에 대해 지연/메뉴 방식의 AskUserQuestion ("다음은 무엇인가요?", "이 중 어떤 것인가요?")을 차단함 — 대신 결정하고 진행하도록 유도함 |
| over-engineering-advisor | PostToolUse |
수정 사항이 대규모 코드 블록이나 새로운 의존성 (dependency)을 추가할 때 보내는 권고 알림 — "이것이 최소한의 솔루션인가요?" (차단하지는 않음) |
| activity-journal-guard | PreToolUse |
공유 활동 저널 (activity journal)을 강제함 — 추적 중인 공유 리소스에 대해 저널에 기록하지 않는 변경 명령을 차단함 |
| coord-claim-guard | PreToolUse |
멀티 세션 / 조정(coord)이 활성화된 리포지토리(repo)를 위한 편집 전 권한 주장 (Claim-before-edit) 게이트 (활성화된 권한 주장 없이 파일을 편집하는 것을 차단함) |
| cyrillic-bash-guard | PreToolUse |
Windows Bash 명령에서 비 ASCII (Cyrillic/CJK) 문자를 차단함 — 인코딩 손상 방지용 |
| feature-list-validator | Stop |
feature_list.json 규율을 검증함 (WIP=1; done은 증거가 필요함) — problems-md-validator의 보조 도구 |
| handoff-resume-gate | SessionStart |
재개 신선도 게이트 (Resume freshness-gate) — 오래되었거나 확인되지 않은 핸드오프(handoff)를 차단하여 session-handoff-check를 보완함 |
| long-run-detector | SessionStart |
장기 실행 프로젝트를 자동 감지하고 [LONG-RUN] 하네스 (feature_list.json / init.sh) 채택을 권고함 |
| verify-deleted-guard | PostToolUse |
파괴적인 작업이 실제로 완료되었는지 확인함 (객체가 실제로 삭제되었는지 확인) |
| db-snapshot-guard | PreToolUse |
우회된 파괴적 SQL 실행 전 데이터베이스를 자동으로 스냅샷 (snapshot) 함 |
| claude-attribution-guard | PreToolUse |

Co-Authored-By: Claude 푸터 (footer)가 포함된 커밋/PR을 차단함 (rules/no-claude-attribution.md 참조) |
| pre-push-claude-attribution | git pre-push |
커밋이 원격 저장소(remote)에 도달하기 전의 최종 귀속(attribution) 게이트
| precompact-handoff-guard | PreCompact |
컨텍스트 압축(context compaction) 전 새로운 핸드오프(handoff)를 요구함; 핸드오프가 존재하지 않으면 AUTO-DRAFT 폴백(fallback)을 작성함
| test-gate-stop-hook | Stop |
테스트가 실패(red) 상태인 동안 세션 종료를 차단함
| problems-md-validator | Stop |
유효한 연기 사유(deferral reason)가 없는 OPEN 상태의 문제(problems)가 있을 경우 종료를 차단함
| task-inbox-show | SessionStart |
.claude/task-inbox/에서 대기 중인 작업들을 표시함
| plan-gate | UserPromptSubmit |
비차단형(Non-blocking) 권고: 실질적인 빌드/리팩토링 요청 + 프로젝트 내 플랜 아티팩트(plan artifact) 없음 -> 한 줄의 "먼저 수락 기준(acceptance criteria)을 확정하세요"라는 알림 (일 최대 1회)

스타터 템플릿 (Starter templates) - 일반적인 프로젝트 유형용: 웹 앱(web-app), ML 프로젝트, 라이브러리, 코드 리뷰, 프로젝트 연대기(project chronicle), 메모리 파일, 메모리 참조, 증명 플랜(proof plan), 버그 수정 프롬프트 ("기존" 제약 조건 방지 기능 내장), 장기 프로젝트 하네스 팩(long-run project harness pack) (5개 이상의 기능과 5개 이상의 세션을 넘나드는 모든 프로젝트를 위해 feature_list.schema.json, feature_list.template.json, init.sh.template을 바로 투입 가능)

동적 워크플로우 명령 (Dynamic workflow commands) (workflows/) - 바로 사용할 수 있는 .js 오케스트레이션 스크립트: Claude Code 동적 워크플로우(/deep-review-flow, /research-cn-ru) 및 EFFECTIVE-AGENTS.md - 비용 측정 교훈 (하나의 agent() ≈ 95-150k 토큰; 주요 경제적 레버로 활용)

크로스 하네스 설정 (Cross-harness setup) (rules/cross-harness-agents-md.md) - 심볼릭 링크(symlink) 없이 Claude Code, Gemini CLI, Codex 간에 프로젝트당 하나의 AGENTS.md를 공유: Claude는 @AGENTS.md를 통해 가져오고, Gemini는 context.fileName을 통해 읽으며, Codex는 네이티브하게 읽음. 동반 기술인 gemini-delegate는 멀티 계정 Gemini CLI 위임(할당량 사다리, 계정 전환 스크립트/gemini-switch.sh, 신뢰 경계)을 지원함.

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