Comprehensive CLAUDE.md guidelines + enforcement agents for Test-Driven Development, TypeScript strict mode, and functional programming.

👆 Watch a real coding session showing how CLAUDE.md guides AI pair programming in Claude Code.

• What This Is
• CLAUDE.md: The Development Framework
• Claude Code Agents: Automated Enforcement
• How to Use This in Your Projects
• Documentation
• Who This Is For
• Philosophy
• Continuous Improvement
• Personal Dotfiles
• Contributing
• 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 - development guidelines I wrote for AI-assisted programming. That's likely why you're here.

This repository now serves two purposes:

1. CLAUDE.md + Skills + Eight enforcement agents - Development guidelines, 9 auto-discovered skill patterns, 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.

→ Read the full CLAUDE.md file

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

• 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

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

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

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

Skills are auto-discovered by Claude when relevant:

• Writing TypeScript? → typescript-strict skill loads automatically
• Running tests? → testing skill provides factory patterns
• After GREEN tests? → refactoring skill assesses opportunities

No manual invocation needed - Claude detects when skills apply.

Problem it solves: Tests that break on every refactor, unclear what to test, low coverage despite many tests

What's inside:

• Behavior-driven testing principles with anti-patterns
• Factory function patterns for test data (no let/beforeEach)
• Achieving 100% coverage through business behavior (not implementation)
• React component testing strategies
• Validating test data with schemas

Concrete example from the docs:

// ❌ BAD - Implementation-focused test (breaks on refactor)
it("should call validateAmount", () => {
  const spy = jest.spyOn(validator, 'validateAmount');
  processPayment(payment);
  expect(spy).toHaveBeenCalled(); // Will break if we rename or restructure
});

// ✅ GOOD - Behavior-focused test (refactor-safe)
it("should reject payments with negative amounts", () => {
  const payment = getMockPayment({ amount: -100 });
  const result = processPayment(payment);
  expect(result.success).toBe(false);
  expect(result.error.message).toBe("Invalid amount");
});

Why this matters: The first test will fail if you refactor validateAmount into a different structure. The second test only cares about behavior - refactor all you want, as long as negative amounts are rejected.

Key insight: A separate payment-validator.ts file gets 100% coverage without dedicated tests - it's fully tested through payment-processor behavior tests. No 1:1 file mapping needed.

Problem it solves: Overusing schemas everywhere, or not using them when needed; confusion about type vs interface

What's inside:

• Strict mode requirements and tsconfig setup
• Type vs interface distinction (data vs behavior contracts)
• 5-question decision framework: When schemas ARE vs AREN'T required
• Schema-first development with Zod
• Schema usage in tests (import from shared locations, never redefine)
• Branded types for type safety

The 5-question framework from the docs:

Ask these in order:

1. Does data cross a trust boundary? (external → internal) → ✅ Schema required
2. Does type have validation rules? (format, constraints) → ✅ Schema required
3. Is this a shared data contract? (between systems) → ✅ Schema required
4. Used in test factories? → ✅ Schema required (for validation)
5. Pure internal type? (utility, state, behavior) → ❌ Type is fine

Concrete example from the docs:

// ❌ Schema NOT needed - pure internal type
type Point = { readonly x: number; readonly y: number };
type CartTotal = { subtotal: number; tax: number; total: number };

// ✅ Schema REQUIRED - API response (trust boundary + validation)
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "user", "guest"]),
});
const user = UserSchema.parse(apiResponse);

Key insight: Not all types need schemas. Use schemas at trust boundaries and for validation. For internal types and utilities, plain TypeScript types are sufficient.

Critical rule: Tests must import real schemas from shared locations, never redefine them. This prevents type drift between tests and production.

Problem it solves: Writing code before tests, refactoring too much/too little, not knowing when to abstract

What's inside:

• TDD process with quality gates (what to verify before each commit)
• RED-GREEN-REFACTOR cycle with complete examples
• Refactoring priority classification (Critical/High/Nice/Skip)
• Semantic vs structural abstraction (the most important refactoring rule)
• Understanding DRY - knowledge vs code duplication
• 4-question decision framework for abstraction
• Git verification methods (audit TDD compliance retrospectively)
• Commit guidelines and PR standards

The refactoring priority system from the docs:

🔴 Critical (Fix Now): Immutability violations, semantic knowledge duplication, deep nesting (>3 levels)

⚠️ High Value (Fix This Session): Unclear names, magic numbers, long functions (>30 lines)

💡 Nice to Have: Minor improvements

✅ Skip: Code that's already clean, structural similarity without semantic relationship

The semantic vs structural rule (THE BIG ONE):

// ❌ DO NOT ABSTRACT - Structural similarity, DIFFERENT semantics
const validatePaymentAmount = (amount: number): boolean => {
  return amount > 0 && amount <= 10000; // Fraud rules
};

const validateTransferAmount = (amount: number): boolean => {
  return amount > 0 && amount <= 10000; // Account type rules
};
// They'll evolve independently - abstracting couples unrelated business rules

// ✅ SAFE TO ABSTRACT - Same semantic meaning
const formatUserDisplayName = (first: string, last: string) => `${first} ${last}`.trim();
const formatCustomerDisplayName = (first: string, last: string) => `${first} ${last}`.trim();
const formatEmployeeDisplayName = (first: string, last: string) => `${first} ${last}`.trim();
// All represent "how we display person names" - same business concept

const formatPersonDisplayName = (first: string, last: string) => `${first} ${last}`.trim();

Key insight: "Duplicate code is far cheaper than the wrong abstraction." Only abstract code that shares the same semantic meaning, not just similar structure.

DRY revelation: DRY means "Don't Repeat Knowledge" not "Don't Repeat Code Structure". The shipping threshold example in the docs shows this perfectly.

Problem it solves: Accidental mutations, nested conditionals, unclear code, when to use FP abstractions

What's inside:

• Complete immutability violations catalog (arrays, objects, nested structures)
• Functional programming patterns and when to use heavy FP abstractions
• Code structure principles (max 2 levels nesting)
• Self-documenting code patterns (no comments)
• Naming conventions (functions, types, constants, files)
• Options objects pattern (vs positional parameters)

The immutability catalog from the docs:

// ❌ WRONG - Array mutations
items.push(newItem);        // → [...items, newItem]
items.pop();                // → items.slice(0, -1)
items[0] = updatedItem;     // → items.map((item, i) => i === 0 ? updatedItem : item)
items.sort();               // → [...items].sort()

// ❌ WRONG - Object mutations
user.name = "New Name";     // → { ...user, name: "New Name" }
delete user.email;          // → const { email, ...rest } = user; rest

// ❌ WRONG - Nested mutations
cart.items[0].quantity = 5; // → { ...cart, items: cart.items.map((item, i) => i === 0 ? { ...item, quantity: 5 } : item) }

Options objects pattern:

// Avoid: Unclear at call site
const payment = createPayment(100, "GBP", "card_123", "cust_456", undefined, { orderId: "789" });

// Good: Self-documenting
const payment = createPayment({
  amount: 100,
  currency: "GBP",
  cardId: "card_123",
  customerId: "cust_456",
  metadata: { orderId: "789" },
});

Key insight: Immutability eliminates entire classes of bugs. The catalog provides the immutable alternative for every common mutation pattern.

Problem it solves: Losing context after complex features, forgetting gotchas, unclear expectations

What's inside:

• Complete expectations checklist for Claude
• Learning documentation framework (7 criteria for what to document)
• Types of learnings to capture (gotchas, patterns, anti-patterns, decisions, edge cases)
• Documentation format templates
• "What do I wish I'd known at the start?" prompts

The 7 criteria for documenting learnings:

Document if ANY of these are true:

