DEV Community: Paul Duvall

Sharing AI Development Rules Across Your Organization

Paul Duvall — Sat, 31 Jan 2026 17:44:03 +0000

Originally published on paulmduvall.com

How centralized-rules achieved 74.4% token savings and consistent AI behavior with progressive disclosure and context-aware rule loading.

Every developer on your team likely has their own AI rules file. One person's CLAUDE.md says "always write tests." Another's says "use TypeScript strict mode." A third developer just copies whatever worked on their last project. Meanwhile, your AI coding assistants—Claude Code, Cursor, GitHub Copilot, Gemini—are getting inconsistent instructions across every project and every person.

This is the AI rules governance problem, and at scale, it's costing you tokens, consistency, and quality. A central CLAUDE.md file can help, but it quickly bloats when you try to cover every scenario—and worse, it can't be specific to your particular environment or project. The AI may not even read all of it.

I built centralized-rules to solve it, based on the centralized-rules pattern I've been experimenting with. After two months of using this approach in my own work, the result: 74.4% token savings and consistent AI behavior that scales across teams.

The Enterprise AI Rules Problem

AI coding tools are now common across development teams. But each tool needs configuration to perform well—Claude Code uses CLAUDE.md and .claude/ directories, Cursor uses .cursorrules, and other tools have their own configuration patterns.

Without centralization, you get:

Tribal knowledge: Best practices live in individual developers' heads (and their personal config files)
Copy-paste chaos: Teams share rules via Slack, and they drift immediately
Onboarding friction: New developers spend days figuring out "how we do AI here"
Token waste: Loading all rules when you only need a subset for your specific context

With hundreds of developers across teams, this becomes ungovernable. You can't audit what instructions your AI tools are receiving. You can't ensure security rules are consistently applied. You can't measure whether your AI development standards are actually being followed.

The Solution: Centralized Rules with Progressive Disclosure

The core insight is simple: one source of truth, versioned in Git, with context-aware loading.

Instead of every developer maintaining their own rules, you maintain a single repository of AI development rules. But here's the key—you don't load all of them all the time. That would overwhelm the AI and waste tokens.

Instead, the system uses progressive disclosure—a technique that loads only relevant rules based on context:

Detect context: Scan the project for language markers (package.json, pyproject.toml, go.mod)
Match keywords: Analyze the prompt for task-specific terms (test, security, refactor)
Display banner: Show which rules apply to the current task
Apply rules: AI follows only the relevant coding standards

The rules themselves are organized in a four-dimensional structure:

