Portable engineering system for Claude Code with hooks, specialized agents, and self-improvement

A developer frustrated with repeating instructions to Claude Code built a portable engineering system that lives in ~/.claude/ and applies to every project automatically. The system addresses two core problems: the repetition loop where Claude Code would hit the same bug days later and solve it from scratch, and the cross-project disconnect where rules refined in one project didn't exist in another.

System components

The system includes several key components:

• A constitution (CLAUDE.md) – 650 lines of rules with a value hierarchy, decision boundaries, and three execution modes depending on task complexity
• Hooks that enforce rules deterministically – Not suggestions the AI might ignore, but bash scripts that physically block dangerous commands like force pushes, wrong package manager usage, or rm -rf
• Three specialized agents – An orchestrator that delegates but never codes, builders that work in isolated copies of the repo, and a read-only reviewer that can't fix things (only reports)
• A skill pipeline – From planning to building to shipping to production, mostly autonomous with one non-negotiable gate: production deploy always asks
• An immune system – Every error gets logged with the root cause AND approaches that failed. Same bug across 2+ projects becomes a permanent rule, developing antibodies
• Anti-Goodhart verification – Five questions every agent must answer before claiming "done," because "all tests pass" doesn't mean the app works

Compound engineering approach

The system is built on Compound Engineering: Plan → Work → Review → Compound. That fourth step is where the system improves itself. The developer mentions specific rules they previously had to repeat daily: "use pnpm not npm," "don't delete passing tests," and "run tests before committing."

The project is open source at https://github.com/vinicius91carvalho/.claude with a full walkthrough of all 15 pieces available at https://tail-f-thoughts.hashnode.dev/self-improving-engineering-system-claude-code.