• ✅ Would save future developers >30 minutes
• ✅ Prevents a class of bugs or errors
• ✅ Reveals non-obvious behavior or constraints
• ✅ Captures architectural rationale or trade-offs
• ✅ Documents domain-specific knowledge
• ✅ Identifies effective patterns or anti-patterns
• ✅ Clarifies tool setup or configuration gotchas

Documentation template from the docs:

#### Gotcha: [Descriptive Title]

**Context**: When this occurs
**Issue**: What goes wrong
**Solution**: How to handle it

```typescript
// ✅ CORRECT
const example = "correct approach";

// ❌ WRONG
const wrong = "incorrect approach";

**Key insight:** Capture learnings while context is fresh, not during retrospectives when details are lost. Ask "What do I wish I'd known at the start?" after every significant change.

---

## 🎯 Why These Skills Are Different

Unlike typical style guides, these skills provide:

1. **Decision frameworks** - Concrete questions to answer before taking action (not vague principles)
2. **Priority classifications** - Objective severity levels to prevent over/under-engineering
3. **Anti-pattern catalogs** - Side-by-side good/bad examples showing exactly what to avoid
4. **Git verification methods** - How to audit compliance after the fact
5. **Quality gates** - Verifiable checklists before commits
6. **Problem-oriented** - Organized by the problems you face, not abstract concepts

**Most valuable insight across all skills:** Abstract based on **semantic meaning** (what code represents), not **structural similarity** (what code looks like). This single principle prevents most bad abstractions.

---

### Schema-First Decision Framework Example

One of the most valuable additions - a 5-question framework for when schemas ARE vs AREN'T required:

```typescript
// ✅ Schema REQUIRED - Trust boundary (API response)
const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email() });
const user = UserSchema.parse(apiResponse);

// ❌ Schema OPTIONAL - Pure internal type
type Point = { readonly x: number; readonly y: number };

Ask yourself:

1. Does data cross a trust boundary? → Schema required
2. Does type have validation rules? → Schema required
3. Is this a shared data contract? → Schema required
4. Used in test factories? → Schema required
5. Pure internal type? → Type is fine

→ Read the agents documentation

Seven specialized sub-agents that run in isolated context windows to enforce CLAUDE.md principles and manage development workflow:

Use proactively when planning to write code, or reactively to verify TDD was followed.

What it checks:

• ✅ Tests were written before production code
• ✅ Tests verify behavior (not implementation)
• ✅ All code paths have test coverage
• ✅ Tests use public APIs only
• ❌ Flags implementation-focused tests
• ❌ Catches missing edge case tests

Example invocation:

You: "I just implemented payment validation. Can you check TDD compliance?"
Claude Code: [Launches tdd-guardian agent]

Output:

• Lists all TDD violations with file locations
• Identifies implementation-focused tests
• Suggests missing test cases
• Provides actionable recommendations

Use before commits or when adding new types/schemas.

What it checks:

• ❌ any types (must use unknown or specific types)
• ❌ Type assertions without justification
• ❌ interface for data structures (use type)
• ✅ Schema-first development (schemas before types at trust boundaries)
• ✅ Immutable data patterns
• ✅ Options objects over positional parameters

Includes the nuanced schema-first framework:

• Schema required: Trust boundaries, validation rules, contracts, test factories
• Schema optional: Internal types, utilities, state machines, behavior contracts

Example invocation:

You: "I've added new TypeScript code. Check for type safety violations."
Claude Code: [Launches ts-enforcer agent]

Output:

• Critical violations (any types, missing schemas at boundaries)
• High priority issues (mutations, poor structure)
• Style improvements (naming, parameter patterns)
• Compliance score with specific fixes

Use after achieving green tests (the REFACTOR step in RED-GREEN-REFACTOR).

What it analyzes:

• 🎯 Knowledge duplication (DRY violations)
• 🎯 Semantic vs structural similarity
• 🎯 Complex nested conditionals
• 🎯 Magic numbers and unclear names
• 🎯 Immutability violations

