claude-code-config

# Claude Code Configuration System A practical configuration kit for Claude Code agents. 28 architectural principles, 19 safety hooks, 23 skills, 12 templates, 15 conditional rules. 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) ```bash 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) ```bash 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) ```bash 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 | Project type | Minimum viable set | |---|---| | **Any project** | 5 safety hooks (destructive-command, secret-leak, git-destructive, git-auto-backup, session-drift-validator) + Principles 09 (Supply Chain), 10 (Agent Security), 11 (Documentation Integrity) | | **Web app** | above + `frontend-design` skill + Principles 04 (Deterministic Orchestration), 05 (Structured Reasoning) | | **ML / data pipeline** | above + `flux2-*`, `diffusion-engineering`, `vlm-segmentation` skills + Principles 03 (Autoresearch), 12 (Low-Signal Training) | | **Multi-agent / parallel sessions** | above + [mclaude](https://github.com/AnastasiyaW/mclaude) + Principles 01 (Harness), 06 (Multi-Agent), 18 (Multi-Session Coordination), 19 (Inter-Agent Communication) | | **Library / package** | above + Principles 08 (Skills Best Practices), 17 (DBS Skill Creation) | See [AGENTS.md](AGENTS.md) for the procedure an agent follows after install, and [HOW-IT-WORKS.md](HOW-IT-WORKS.md) for the mechanics of each layer. --- ## What This Gives You **28 Architectural Principles** - each one prevents a specific failure mode observed in real agent workflows: - **Self-evaluation bias?** Separate Generator and Evaluator agents ([Harness Design](principles/01-harness-design.md)) - **Agent claims "done" but it's broken?** Require durable proof artifacts ([Proof Loop](principles/02-proof-loop.md)) - **Need to improve a prompt/skill/config?** Automated Read-Change-Test loop ([Autoresearch](principles/03-autoresearch.md)) - **LLM skips steps in complex workflows?** Shell scripts for mechanical tasks, one step at a time ([Deterministic Orchestration](principles/04-deterministic-orchestration.md)) - **Wrong debugging conclusions?** Structured Premises-Trace-Conclusions format ([Structured Reasoning](principles/05-structured-reasoning.md)) - **Task too big for one agent?** Coordinator + specialized sub-agents ([Multi-Agent Decomposition](principles/06-multi-agent-decomposition.md)) - **Context degrades in long sessions?** Treat CLAUDE.md as runtime config, not docs ([Codified Context](principles/07-codified-context.md)) - **Supply chain attack?** Two config lines block packages younger than 7 days ([Supply Chain Defense](principles/09-supply-chain-defense.md)) - **Prompt injection via repo/MCP/web?** Six-layer defense with real CVEs ([Agent Security](principles/10-agent-security.md)) - **Docs reference files that no longer exist?** SessionStart hook validates every reference ([Documentation Integrity](principles/11-documentation-integrity.md)) - ships with a working validator script - **Multi-agent infrastructure overhead?** Separate brain from hands with lazy provisioning ([Managed Agents](principles/14-managed-agents.md)) - **Agent cuts corners on critical rules?** Absolute prohibitions with incident history ([Red Lines](principles/15-red-lines.md)) - **Long-running project lost its history?** Condensed timeline per project, alongside handoffs ([Project Chronicles](principles/16-project-chronicles.md)) - **Skill is a monolithic wall of text?** Split into Direction, Blueprints, Solutions ([DBS Framework](principles/17-dbs-skill-creation.md)) - **Parallel chats fight over GPUs or overwrite each other's state?** Append-only handoffs + lock-file coordination ([Multi-Session Coordination](principles/18-multi-session-coordination.md)) - **One chat needs to send a specific request to another?** File-based mailbox with email-style threading and delivery receipts ([Inter-Agent Communication](principles/19-inter-agent-communication.md)) - **AI-assisted code review findings get rediscovered next PR?** Review finding → regression test → invariant → cross-reference ([Knowledge Base Enforcement](principles/21-knowledge-base-enforcement.md)) - **Zero-day vulnerabilities buried in source tree?** LLM + rules + SAST pipeline ([Vulnerability Detection Pipeline](principles/20-vulnerability-detection-pipeline.md)) - **User needs to choose between visual options (UI, design, diagrams)?** HTML fragment server + file-based event queue ([Visual Context Pattern](principles/22-visual-context-pattern.md)) - **Output keeps reverting to generic defaults (Inter font, SELECT *, etc.)?** Anti-attractor procedure + three-layer enforcement ([Anti-pattern as Config](principles/23-anti-pattern-as-config.md)) - **Merge conflict resolved "by logic" and lost half the work?** Two-agent isolated reconciliation + verified-data priority ([Merge Conflict Resolution](principles/24-merge-conflict-resolution.md)) - **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](principles/25-coordination-primitives-mapping.md)) - **Bug fix detoured into "this was already broken before me"?** Five valid deferral reasons + mandatory durable proof artifacts ([No-Pre-Existing Evasion](principles/26-no-pre-existing-evasion.md)) - **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](principles/27-feature-tracking.md)) - **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](principles/28-feature-layer-architecture.md)) **Ready-to-use hooks** that enforce rules mechanically, not probabilistically: | Hook | Event | What It Does | |---|---|---| | [session-drift-validator](hooks/session-drift-validator.py) | `SessionStart` | Validates file references in CLAUDE.md at session start | | [destructive-command-guard](hooks/destructive-command-guard.py) | `PreToolUse` | Blocks `rm -rf`, `git push --force`, `DROP TABLE` | | [secret-leak-guard](hooks/secret-leak-guard.py) | `PreToolUse` | Prevents committing API keys, tokens, passwords | | [session-handoff-reminder](hooks/session-handoff-reminder.py) | `Stop` | Reminds to write handoff before closing long sessions | | [session-handoff-check](hooks/session-handoff-check.py) | `SessionStart` | Shows recent handoffs from previous sessions | | [stop-phrase-guard](hooks/stop-phrase-guard.py) | `Stop` | Detects behavioral-regression phrases (ownership dodging, permission-seeking, premature stopping) | | [keyword-skill-router](hooks/keyword-skill-router.py) | `UserPromptSubmit` | Detects natural-language keywords and suggests matching skills (bilingual RU/EN) | | [api-key-leak-detector](hooks/api-key-leak-detector.py) | `PostToolUse` | Scans tool output for exposed API keys, tokens, secrets | | [command-injection-guard](hooks/command-injection-guard.py) | `PreToolUse` | Blocks shell substitution with non-trivial commands | | [git-destructive-guard](hooks/git-destructive-guard.py) | `PreToolUse` | Blocks `git reset --hard`, `push --force`, `branch -D` | | [git-auto-backup](hooks/git-auto-backup.py) | `PreToolUse` | Creates backup branch before destructive git operations | | [self-harm-guard](hooks/self-harm-guard.py) | `PreToolUse` | Prevents agent from killing its own process, locking SSH | | [test-muting-guard](hooks/test-muting-guard.py) | `PreToolUse` | Blocks adding `@skip`, `.only()`, `@Ignore` to existing tests | | [backup-retention-cleanup](hooks/backup-retention-cleanup.py) | `Stop` | Cleans up old backup branches (14-day retention) | **Starter templates** for common project types: [web-app](templates/CLAUDE-web-app.md), [ML project](templates/CLAUDE-ml-project.md), [library](templates/CLAUDE-library.md), [code review](templates/REVIEW.md), [project chronicle](templates/chronicle.md), [memory files](templates/memory-project.md), [memory reference](templates/memory-reference.md), [proof plan](templates/proof-plan.md), [long-run project harness pack](templates/long-run-project/) (drop-in `feature_list.schema.json` + `feature_list.template.json` + `init.sh.template` for any project crossing 5+ features and 5+ sessions). **Your agent picks the approach that fits.** The [alternatives/](alternatives/) directory compares 2-5 approaches for each problem, with pros, cons, and "when to choose" guidance: | Problem | Approaches Compared | |---|---| | [Multi-step orchestration](alternatives/orchestration.md) | Harness Design, Proof Loop, Deterministic Orchestration, Prompt-only | | [Code review](alternatives/code-review.md) | Sequential checklist, Parallel competency, Cross-model, LLM + static | | [Iterative optimization](alternatives/optimization.md) | Autoresearch, HyperAgent, Manual, Eval-driven | | [Context in long sessions](alternatives/context-management.md) | JIT Loading, Full Context Upfront, Compaction, Fresh Sessions | | [Session transitions](alternatives/session-handoff.md) | Manual HANDOFF.md, Auto hooks, Session Journal, ContextHarness, Memory | | [Reasoning-quality regression](alternatives/reasoning-regression-debugging.md) | Config reset, Stop-phrase guard, Metric monitoring, Fresh-session A/B, Proof Loop | --- ## 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: | Artifact | Question it answers | Where | |---|---|---| | `init.sh` | Is the project healthy right now? (binary check, <3 min target) | [templates/long-run-project/init.sh.template](templates/long-run-project/init.sh.template) | | `feature_list.json` | What features exist and what state are they in? (machine-readable) | [templates/long-run-project/feature_list.schema.json](templates/long-run-project/feature_list.schema.json) + [.template.json](templates/long-run-project/feature_list.template.json) | | `PROBLEMS.md` | What is broken right now? Recovery procedures? | Already covered in [rules](rules/) — pairs with the two above | 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`](skills/operational/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](principles/27-feature-tracking.md) for the full framework. Templates and concepts adapted from [walkinglabs/learn-harness-engineering](https://github.com/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](HOW-IT-WORKS.md) - technical deep dive into how each technology actually works, with real measurements. **Structure:** - `principles/` - 28 standalone architectural principles. Read the one that matches your current problem. - `alternatives/` - side-by-side comparisons of 2-5 approaches per problem. Pick the approach that fits. - `hooks/` - ready-to-use Python scripts for session management and safety guards. - `templates/` - starter CLAUDE.md and REVIEW.md files for different project types. - `skills/` - domain-specific knowledge (AI/ML, frontend, iOS, code review, video, writing, operational tooling). Loaded on demand. - `scripts/` - diagnostic utilities (config validator, KV-cache stats, skills-lock generator, handoff GC). - `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. | Level | Focus | Principles | |---|---|---| | **L1: Foundational** | Single agent, planning, tool use | Deterministic Orchestration, Structured Reasoning, Skills Best Practices, DBS Skill Creation | | **L2: Self-Evolving** | Feedback loops, memory, optimization | Autoresearch, Codified Context, Proof Loop | | **L3: Collective** | Multi-agent coordination | Harness Design, Multi-Agent Decomposition, Managed Agents | | **Cross-cutting** | Security + Integrity | Supply Chain Defense, Agent Security, Documentation Integrity, Red Lines | | **Cross-cutting** | Session + Project Continuity | Codified Context, Project Chronicles, Research Pipeline | 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: ```ini # ~/.npmrc min-release-age=7 ``` ```toml # ~/.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:** | Mode | When to use | Storage | |---|---|---| | **Single-file** (default, simpler) | One chat at a time | `.claude/HANDOFF.md` | | **Multi-session** (opt-in) | You run multiple Claude Code chats simultaneously on the same project | `.claude/handoffs/<unique>.md` + append-only `INDEX.md` | 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](rules/session-handoff.md) for both protocols and [principle 18](principles/18-multi-session-coordination.md) 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](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](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](principles/19-inter-agent-communication.md). 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. | Category | Skill | What It Does | |---|---|---| | Development | `deep-review` | 8 parallel specialist reviewers (security, perf, arch, DB, concurrency, errors, frontend, tests) | | AI/ML | `diffusion-engineering` | UNet, DiT, Flow Matching, Flux architectures, LoRA, schedulers, memory optimization | | AI/ML | `flux2-lora-training` | LoRA training for FLUX.2 Klein 9B and Qwen Image Edit | | AI/ML | `flux2-klein-prompting` | Prompt engineering for FLUX.2 Klein | | AI/ML | `vlm-segmentation` | VLM + segmentation: SAM2/3, Florence-2, YOLO-World | | AI/ML | `forensic-prompt-compiler` | Reverse-engineer images into reproducible prompts | | Frontend | `frontend-design` | Production-grade interfaces, not template defaults | | Architecture | `harness-design` | Multi-agent patterns: Generator-Evaluator, Sprint Contracts | | Architecture | `layer-new` | Scaffold a project layer (security, data, ui, etc.) under `docs/layers/` per Principle 28. Idempotent, falls back to GitHub fetch if template missing. | | Architecture | `feature-new` | Scaffold an ULTRAPACK-style feature narrative inside a layer with auto-allocated F-NNN ID, layer README updates, feature_list.json sync. | | iOS | `ios-development` | Swift, SwiftUI, UIKit, MVVM/TCA, Metal/GPU | | Video | `product-meaning-extractor` | Deep product analysis: JTBD, StoryBrand, positioning, customer voice bank | | Video | `video-narrative-arc` | 5 narrative templates (10s-90s) with beat-by-beat timing and emotional arcs | | Video | `script-evaluator` | Score scripts on 6 dimensions, detect flatness patterns | | Video | `remotion-production-guide` | Complete Remotion reference: animations, springs, typography, 3D, export | | Video | `video-post-production` | FFmpeg patterns for audio, captions, color, platform export | | Development | `proof-verify` | Plan-based verification: freeze ACs, build, verify with independent agent, KB conformance | | Architecture | `plan-swarm-review` | Multi-agent plan review with parallel independent reviewers | | Writing | `humanize-english` | Transform AI text into natural English prose | | Writing | `humanize-russian` | Transform AI text into natural Russian prose | | Writing | `article-structure-review` | Audit article structure: hook strength, narrative arc, conclusion clarity | | Operational | `desktop-sessions-discovery` | Find/restore Claude desktop app sessions hidden after account switch (issue #48511) — 4 scripts (inventory/find/restore/HTML registry) for Mac/Win/Linux | | Operational | `harness-audit` | Score a project's agent harness across 5 subsystems (Instructions / State / Verification / Scope / Lifecycle), identify the bottleneck, produce a prioritized 3-step improvement plan with effort estimates. Read-only query skill — no changes applied without explicit user approval. | --- ## Complementary Tools These work well alongside the principles: - **[gstack](https://github.com/nichochar/gstack)** - dev workflow skills: /review, /qa, /ship, /investigate, /design-review - **[hookify](https://github.com/AstroMined/hookify)** - git hooks generator for Claude Code - **[Semgrep](https://semgrep.dev/)** - static analysis, pairs with deep-review - **[task-orchestrator](https://github.com/jpicklyk/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](UPDATES.md) for the full changelog. --- ## 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 智能体的实战配置系统。包含 28 个架构原则、16 对比方案、23 个技能、19 个即用型 Hook 脚本和 12 个项目模板。 **核心功能:** - `principles/` - 28 个独立架构原则，每个解决一个具体失败模式 - `alternatives/` - 每个问题 2-5 种方案对比，附决策表 - `hooks/` - 19 个即用型 Hook 脚本（安全防护、会话管理、技能路由） - `templates/` - 适用于不同项目类型的 CLAUDE.md 起始模板 + 验证计划、记忆、项目编年史和长期项目脚手架（feature_list.json + init.sh） - `skills/` - 领域技能（AI/ML、视频制作、前端、iOS、写作、代码审查、验证、运维工具，包括新的 `harness-audit` 五子系统评估） **安装:** `claude plugin install https://github.com/AnastasiyaW/claude-code-config` 或直接复制所需文件。 **灵感来源:** 部分设计理念受到中国工程社区的启发，包括红线(红线)模式、规范驱动开发(OpenSpec)、经验库模式。 --- ## Описание на русском Система конфигурации для Claude Code агентов. 28 архитектурных принципов, 16 сравнений подходов, 23 навыка, 19 hook-скриптов и 12 шаблонов. **Что внутри:** - `principles/` - 28 принципов, каждый предотвращает конкретный тип отказа - `alternatives/` - сравнение 2-5 подходов для каждой проблемы с таблицей решений - `hooks/` - 19 готовых скриптов (safety guards, handoff, drift validator, keyword router, secret leak detection, backup retention и др.) - `templates/` - стартовые CLAUDE.md + план верификации + шаблоны memory и хроник + **long-run harness pack** (drop-in `feature_list.json` + `init.sh` для проектов с 5+ фичами) - `skills/` - доменные навыки (AI/ML, видео, фронтенд, iOS, письмо, код-ревью, верификация, операционные инструменты для самого Claude, включая новый `harness-audit` — 5-подсистемная оценка любого проекта) **Установка:** `claude plugin install https://github.com/AnastasiyaW/claude-code-config` или копирование нужных файлов. --- ## License MIT