Base: Universal rules that apply to all projects (git workflow, code quality, security principles)
Language: Language-specific rules (Python, TypeScript, Go, Java, C#, Rust)
Framework: Framework-specific rules (React, Django, FastAPI, Express, Spring Boot)
Cloud: Cloud provider rules (AWS, Vercel, with Azure and GCP extensible)

This follows the MECE principle (Mutually Exclusive, Collectively Exhaustive)—no duplication across dimensions, complete coverage of common scenarios.

How It Works

The install script auto-detects your project configuration:

# Language detection
pyproject.toml → Load Python rules
package.json → Load JavaScript/TypeScript rules
go.mod → Load Go rules

# Framework detection
"fastapi" in dependencies → Load FastAPI rules
"react" in dependencies → Load React rules

# Cloud detection
vercel.json → Load Vercel rules

Token Efficiency

Here's the measured impact across different task types:

Task Type	Files Loaded	Tokens Used	Tokens Saved	Savings
Code Review	2 files	3,440	21,796	86.4%
Write Tests	2 files	11,163	14,073	55.8%
FastAPI Endpoint	3 files	8,608	16,628	65.9%
Git Commit	2 files	2,618	22,618	89.6%
Average	2.25 files	6,457	18,779	74.4%

Quick Start

Installation is one command, and it's idempotent (safe to run multiple times):

# Global installation (all projects)
curl -fsSL https://raw.githubusercontent.com/paulduvall/centralized-rules/main/install-hooks.sh | bash

# Project-specific installation
curl -fsSL https://raw.githubusercontent.com/paulduvall/centralized-rules/main/install-hooks.sh | bash -s -- --local

Get Started

The repository is open source under MIT license: github.com/PaulDuvall/centralized-rules

Star it, try it, and let me know any changes you'd like to see.

✦ Read the original and more at paulmduvall.com

Customizing Claude Code: What I Learned from Losing Everything

Paul Duvall — Mon, 01 Sep 2025 21:10:27 +0000

Imagine that you've spent weeks building a set of custom Claude Code slash commands. Custom shortcuts that know your workflow, your coding standards, your deployment pipeline. Then one day they're just gone. Maybe you switched machines, maybe a config got corrupted, maybe you just forgot to version control them properly.

That's what happened to me. I'd built numerous custom slash commands in Claude Code. /xgit ran my git workflows. /xdocs generated documentation. /xsecurity checked security requirements over and above deterministic tooling.

I learned later it was because I'd configured them for one of the projects I was no longer using. When I switched contexts, everything disappeared. I'd built customization without making it portable or persistent.

The irony wasn't lost on me—I've always been an advocate for version controlling everything in software development. But while learning Claude Code, I got lulled into treating these commands as disposable experiments rather than valuable assets. The ease of creating them made me forget their importance until they were gone.

So I rebuilt everything—but this time with a system designed to survive project switches and machine changes.

Building Customizations That Last

What I learned: customization needs to be portable across projects, machines, and teams.

The toolkit is distributed as an NPM package, making installation straightforward and consistent across all platforms. If you want to see the full collection of examples and patterns, visit https://github.com/PaulDuvall/claude-code:

# 1. Install Claude Code (if you haven't already)
npm install -g @anthropic-ai/claude-code

# 2. Install Claude Dev Toolkit via NPM
npm install -g @paulduvall/claude-dev-toolkit

# 3. Deploy commands to Claude Code
claude-commands install --active # Install core commands

# 4. Install Claude Code subagents (Optional)
claude-commands subagents --install

# 5. Configure settings (Optional)
claude-commands config --list  # View available templates
claude-commands config --template <template-name>  # Apply your preferred template
# Learn more: https://docs.anthropic.com/en/docs/claude-code/settings

The toolkit handles deployment automatically, preventing the fragmentation that caused my original loss. The NPM package contains all commands, templates, and configuration files you need.

For those interested in exploring the source code or contributing:

# Optional: View source code and contribute
git clone https://github.com/PaulDuvall/claude-code.git

The NPM package is completely self-contained, so you can install, configure, and customize Claude Code without needing the repository.

Real persistence comes from CLAUDE.md - Claude Code's reference guide for your project. This file is what makes customization truly portable. When I lost my commands, I also lost all the context about why they existed and how to use them. The CLAUDE.md structure captures core philosophy, command categories, and development guidelines.

Advanced Features Deep Dive

Custom Commands

Here's something I learned: custom slash commands work best when deterministic tooling won't cut it—when you need AI's judgment, creativity, or pattern recognition. I didn't always follow this rule when creating my custom slash commands. Some, like /xtest, could arguably be simple shell scripts. But the real power comes when AI enhances the tooling.

Take /xdebug or /xarchitecture—these leverage AI to analyze patterns, suggest improvements, and make decisions that pure scripts cannot. The magic happens when agents combine deterministic tools (running tests, checking syntax) with AI reasoning (understanding context, making architectural decisions, generating creative solutions).

Custom slash commands are markdown files stored in:

Machine-wide: ~/.claude/commands/
Project-specific: .claude/commands/

Each command is a markdown file with name, description, and system prompt. For more details, see the slash commands documentation.

The custom slash commands in the toolkit are markdown files that define custom behaviors. The "x" prefix is my convention for custom commands.

My core/active custom slash commands evolved from real needs:

/xtest, /xquality, /xgit - Daily development workflow
/xsecurity, /xrefactor - Code improvement and safety
/xdebug, /xarchitecture - Complex problem-solving that needs AI insight
/xspec, /xdocs - Documentation and requirements
/xpipeline, /xrelease, /xconfig - CI/CD automation

Creating custom commands is straightforward: write markdown files in .claude/commands/ and they become available automatically. The real value emerges when you chain them:

/xtest       # Run tests with coverage
/xsecurity   # Scan for vulnerabilities  
/xquality    # Check code quality
/xgit        # Commit and push with AI-generated message

This workflow replaces dozens of manual steps with four commands. Always version control your .claude/ directory—it's your customization insurance policy.

Hooks: Intercepting Claude Code's Operations

Hooks are shell scripts that intercept Claude Code's operations. They trigger on events like UserPromptSubmit (when you send a message), PreToolUse (before Claude Code runs commands), PostToolUse (after file edits), and SessionStart (when starting Claude Code). Store them in:

Machine-wide: ~/.claude/hooks/
Project-specific: .claude/hooks/

The toolkit includes hooks and subagents that work together. Hooks intercept operations while subagents provide AI-powered analysis and decision-making. This combination creates a powerful workflow where deterministic controls (hooks) trigger intelligent responses (subagents) that don't rely on AI remembering to check for issues—they enforce it every time.

Start Building

Install with npm install -g @paulduvall/claude-dev-toolkit
Deploy commands with claude-commands install --active
Create CLAUDE.md with project context
Build custom commands in .claude/commands/
Install Subagents for persistent context: claude-commands subagents --install
Version control everything

Some of my customizations were inspired by my patterns at https://github.com/PaulDuvall/ai-development-patterns.

I never want to lose my customizations again. That's why everything lives in version control now—portable across projects, machines, and teams. When you build your system, remember: customization lets you focus on architecture and problem-solving, but only if it survives. Start small, build systematically, version control everything.

Dive Deeper

For advanced techniques and more detailed examples of commands, configuration, and hooks, see my post: Claude Code Advanced Tips: Using Commands, Configuration, and Hooks.