What it doesn't recommend:

• ❌ Refactoring code that's already clean
• ❌ Abstracting structurally similar but semantically different code
• ❌ Cosmetic changes without clear value

Example invocation:

You: "My tests are passing, should I refactor anything?"
Claude Code: [Launches refactor-scan agent]

Output:

• 🔴 Critical refactoring needed (must fix)
• ⚠️ High value opportunities (should fix)
• 💡 Nice to have improvements (consider)
• ✅ Correctly separated code (keep as-is)
• Specific recommendations with code examples

Use proactively when creating documentation or reactively to review and improve existing docs.

What it ensures:

• ✅ Value-first approach (why before how)
• ✅ Scannable structure (visual hierarchy, clear headings)
• ✅ Progressive disclosure (quick start before deep dive)
• ✅ Problem-oriented navigation (organized by user problems)
• ✅ Concrete examples showing value (not just descriptions)
• ✅ Cross-references and multiple entry points
• ✅ Actionable next steps in every section

What it checks:

• ❌ Wall of text without visual breaks
• ❌ Feature lists without value demonstrations
• ❌ Installation-first (before showing what it does)
• ❌ Missing navigation aids
• ❌ Broken links or outdated information

Example invocation:

You: "I need to write a README for this feature."
Claude Code: [Launches docs-guardian agent]

You: "Can you review the documentation I just wrote?"
Claude Code: [Launches docs-guardian agent]

Output:

• Assessment against 7 pillars of world-class documentation
• Critical issues (must fix) vs nice-to-haves
• Specific improvement recommendations with examples
• Proposed restructuring for better discoverability
• Templates for common documentation types (README, guides, API docs)

Use proactively when discovering gotchas, or reactively after completing complex features.

What it captures:

• Gotchas or unexpected behavior discovered
• "Aha!" moments or breakthroughs
• Architectural decisions being made
• Patterns that worked particularly well
• Anti-patterns encountered
• Tooling or setup knowledge gained

Example invocation:

You: "I just fixed a tricky timezone bug. Let me document this gotcha."
Claude Code: [Launches learn agent]

Output:

• Asks discovery questions about what you learned
• Reads current CLAUDE.md to check for duplicates
• Proposes formatted additions to CLAUDE.md
• Provides rationale for placement and structure

Use proactively when starting significant multi-step work, or reactively to update progress, capture learnings, and handle blockers.

Three-Document Model:

What it manages:

• Creates and maintains three documents for significant work
• Enforces small increments, TDD, and commit approval
• Never modifies PLAN.md without explicit user approval
• Captures learnings as they occur
• At end: orchestrates learning merge, then deletes all three docs

Example invocation:

You: "I need to implement OAuth with JWT tokens and refresh logic"
Claude Code: [Launches progress-guardian to create PLAN.md, WIP.md, LEARNINGS.md]

You: "Tests are passing now"
Claude Code: [Launches progress-guardian to update WIP.md and ask for commit approval]

Output:

• PLAN.md - Approved steps with acceptance criteria
• WIP.md - Current step, status, blockers, next action
• LEARNINGS.md - Gotchas, patterns, decisions discovered
• At end: learnings merged into CLAUDE.md/ADRs, all docs deleted

Key distinction: Creates TEMPORARY documents (deleted when done). Learnings merged into permanent knowledge base first.

Related skill: Load planning skill for detailed incremental work principles.

Use proactively when making significant architectural decisions, or reactively to document decisions already made.

What it documents:

• Significant architectural choices with trade-offs
• Technology/library selections with long-term impact
• Pattern decisions affecting multiple modules
• Performance vs maintainability trade-offs
• Security architecture decisions

When to use:

• ✅ Evaluated multiple alternatives with trade-offs
• ✅ One-way door decisions (hard to reverse)
• ✅ Foundational choices affecting future architecture
• ❌ Trivial implementation choices
• ❌ Temporary workarounds
• ❌ Standard patterns already in CLAUDE.md

