claude-code-config

Claude Code + Codex Agent Configuration System

A practical configuration kit for Claude Code, Codex, and other coding agents. It contains architectural principles, enforcement hooks, skills, drop-in rules, starter templates, and dynamic-workflow commands. Drop the relevant parts into a project so the agent starts from verified working patterns instead of rediscovering them every session.

This is not a collection of tips. It is a system that teaches your agent how to work - when to use one agent vs many, how to verify its own output, how to manage context across long sessions, how to not get poisoned by malicious packages.

Notes

Write-ups of the incidents that produced a rule or a hook here. Each states what was measured, what is inference, and what the fix does not cover.

Installation

Three paths depending on what you need:

Option 1: Claude Code plugin (fastest)

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

Then in your Claude Code chat:

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

Option 2: Global install (hooks + skills available in every project)

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

# Copy the always-on safety hooks to your global config
python ~/claude-code-config/scripts/install_hooks.py --global

# Claude Code: copy a selected skill directory, not its parent category
mkdir -p ~/.claude/skills
cp -r ~/claude-code-config/skills/ai-ml/ml-research-lab ~/.claude/skills/

# Codex desktop, its shared ~/.agents root, and Claude Code: sync public skills
# with independent backups for changed local copies. Target-only skills remain intact.
python ~/claude-code-config/scripts/sync_skills_to_codex.py --apply --also-claude --also-agents

The canonical tracked checkout's hooks/ directory stores the global hook scripts; ~/.claude/settings.json and ~/.codex/hooks.json register that exact source. The installer must not create a second active ~/.claude/hooks/ tree; it merges safe defaults into the existing manifests and keeps backups before changes.

Option 3: Project-local (hooks/skills only in this project)

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

This keeps everything under .claude/ in your repo, nothing global.

Choosing what to install

See AGENTS.md for the procedure an agent follows after install, HOW-IT-WORKS.md for the mechanics of each layer, and docs/runtime-wiring.md for the live verification contract.

Moved the config to a new machine or account and most skills stopped being offered? Nothing raises an error when that happens — see docs/skill-tree-recovery.md and run python scripts/recover_skill_trees.py --report.

What This Gives You

Architectural Principles - each one prevents a specific failure mode observed in real agent workflows:

• Self-evaluation bias? Separate Generator and Evaluator agents (Harness Design)
• Agent claims "done" but it's broken? Require durable proof artifacts (Proof Loop)
• Tests feel repetitive or a specialized gate blocks smoke? Use the universal candidate-state sequence: focused slice, risk-based review, one full matrix, then only the relevant immutable-candidate compatibility proof (testing strategy)
• Need to improve a prompt/skill/config? Automated Read-Change-Test loop (Autoresearch)
• LLM skips steps in complex workflows? Shell scripts for mechanical tasks, one step at a time (Deterministic Orchestration)
• Wrong debugging conclusions? Structured Premises-Trace-Conclusions format (Structured Reasoning)
• Task too big for one agent? Coordinator + specialized sub-agents (Multi-Agent Decomposition)
• Context degrades in long sessions? Treat CLAUDE.md as runtime config, not docs (Codified Context)
• Supply chain attack? Two config lines block packages younger than 7 days (Supply Chain Defense)
• Prompt injection via repo/MCP/web? Six-layer defense with real CVEs (Agent Security)
• Docs reference files that no longer exist? SessionStart hook validates every reference (Documentation Integrity) - ships with a working validator script
• Multi-agent infrastructure overhead? Separate brain from hands with lazy provisioning (Managed Agents)
• Agent cuts corners on critical rules? Absolute prohibitions with incident history (Red Lines)
• Long-running project lost its history? Condensed timeline per project, alongside handoffs (Project Chronicles)
• Skill is a monolithic wall of text? Split into Direction, Blueprints, Solutions (DBS Framework)
• Parallel chats fight over GPUs or overwrite each other's state? Append-only handoffs + lock-file coordination (Multi-Session Coordination)
• One chat needs to send a specific request to another? File-based mailbox with email-style threading and delivery receipts (Inter-Agent Communication)
• AI-assisted code review findings get rediscovered next PR? Review finding → regression test → invariant → cross-reference (Knowledge Base Enforcement)
• Zero-day vulnerabilities buried in source tree? LLM + rules + SAST pipeline (Vulnerability Detection Pipeline)
• User needs to choose between visual options (UI, design, diagrams)? HTML fragment server + file-based event queue (Visual Context Pattern)
• *Output keeps reverting to generic defaults (Inter font, SELECT , etc.)? Anti-attractor procedure + three-layer enforcement (Anti-pattern as Config)
• Merge conflict resolved "by logic" and lost half the work? Two-agent isolated reconciliation + verified-data priority (Merge Conflict Resolution)
• Built a coordination primitive from scratch? Map it to the classical analog first (Chubby lease, WAL, SMTP) and inherit 30 years of failure-mode literature (Coordination Primitives Mapping)
• Bug fix detoured into "this was already broken before me"? Five valid deferral reasons + mandatory durable proof artifacts (No-Pre-Existing Evasion)