codex-claude-code-config
무엇인가
이 저장소는 Claude Code·Codex 등 코딩 에이전트에 아키텍처 원칙, 강제 훅, 스킬, 드롭인 규칙, 스타터 템플릿, 동적 워크플로 명령을 주입하는 설정 키트다. 단일 규칙 파일이 아니라 에이전트가 "어떻게 일할지"를 규정하는 계층 구조로, 언제 단일 에이전트를 쓰고 언제 다중 에이전트로 분해할지, 자기 출력을 어떻게 검증할지, 긴 세션에서 컨텍스트를 어떻게 관리할지, 악성 패키지에 오염되지 않을지를 규율한다.
어떻게 동작하나
동작은 파일 계층으로 나뉜다. AGENTS.md가 설치 후 에이전트가 따르는 절차를 담고, hooks/ 디렉터리에 전역 훅 스크립트가 있으며 ~/.claude/settings.json과 ~/.codex/hooks.json이 그 소스를 등록한다. SessionStart 훅은 문서가 참조하는 파일이 실제로 존재하는지 검증 스크립트로 확인한다. skills/ 아래에는 카테고리별 스킬 디렉터리(예: ai-ml/ml-research-lab)가 SKILL.md 형식으로 놓인다. install_hooks.py는 안전 기본값을 기존 매니페스트에 병합하고 변경 전 백업을 남기며, sync_skills_to_codex.py는 Codex 데스크톱·공유 ~/.agents 루트·Claude Code에 스킬을 동기화한다.
무엇과 다른가
프롬프트를 직접 작성하거나 단일 CLAUDE.md에 규칙을 몰아넣는 방식과 달리, 원칙·훅·스킬·템플릿을 분리된 계층으로 두고 훅으로 기계적 강제를 건다. 공급망 방어는 설정 두 줄로 7일 미만 패키지를 차단하고, 문서 무결성은 SessionStart 훅이 검증기로 강제한다. 규칙이 문서 권고에 머물지 않고 실행 시점에 발동한다는 점이 구조적 차이다.
어떻게 쓰나
설치 경로는 세 가지다. 플러그인은 `claude plugin install https://github.com/AnastasiyaW/claude-code-config` 실행 후 채팅에서 "Read AGENTS.md and pick the principles, hooks, and skills that match my project."를 입력한다. 전역 설치는 저장소를 클론한 뒤 `python scripts/install_hooks.py --global`로 훅을 등록하고, 스킬 디렉터리를 ~/.claude/skills로 복사한 다음 `python scripts/sync_skills_to_codex.py --apply --also-claude --also-agents`로 동기화한다. 프로젝트 로컬은 프로젝트 안에 .claude-config로 클론하고 `install_hooks.py --local`과 skills 복사를 수행해 .claude/ 아래에만 둔다.
전제와 한계
전제와 한계는 명시적이다. 대상은 Claude Code와 Codex이며 훅 등록이 ~/.claude/settings.json, ~/.codex/hooks.json 경로에 의존한다. 설치기는 두 번째 활성 ~/.claude/hooks/ 트리를 만들면 안 되고 기존 매니페스트에 병합해야 한다. 설정을 새 머신·계정으로 옮긴 뒤 스킬이 더 이상 제안되지 않아도 오류가 발생하지 않으므로 recover_skill_trees.py --report로 복구해야 한다. 각 규칙이 다루지 않는 범위는 Notes에 따로 기록된다.