Example invocation:

You: "Should we use BullMQ or AWS SQS for our job queue?"
Claude Code: [Launches adr agent to help evaluate and document]

You: "I decided to use PostgreSQL over MongoDB"
Claude Code: [Launches adr agent to document the rationale]

Output:

• Structured ADR in docs/adr/ with context and alternatives
• Honest assessment of pros/cons and trade-offs
• Clear rationale for decision
• Consequences (positive, negative, neutral)
• Updated ADR index

Key distinction: Documents WHY architecture chosen (permanent), vs learn agent's HOW to work with it (gotchas, patterns).

Quick navigation by situation:

Once installed (via any option below), here's the typical development flow:

1. Start feature: Plan with Claude, let tdd-guardian guide test-first approach
2. Write tests: Get RED (failing test)
3. Implement: Get GREEN (minimal code to pass)
4. Refactor: Run refactor-scan to assess opportunities
5. Review: Run ts-enforcer and tdd-guardian before commit
6. Document: Use learn agent to capture insights, docs-guardian for user-facing docs
7. Commit: Follow conventional commits format

Agent invocation examples:

Agents can be invoked implicitly (Claude detects when to use them) or explicitly:

• Implicit: "I just implemented payment processing. Can you verify I followed TDD?" → Claude automatically launches tdd-guardian
• Explicit: "Launch the refactor-scan agent to assess code quality" → Claude launches refactor-scan
• Multiple agents: "Run TDD, TypeScript, and refactoring checks on my recent changes" → Claude launches all three in parallel

Now choose your installation method:

Best for: Individual developers who want consistent practices across all projects

Why choose this:

• ✅ One-time setup applies everywhere automatically
• ✅ No per-project configuration needed
• ✅ Works with Claude Code immediately
• ✅ Modular structure loads details on-demand
• ✅ Easy updates via git pull

One-liner installation:

curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash

One-liner with options (use bash -s -- to pass arguments):

# Install with OpenCode support
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --with-opencode

# Install specific version
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --version v2.0.0

Or download and run:

curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh -o install-claude.sh
chmod +x install-claude.sh
./install-claude.sh

Install options:

./install-claude.sh                    # Install everything (CLAUDE.md + skills + commands + agents)
./install-claude.sh --claude-only      # Install only CLAUDE.md
./install-claude.sh --skills-only      # Install only skills
./install-claude.sh --no-agents        # Install without agents
./install-claude.sh --with-opencode    # Also install OpenCode configuration
./install-claude.sh --version v2.0.0   # Install v2.0.0 (modular docs)
./install-claude.sh --version v1.0.0   # Install v1.0.0 (single file)

What gets installed (v3.0.0):

• ✅ ~/.claude/CLAUDE.md (~100 lines - lean core principles)
• ✅ ~/.claude/skills/ (9 auto-discovered patterns: tdd, testing, typescript-strict, functional, refactoring, expectations, planning, front-end-testing, react-testing)
• ✅ ~/.claude/commands/ (1 slash command: /pr)
• ✅ ~/.claude/agents/ (8 automated enforcement agents)

Optional: Enable GitHub MCP Integration

For enhanced GitHub workflows with native PR/issue integration:

Step 1: Create a GitHub Personal Access Token

Go to https://github.com/settings/tokens and create a token:

For Fine-grained token (recommended):

• Repository access: All repositories (or select specific ones)
• Permissions required:
  • Contents: Read and write
  • Pull requests: Read and write
  • Issues: Read and write
  • Metadata: Read-only (automatically included)

For Classic token:

• Select the repo scope (full control of private repositories)

Step 2: Add the MCP Server

claude mcp add --transport http --scope user github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_TOKEN"

Replace YOUR_GITHUB_TOKEN with the token you created.

Step 3: Verify Connection

Restart Claude Code and run /mcp to verify the GitHub server shows as connected.

What this enables:

