refactoring

• [What This Is](#what-this-is)
• [CLAUDE.md: The Development Framework](#-claudemd-the-development-framework)
• [Claude Code Agents: Automated Enforcement](#-claude-code-agents-automated-enforcement)
• [How to Use This in Your Projects](#-how-to-use-this-in-your-projects)
• [Documentation](#-documentation)
• [Who This Is For](#-who-this-is-for)
• [Philosophy](#-philosophy)
• [Continuous Improvement](#-continuous-improvement)
• [Personal Dotfiles](#-personal-dotfiles-the-original-purpose)
• [Contributing](#-contributing)
• [Contact](#-contact)

---

This is my personal dotfiles repository. I use it to manage my shell configurations, git aliases, and development environment setup.

It became unexpectedly popular when I shared the [CLAUDE.md file](claude/.claude/CLAUDE.md) - development guidelines I wrote for AI-assisted programming. That's likely why you're here.

This repository now serves two purposes:

1. [CLAUDE.md](claude/.claude/CLAUDE.md) + [Skills](claude/.claude/skills/) + [Nine enforcement agents](claude/.claude/agents/) - Development guidelines, 11 auto-discovered skill patterns + 6 web quality skills from [addyosmani/web-quality-skills](https://github.com/addyosmani/web-quality-skills), and automated quality enforcement (what most visitors want)
2. Personal dotfiles - My shell configs, git aliases, and tool configurations (what this repo was originally for)

Most people are here for CLAUDE.md and the agents. This README focuses primarily on those, with [dotfiles coverage at the end](#-personal-dotfiles-the-original-purpose).

---

[→ Read the full CLAUDE.md file](claude/.claude/CLAUDE.md)

CLAUDE.md is a living document that defines development principles, patterns, and anti-patterns. It transforms abstract concepts into actionable decision frameworks.

Core Philosophy

• TDD is non-negotiable - Every line of production code must be test-driven
• Behavior over implementation - Tests verify what code does, not how it does it
• Immutability by default - Pure functions and immutable data structures
• Schema-first with nuance - Runtime validation at trust boundaries, types for internal logic
• Semantic refactoring - Abstract based on meaning, not structure
• Explicit documentation - Capture learnings while context is fresh

What Makes It Different

Unlike typical style guides, CLAUDE.md provides:

• Decision frameworks - Concrete questions to answer before taking action
• Priority classifications - Objective severity levels (Critical/High/Nice/Skip)
• Quality gates - Verifiable checklists before commits
• Anti-pattern catalogs - Side-by-side good/bad examples
• Git verification methods - How to audit compliance retrospectively

Key Sections

| Section | What It Provides | Detailed Patterns |

|---------|-----------------|-------------------|

| Testing Principles | Behavior-driven testing, 100% coverage strategy, factory patterns | [→ skills/testing](claude/.claude/skills/testing/SKILL.md) |

| Mutation Testing | Test effectiveness verification, mutation operators, weak test detection | [→ skills/mutation-testing](claude/.claude/skills/mutation-testing/SKILL.md) |

| Test Design Review | Dave Farley's 8 properties evaluation, Farley Score calculation, test quality assessment | [→ skills/test-design-reviewer](claude/.claude/skills/test-design-reviewer/SKILL.md) |

| Front-End Testing | DOM Testing Library patterns, accessibility-first queries, userEvent best practices (framework-agnostic) | [→ skills/front-end-testing](claude/.claude/skills/front-end-testing/SKILL.md) |

| React Testing | React Testing Library patterns for components, hooks, context, and forms | [→ skills/react-testing](claude/.claude/skills/react-testing/SKILL.md) |

| TypeScript Guidelines | Schema-first decision framework, type vs interface clarity, immutability patterns | [→ skills/typescript-strict](claude/.claude/skills/typescript-strict/SKILL.md) |

| TDD Process | RED-GREEN-REFACTOR cycle, quality gates, anti-patterns | [→ skills/tdd](claude/.claude/skills/tdd/SKILL.md) |

| Refactoring | Priority classification, semantic vs structural framework, DRY decision tree | [→ skills/refactoring](claude/.claude/skills/refactoring/SKILL.md) |

| Functional Programming | Immutability violations catalog, pure functions, composition patterns | [→ skills/functional](claude/.claude/skills/functional/SKILL.md) |

| Expectations | Learning capture guidance, documentation templates, quality criteria | [→ skills/expectations](claude/.claude/skills/expectations/SKILL.md) |

| Planning | Small increments, three-document model (PLAN/WIP/LEARNINGS), commit approval | [→ skills/planning](claude/.claude/skills/planning/SKILL.md) |

| Web Quality Audit | Comprehensive Lighthouse-based quality review across all categories | [→ web-quality-skills](https://github.com/addyosmani/web-quality-skills) |

| Performance | Loading speed, runtime efficiency, resource optimization | [→ web-quality-skills](https://github.com/addyosmani/web-quality-skills) |

| Core Web Vitals | LCP, INP, CLS specific optimizations | [→ web-quality-skills](https://github.com/addyosmani/web-quality-skills) |

| Accessibility | WCAG compliance, screen reader support, keyboard navigation | [→ web-quality-skills](https://github.com/addyosmani/web-quality-skills) |

| SEO | Search engine optimization, crawlability, structured data | [→ web-quality-skills](https://github.com/addyosmani/web-quality-skills) |

| Best Practices | Security, modern APIs, code quality patterns | [→ web-quality-skills](https://github.com/addyosmani/web-quality-skills) |

---

v3.0 Architecture: Skills are auto-discovered patterns loaded on-demand when relevant. This reduces always-loaded context from ~3000+ lines to ~100 lines.

Quick Navigation by Problem

"I'm struggling with..." → Go here:

| Problem | Skill | Key Insight |

|---------|-------|-------------|

| Tests that break when I refactor | [testing](claude/.claude/skills/testing/SKILL.md) | Test behavior through public APIs, not implementation |

| 100% coverage but bugs still slip through | [mutation-testing](claude/.claude/skills/mutation-testing/SKILL.md) | Coverage measures execution, mutation testing measures detection |

| Tests break when refactoring UI components | [front-end-testing](claude/.claude/skills/front-end-testing/SKILL.md) | Query by role (getByRole), not implementation (framework-agnostic) |

| Testing React components, hooks, or context | [react-testing](claude/.claude/skills/react-testing/SKILL.md) | renderHook for hooks, wrapper for context, test components as functions |

| Don't know when to use schemas vs types | [typescript-strict](claude/.claude/skills/typescript-strict/SKILL.md) | 5-question decision framework |

| Code that "looks the same" - should I abstract it? | [refactoring](claude/.claude/skills/refactoring/SKILL.md) | Semantic vs structural abstraction guide |

| Refactoring everything vs nothing | [refactoring](claude/.claude/skills/refactoring/SKILL.md) | Priority classification (Critical/High/Nice/Skip) |

| Understanding what "DRY" really means | [refactoring](claude/.claude/skills/refactoring/SKILL.md) | DRY = knowledge, not code structure |

| Accidental mutations breaking things | [functional](claude/.claude/skills/f