Claude Code Configuration System

A practical configuration kit for Claude Code agents. 29 architectural principles, 25 enforcement hooks, 28 skills, 43 drop-in rules, starter templates, and ready-made dynamic-workflow commands. Drop it into your project and your agent immediately gets battle-tested patterns - instead of figuring them out from scratch 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.

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

# Copy skills you want (or all)
mkdir -p ~/.claude/skills
cp -r ~/claude-code-config/skills/* ~/.claude/skills/

~/.claude/hooks/ stores the hook scripts; ~/.claude/settings.json is where they are registered. The install script merges safe defaults into your existing settings.

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, and HOW-IT-WORKS.md for the mechanics of each layer.

What This Gives You

29 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)
• 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)
• Long-run project's scope and progress scattered across 30+ handoffs? Three-artifact harness (PROBLEMS.md + feature_list.json + init.sh) with WIP=1 invariant and L1/L2/L3 evidence requirements (Feature Tracking)
• Feature rationale evaporates into git log after 6 weeks? Three-tier KB (Global -> Layer -> Feature narrative) with ULTRAPACK-style task.md, auto-allocated F-NNN ID, hyperlinked invariants (Feature-Layer Architecture)
• Model collapses to "predict zero" on residual/delta tasks? Traps and fixes for low-signal training (overlay maps, denoise deltas, color-correction residuals), from 4 rounds of real failure (Low-Signal Residual Training)
• Deep research results evaporate with the conversation? Save structured findings to an incoming folder -> review -> knowledge base pipeline (Research Pipeline)
• Building a brand-new agent and not sure what to decide first? 15-section MVP blueprint: autonomy level -> tool risk classes -> permission matrix -> budgets -> evals -> release checklist (MVP Agent Blueprint)

Ready-to-use hooks that enforce rules mechanically, not probabilistically (install via scripts/install_hooks.py; full map with bypass keys in rules/safety-hooks.md):

Starter templates for common project types: web-app, ML project, library, code review, project chronicle, memory files, memory reference, proof plan, bug-fix prompt (anti-"pre-existing" constraints baked in), long-run project harness pack (drop-in feature_list.schema.json + feature_list.template.json + init.sh.template for any project crossing 5+ features and 5+ sessions).

Dynamic workflow commands (workflows/) - ready-to-drop .js orchestration scripts for Claude Code dynamic workflows (/deep-review-flow, /research-cn-ru) plus EFFECTIVE-AGENTS.md - measured cost lessons (one agent() ≈ 95-150k tokens; resume as the main economy lever).

Cross-harness setup (rules/cross-harness-agents-md.md) - share one AGENTS.md per project between Claude Code, Gemini CLI, and Codex without symlinks: Claude imports it via @AGENTS.md, Gemini reads it via context.fileName, Codex natively. Companion skill gemini-delegate covers multi-account Gemini CLI delegation (quota ladders, account switcher scripts/gemini-switch.sh, trust boundaries).

Your agent picks the approach that fits. The alternatives/ directory compares 2-5 approaches for each problem, with pros, cons, and "when to choose" guidance:

Long-Run Project Harness (new in v3.17/v3.18)

If you have a project that crosses 5+ features and 5+ sessions of work, three drop-in artifacts close the gap that PROBLEMS.md + handoffs + chronicles alone leave open:

Hard rules attached to this pack:

• WIP=1: at most one feature in status: "in-progress" at any time
• L1+L2+L3 evidence: status: "done" requires evidence field referencing Syntax/Static + Runtime + System artifacts (durable files, not "tests pass" claims)
• done is one-way: regression becomes a new feature, never roll back

To audit whether your project needs this pack — and which subsystem to fix first — invoke the new harness-audit skill:

/harness-audit

or trigger phrases like "audit my harness", "score my CLAUDE.md", "is my project ready for long-run". The skill produces a 5-subsystem scorecard (1-5 per dimension), identifies the bottleneck, and outputs a prioritized 3-step improvement plan with effort estimates and pointers to the templates above. Read-only — no changes applied unless you approve.

See principle 27 - Feature Tracking for the full framework. Templates and concepts adapted from walkinglabs/learn-harness-engineering (MIT license), integrated with our existing Proof Loop, Multi-Agent Decomposition, and No-Pre-Existing Evasion principles.

How This Works

For the agent (you): When this repo is connected to your project, you get access to all principles and skills automatically. Use them as decision frameworks - when facing a choice (one agent vs many? how to verify? how to manage context?), check the relevant principle or alternative comparison.

New: HOW-IT-WORKS.md - technical deep dive into how each technology actually works, with real measurements.

Structure:

• principles/ - 29 standalone architectural principles. Read the one that matches your current problem.
• rules/ - 43 drop-in .claude/rules/ files: always-on working discipline (no-guessing, finish-the-task, deletion-confirm), agent-design operational rules (tool risk taxonomy, budgets, evals, observability), and safety-hook companion docs.
• alternatives/ - side-by-side comparisons of 2-5 approaches per problem. Pick the approach that fits.
• hooks/ - 25 ready-to-use Python hook scripts for safety guards, session management, and discipline enforcement. Wire them with scripts/install_hooks.py.
• workflows/ - drop-in dynamic-workflow commands (/deep-review-flow, /research-cn-ru) + measured cost lessons.
• templates/ - starter CLAUDE.md and REVIEW.md files for different project types, plus the kb-skeleton and long-run-project scaffolding packs.
• skills/ - 28 domain skills (AI/ML, frontend, iOS, code review, video, writing, operational tooling). Loaded on demand.
• scripts/ - utilities: hook installer, config validator, cross-reference checker, KV-cache stats, skills-lock generator, public-repo sync with privacy scanner, Gemini account switcher.
• skills-lock.json - reproducible lockfile with content hashes of every skill (regenerate via scripts/generate_skills_lock.py).
• CLAUDE.md - compact summary of all principles for global config.

Principles by Maturity Level

Start with L1 for any project. Add L2 when tasks repeat and optimization matters. L3 only when solo agent is not enough.

Based on three-level agentic reasoning taxonomy (arxiv 2601.12538, 2504.19678).

Security Hardening

Two principles specifically address agent security:

Supply Chain Defense - most poisoned npm/PyPI packages are caught within 1-3 days. Two config lines create a 7-day buffer:

# ~/.npmrc
min-release-age=7

# ~/.config/uv/uv.toml
exclude-newer = "7 days"

Agent Security - covers 7 real attack categories with documented CVEs: in-code prompt injection, repo metadata poisoning, package metadata, MCP tool poisoning, web content injection, memory poisoning, sandbox escape. Includes a six-layer defense architecture.

Session Handoff - Moving Between Chats

When a Claude Code session gets long, or you want to continue tomorrow on a different machine, or your current chat predates any automation you've set up - just tell the agent to prepare a handoff.

Type one of these phrases and hit Enter:

• prepare handoff
• save context for new chat
• write handoff
• handoff this session

The agent writes a handoff file with:

• What was the goal
• What got done
• What did NOT work (the most valuable part - prevents repeating dead ends)
• Current state (working / broken / blocked)
• Key decisions and why
• The single next step

Then it stops. Close the chat. Open a new one in the same directory. The new session reads the handoff automatically (if you set up the SessionStart hook) or you can paste the file as your first message.

Two storage modes - pick one:

Single-file works for ~80% of users. Switch to multi-session only if you've actually hit last-writer-wins data loss from parallel chats. See rule file for both protocols and principle 18 for the theory behind the multi-session append-only invariant.

Why a phrase and not a button: the trigger lives in .claude/rules/session-handoff.md as plain markdown. No plugin install, no settings file, no hook. Works in any Claude Code session immediately. This is essential for migrating existing sessions that were started before you configured anything.

Copy the ready-made rule file from rules/session-handoff.md into your project's .claude/rules/ (or ~/.claude/rules/ for global) and you're done.

For automation nerds: pair this with a Stop hook that blocks long-session closure until a handoff is written. See alternatives/session-handoff.md for all 5 approaches compared.

If you run parallel chats and they need to talk to each other (not just leave state), see principle 19 - Inter-Agent Communication. Mini decision tree:

Broadcast "I'm done, anyone continue"       → handoff (principle 18)
Claim exclusive resource                    → lock file (principle 18)
Ask a specific other session to do X        → mailbox/<name>/ (principle 19)
Announce a decision for all running chats   → mailbox/all/ (principle 19)
Multi-turn reply chain                      → mailbox with in_reply_to threading

Skills Catalog

Skills are practical tools for specific domains. They are secondary to the principles - think of them as reference implementations.

Complementary Tools

These work well alongside the principles:

• gstack - dev workflow skills: /review, /qa, /ship, /investigate, /design-review
• hookify - git hooks generator for Claude Code
• Semgrep - static analysis, pairs with deep-review
• task-orchestrator - MCP task orchestration with dependency ordering

This Repo Is Updated Regularly

Principles are updated with new research findings, real-world incidents, and community patterns. Security sections track actual CVEs and attack chains. See UPDATES.md for the full changelog.

Freshness is mechanical, not aspirational: scripts/sync_public_config.py + sync-manifest.json run a manifest-driven one-way sync from the author's live ~/.claude into this repo - EOL-normalized diffing, an explicit deny-list for machine-specific files, and a privacy-marker scanner that blocks anything private from reaching the public tree (--scan-repo --strict runs before every push). If you maintain your own private-config/public-fork split, the same script works for you - edit the manifest.

Contributing

1. Fork the repo
2. Add/improve a skill (skills/<category>/<name>/SKILL.md) or principle (principles/)
3. Skill descriptions = triggers for the model, not human summaries. Include ## Gotchas from real failures
4. For principles or alternatives: open an issue first

中文简介

面向 Claude Code 智能体的实战配置系统。包含 29 个架构原则、18 对比方案、28 个技能、25 个即用型 Hook 脚本、43 条 drop-in 规则和项目模板。

核心功能:

• principles/ - 29 个独立架构原则，每个解决一个具体失败模式
• rules/ - 43 条 drop-in 规则（工作纪律、Agent 设计运维规则、安全 Hook 配套文档）
• alternatives/ - 每个问题 2-5 种方案对比，附决策表
• hooks/ - 25 个即用型 Hook 脚本（安全防护、会话管理、技能路由），用 scripts/install_hooks.py 一键注册
• workflows/ - 动态工作流命令（/deep-review-flow、/research-cn-ru）+ 实测成本经验
• templates/ - 适用于不同项目类型的 CLAUDE.md 起始模板 + 验证计划、记忆、项目编年史和长期项目脚手架（feature_list.json + init.sh）
• skills/ - 领域技能（AI/ML、视频制作、前端、iOS、写作、代码审查、验证、运维工具，包括 harness-audit 五子系统评估、workflow-orchestration 和 gemini-delegate 跨 CLI 委派）
• 跨 harness 支持：每个项目一个 AGENTS.md，同时供 Claude Code、Gemini CLI、Codex 读取（无需符号链接），见 rules/cross-harness-agents-md.md

安装: claude plugin install https://github.com/AnastasiyaW/claude-code-config 或直接复制所需文件。

灵感来源: 部分设计理念受到中国工程社区的启发，包括红线(红线)模式、规范驱动开发(OpenSpec)、经验库模式。

Описание на русском

Система конфигурации для Claude Code агентов. 29 архитектурных принципов, 18 сравнений подходов, 28 навыков, 25 hook-скриптов, 43 drop-in правила и шаблоны проектов.

Что внутри:

• principles/ - 29 принципов, каждый предотвращает конкретный тип отказа
• rules/ - 43 drop-in правила: рабочая дисциплина (no-guessing, finish-the-task, deletion-confirm, autonomy-risk-tiers), операционные правила проектирования агентов (risk taxonomy, budgets, evals, observability), доки к safety-хукам
• alternatives/ - сравнение 2-5 подходов для каждой проблемы с таблицей решений
• hooks/ - 25 готовых скриптов (safety guards, handoff, drift validator, keyword router, secret leak detection, backup retention, test/problems gates и др.), регистрация одной командой scripts/install_hooks.py
• workflows/ - готовые dynamic-workflow команды (/deep-review-flow, /research-cn-ru) + замеры стоимости агентов
• templates/ - стартовые CLAUDE.md + план верификации + шаблоны memory и хроник + long-run harness pack (drop-in feature_list.json + init.sh для проектов с 5+ фичами)
• skills/ - доменные навыки (AI/ML, видео, фронтенд, iOS, письмо, код-ревью, верификация, операционные инструменты, включая harness-audit, workflow-orchestration и gemini-delegate — делегирование в Gemini CLI с мульти-аккаунтом)
• Кросс-harness: один AGENTS.md на проект читают Claude Code, Gemini CLI и Codex (без симлинков) — rules/cross-harness-agents-md.md

Установка: claude plugin install https://github.com/AnastasiyaW/claude-code-config или копирование нужных файлов.

License

MIT