• Native PR creation, updates, and reviews
• Issue management without CLI parsing
• Structured GitHub API access
• @github:pr://123 - Reference PRs directly in prompts
• @github:issue://45 - Reference issues directly in prompts

Optional: Enable OpenCode Support

These guidelines also work with OpenCode - an open source AI coding agent. OpenCode uses AGENTS.md for custom instructions (similar to CLAUDE.md in Claude Code).

How OpenCode Integration Works:

OpenCode doesn't automatically read ~/.claude/ files. Instead, it uses a configuration file to specify which instruction files to load. The opencode.json configuration tells OpenCode to load your CLAUDE.md and skills files.

Installation:

# One-liner with OpenCode support
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --with-opencode

# Or download and run with options
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh -o install-claude.sh
chmod +x install-claude.sh
./install-claude.sh --with-opencode

# Install OpenCode config only (if you already have CLAUDE.md installed)
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --opencode-only

What gets installed:

• ~/.config/opencode/opencode.json - Configuration that loads:
  • ~/.claude/CLAUDE.md (core principles)
  • ~/.claude/skills/*/SKILL.md (all skill patterns)

Manual Installation:

If you prefer to set it up manually:

mkdir -p ~/.config/opencode
cat > ~/.config/opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "~/.claude/CLAUDE.md",
    "~/.claude/skills/*/SKILL.md"
  ]
}
EOF

Learn more:

• OpenCode Documentation
• OpenCode Rules Configuration
• OpenCode GitHub

Best for: Team projects where you want full control and project-specific configuration

Why choose this:

• ✅ Full enforcement in a specific project
• ✅ Team can collaborate on customizations
• ✅ Version control with your project
• ✅ Works without global installation

For full enforcement in a specific project, install both CLAUDE.md and the agents:

# In your project root
mkdir -p .claude/agents

# Download CLAUDE.md
curl -o .claude/CLAUDE.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/CLAUDE.md

# Download all agents
curl -o .claude/agents/tdd-guardian.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/agents/tdd-guardian.md
curl -o .claude/agents/ts-enforcer.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/agents/ts-enforcer.md
curl -o .claude/agents/refactor-scan.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/agents/refactor-scan.md
curl -o .claude/agents/docs-guardian.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/agents/docs-guardian.md
curl -o .claude/agents/learn.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/agents/learn.md
curl -o .claude/agents/progress-guardian.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/agents/progress-guardian.md
curl -o .claude/agents/adr.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/agents/adr.md

# Download agents README
curl -o .claude/agents/README.md https://raw.githubusercontent.com/citypaul/.dotfiles/main/claude/.claude/agents/README.md

Best for: Quick evaluation or when you want everything in one standalone file

Why choose this:

• ✅ Single command, one file (1,818 lines)
• ✅ All content included - examples, anti-patterns, decision frameworks
• ✅ Works standalone (no broken imports)
• ✅ No agent overhead
• ⚠️ Tradeoff: Larger file vs v2.0.0's modular structure (156 lines + separate docs)
• ⚠️ Tradeoff: Uses v1.0.0 structure (content identical to v2.0.0, just organized differently)

Important: This downloads the v1.0.0 monolithic version. v3.0.0 no longer has @import issues - CLAUDE.md is fully self-contained with skills loaded on-demand. For project-level use, v3.0.0 is now recommended.

Download the complete single-file version:

# In your project root
mkdir -p .claude
curl -o .claude/CLAUDE.md https://raw.githubusercontent.com/citypaul/.dotfiles/v1.0.0/claude/.claude/CLAUDE.md

This gives you the complete guidelines (1,818 lines) in a single standalone file.

Best for: Teams with specific standards who need full customization control

Why choose this:

• ✅ Complete control over guidelines and enforcement
• ✅ Customize for your team's specific tech stack
• ✅ Modify agent behavior to match your workflow
• ✅ Maintain team-specific patterns and anti-patterns

How to customize:

1. Fork this repository
2. Modify CLAUDE.md to match your team's preferences
3. Customize agents to enforce your specific rules
4. Commit to your fork
5. Pull into your projects

Current version (v3.0.0): Skills-based architecture with lean CLAUDE.md (~100 lines) + 9 auto-discovered skills + planning workflow

Previous version (v2.0.0): Modular structure with main file (156 lines) + 6 detailed docs loaded via @imports (~3000+ lines total)

Legacy version (v1.0.0): Single monolithic file (1,818 lines, all-in-one)

• v3.0.0 (current): https://github.com/citypaul/.dotfiles/tree/main/claude/.claude
• v2.0.0 modular docs: https://github.com/citypaul/.dotfiles/tree/v2.0.0/claude/.claude
• v1.0.0 single file: https://github.com/citypaul/.dotfiles/blob/v1.0.0/claude/.claude/CLAUDE.md

The installation script installs v3.0.0 by default. Use --version v2.0.0 or --version v1.0.0 for older versions.

• CLAUDE.md - Core development principles (~100 lines)
• Skills - Auto-discovered patterns (7 skills: tdd, testing, typescript-strict, functional, refactoring, expectations, planning)
• Commands - Slash commands (/pr)
• Agents README - Detailed agent documentation with examples
• Agent Definitions - Individual agent configuration files

• Teams adopting TDD - Automated enforcement prevents backsliding
• TypeScript projects - Nuanced schema-first guidance with decision frameworks
• AI-assisted development - Consistent quality with Claude Code or similar tools
• Solo developers - Institutional knowledge that doesn't rely on memory
• Code reviewers - Objective quality criteria and git verification methods

This system is based on several key insights:

1. AI needs explicit context - Vague principles → inconsistent results. Decision frameworks → reliable outcomes.

2. Quality gates prevent drift - Automated checking catches violations before they become habits.

3. Refactoring needs priority - Not all improvements are equal. Critical/High/Nice/Skip classification prevents over-engineering.

4. Semantic beats structural - Abstract based on meaning (business concepts), not appearance (code structure).

5. Document while fresh - Capture learnings immediately, not during retrospectives when context is lost.

6. Explicit "no refactoring" - Saying "code is already clean" prevents the feeling that the refactor step was skipped.

CLAUDE.md and the agents evolve based on real usage. The learn agent ensures valuable insights are captured and integrated:

• Gotchas discovered → Documented in CLAUDE.md
• Patterns that work → Added to examples
• Anti-patterns encountered → Added to warnings
• Architectural decisions → Preserved with rationale

This creates a self-improving system where each project session makes future sessions more effective.

While most visitors are here for CLAUDE.md, this repository's original purpose is managing my personal development environment. If you're interested in dotfiles, here's what's included and how to use them.

I have an extensive collection of git aliases that speed up common workflows. These are in git/.gitconfig.

Most useful aliases:

# Pretty log with graph
git lg          # One-line log with graph
git lga         # All branches log with graph
git lgp         # Log with patch (shows changes)

# Status and diff shortcuts
git st          # git status
git di          # git diff
git dc          # git diff --cached
git ds          # git diff --stat

# Commit shortcuts
git ci          # git commit
git ca          # git commit --amend
git cane        # git commit --amend --no-edit

# Branch management
git co          # git checkout
git cob         # git checkout -b (new branch)
git br          # git branch
git brd         # git branch -d (delete branch)

# Working with remotes
git pu          # git push
git puf         # git push --force-with-lease (safer force push)
git pl          # git pull
git plo         # git pull origin

# Stash shortcuts
git sl          # git stash list
git ss          # git stash save
git sp          # git stash pop

# Undo shortcuts
git undo        # Undo last commit (keeps changes)
git unstage     # Unstage files
git uncommit    # Undo commit and unstage

# Advanced workflows
git wip         # Quick "work in progress" commit
git unwip       # Undo WIP commit
git squash      # Interactive rebase to squash commits

Installation:

# Install just the git config
cd ~/.dotfiles
stow git

# Or manually copy specific aliases you want
cat git/.gitconfig >> ~/.gitconfig

My shell setup (for bash/zsh) includes:

• Prompt customization - Git status in prompt
• Useful functions - Project navigation helpers
• PATH management - Tool directories
• Environment variables - Editor, pager, etc.

Files:

• bash/.bashrc - Bash configuration
• bash/.bash_profile - Bash login shell
• zsh/.zshrc - Zsh configuration (if you use zsh)

Installation:

cd ~/.dotfiles
stow bash  # or stow zsh

Configuration files for various development tools:

• vim/.vimrc - Vim editor configuration
• tmux/.tmux.conf - Terminal multiplexer settings
• npm/.npmrc - npm configuration

The claude/.claude/settings.json file contains my personal Claude Code configuration including:

• claude-powerline - vim-style statusline with usage tracking and git integration
• Official Anthropic plugins - feature-dev, frontend-design, hookify, learning-output-style, plugin-dev, security-guidance

⚠️ Important: This installs ALL personal dotfiles (git, shell, vim, etc.) NOT just CLAUDE.md

⚠️ Requires: GNU Stow must be installed first

For CLAUDE.md only (no stow needed), see Option 3 above.

To install all dotfiles including my personal configurations:

# Install GNU Stow first (if not already installed)
# macOS: brew install stow
# Ubuntu/Debian: sudo apt-get install stow
# Fedora: sudo dnf install stow

# Clone the repository
git clone https://github.com/citypaul/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# Run the installation script
./install.sh

# This uses GNU Stow to create symlinks for all configurations

This will install:

• ✅ CLAUDE.md + 9 skills + 8 agents (development guidelines)
• ✅ Commands (/pr slash command)
• ✅ Claude Code settings.json (plugins, hooks, statusline)
• ✅ Git aliases and configuration
• ✅ Shell configuration (bash/zsh)
• ✅ Vim, tmux, npm configs
• ✅ All personal preferences

⚠️ Requires: GNU Stow (see installation commands above)

Only want certain configurations? Install them individually:

cd ~/.dotfiles

# Install just git config
stow git

# Install just bash config
stow bash

# Install vim config
stow vim

# Install multiple at once
stow git bash vim

This repository uses GNU Stow for dotfile management:

1. Each directory (git/, bash/, etc.) represents a "package"
2. Files inside mirror your home directory structure
3. stow git creates symlinks from ~/.gitconfig → ~/.dotfiles/git/.gitconfig
4. Changes to files in ~/.dotfiles are instantly reflected
5. Uninstall with stow -D git

Feel free to browse the repository and cherry-pick what's useful:

• git/.gitconfig - Git aliases and configuration
• bash/.bashrc - Bash shell configuration
• vim/.vimrc - Vim editor setup

Note: These are my personal preferences. Review before installing - you may want to customize them for your workflow.

This is a personal repository that became unexpectedly popular. Contributions are welcome, especially:

• Improvements to CLAUDE.md - Better decision frameworks, clearer examples
• Agent enhancements - New checks, better error messages
• Documentation - Clarifications, additional examples
• Real-world feedback - What worked? What didn't?

Please open issues or PRs on GitHub.

Paul Hammond

• LinkedIn - Feel free to connect and discuss
• GitHub Issues - Questions, suggestions, feedback

Special thanks to contributors who have shared their work:

• Kieran O'Hara - The use-case-data-patterns agent is adapted from Kieran's dotfiles. Thank you for creating and sharing this excellent agent specification.

This repository is open source and available for use. The CLAUDE.md file and agents are designed to be copied and customized for your projects.

If you found CLAUDE.md or the agents valuable, consider:

• Starring this repo on GitHub
• Sharing it with your team
• Contributing improvements back
• Connecting on LinkedIn to share your experience

The more people who adopt these practices, the better the AI-assisted development ecosystem becomes for everyone.