Claude Code Guidelines Template

A template repository for managing Claude Code guidelines across multiple projects using version control, DRY principles, and on-demand skills.

Features

• 🔄 DRY Guidelines: Write once in common/, reuse across projects
• 📦 Skills System: Extract detailed workflows to on-demand skills (reduces baseline context)
• 🎯 Project Overrides: Customize common patterns per project
• 🔗 Auto-linking: Build script creates symlinks automatically
• ✅ Tested: Comprehensive test suite ensures reliability
• 📝 YAML Config: Easy-to-edit configuration

Why Use This System?

The Problem

Claude Code loads guidelines from:

• ~/.claude/CLAUDE.md (global for all projects)
• PROJECT_DIR/CLAUDE.local.md (project-specific)

Simple approaches:

• Global only (~/.claude/CLAUDE.md) - One file for everything, but no project-specific context
• Per-project only - Each project has its own CLAUDE.local.md, but you duplicate common patterns across projects

When This System Makes Sense

Use this system if you have:

• ✅ Multiple projects - More than 2-3 projects that need guidelines
• ✅ Shared patterns - Common workflows you use across projects (git conventions, review process, decision frameworks)
• ✅ Project-specific needs - Different tech stacks, structures, or domains per project
• ✅ Evolving practices - You want to track how your development practices improve over time

Benefits you get:

1. DRY Principle - Write common patterns once, reuse across projects
2. Modular Composition - Each project selects which common guidelines to include (not all-or-nothing)
3. Version Control - Track guideline evolution, see what worked, rollback changes
4. Project Customization - Tech stack and domain-specific guidelines per project, with overrides for common patterns
5. Context Optimization - Skills system reduces baseline context by loading details on-demand
6. Consistency - Update a pattern once, rebuild to apply everywhere that uses it

When Simpler Approaches Work Better

Skip this system if:

• ❌ Single project - Just use CLAUDE.local.md in that project's repo
• ❌ No shared patterns - Every project is completely different
• ❌ Static guidelines - You don't update practices regularly
• ❌ Quick experiment - Testing Claude Code for the first time

Use instead:

# Global universal principles
~/.claude/CLAUDE.md

# Project-specific guidelines (version controlled in each repo)
~/Projects/my-app/CLAUDE.local.md
~/Projects/another-app/CLAUDE.local.md

The Hybrid Approach

Many users benefit from combining both:

• ~/.claude/CLAUDE.md - Truly universal principles (work for any project)
• This system - Your shared patterns across YOUR projects with project-specific customization

Quick Start

1. Clone This Template

git clone https://github.com/YOUR-USERNAME/claude-guidelines-template.git claude-guidelines
cd claude-guidelines

2. Add Your First Project

# Create project directory
mkdir -p projects/my-project

# Create project file
cat > projects/my-project/main.project.md << 'EOF'
# My Project

## Tech Stack
- [Your stack here]

## Project Structure
- [Your structure]

## Key Patterns
- [Your patterns]
EOF

3. Configure Build

Edit builds.yml:

builds:
  - name: My Project
    project: projects/my-project/main.project.md
    output: generated/my-project/guidelines.md
    link_to: ~/Projects/my-project/CLAUDE.local.md  # Path to actual project
    common:
      - common/preferences.md
    skills: []  # Add skills as needed

4. Build

./build.rb

This generates:

• generated/my-project/guidelines.md (in this repo)
• generated/my-project/.claude/skills/ (skill directories, if configured)
• Symlink at ~/Projects/my-project/CLAUDE.local.md (points to generated file)
• Symlink at ~/Projects/my-project/.claude/skills/ (points to generated skills)

Claude Code will now use these guidelines when working in your project!

Repository Structure

claude-guidelines/
├── common/                    # Shared guidelines (DRY)
│   ├── preferences.md        # Example: General preferences
│   └── _editing-instructions.md
├── projects/                  # Project-specific content
│   └── example-project/
│       └── main.project.md
├── skills/                    # On-demand skills (loaded when invoked)
│   └── example-skill/
│       └── SKILL.md
├── generated/                 # Generated files (created by build.rb)
│   └── example-project/
│       ├── guidelines.md      # → Symlinked to actual project
│       └── .claude/           # Skills directory
├── learnings/                 # Track what works (not in builds)
│   └── README.md
├── test/                      # Test suite
│   ├── build_test.rb
│   └── README.md
├── build.rb                   # Build script
├── builds.yml                 # Build configuration
├── Rakefile                   # Rake tasks
└── README.md                  # This file

Core Concepts

Common Guidelines

Files in common/ are shared across all projects that include them:

# common/preferences.md
When writing code:
- Match existing patterns
- Keep it simple
- Ask questions when uncertain

Project-Specific Content

Each project has its own directory in projects/:

# projects/my-app/main.project.md
# My App

## Tech Stack
- Rails 7, PostgreSQL, React

## Project Structure
- app/services/ - Business logic
- app/controllers/ - Keep thin

Skills (On-Demand Loading)

Skills are detailed workflows loaded only when invoked with /skill-name:

# skills/commit/SKILL.md
---
name: commit
description: Create well-formatted git commits
---

# Commit Guidelines
[Detailed commit message format, examples, checklist...]

Benefits:

• Reduces baseline context (skills not loaded unless needed)
• Detailed information available on-demand
• Modular and maintainable

Override System

Projects can override common files with project-specific versions:

common/git-workflow.md          # Universal git patterns
projects/my-project/git-workflow.md  # Project-specific (overrides common/)

Hierarchical resolution:

1. Check projects/my-project/git-workflow.md (most specific)
2. Check parent directories
3. Fall back to common/git-workflow.md

Usage

Building

# Build all projects
./build.rb

# Via rake
rake build

Testing

# Run tests
ruby test/build_test.rb

# Via rake
rake test

# Test + build
rake verify

Adding a New Project

1. Create project directory:

   mkdir -p projects/my-project
   vim projects/my-project/main.project.md

2. Add to builds.yml:

   - name: My Project
     project: projects/my-project/main.project.md
     output: generated/my-project/guidelines.md
     link_to: ~/Projects/my-project/CLAUDE.local.md
     common:
       - common/preferences.md
     skills: []

3. Build:

   ./build.rb

Creating a Skill

1. Create skill directory:

   mkdir -p skills/my-skill

2. Create SKILL.md:

   # My Skill
   
   Detailed instructions...

3. Create meta.yml (optional, for version tracking):

   name: my-skill
   description: What this skill does
   version: 1.0.0
   category: workflow

4. Add to project in builds.yml:

   skills:
     - my-skill

5. Rebuild:

   ./build.rb

6. Invoke in Claude:

   /my-skill
   

Creating Project Overrides

If a project needs different conventions:

# Create override (same filename as common file)
vim projects/my-project/git-workflow.md

# Rebuild - your version replaces common/git-workflow.md
./build.rb

Best Practices

What Goes in common/

• ✅ Patterns that apply to most projects
• ✅ Default workflows and preferences
• ✅ Universal best practices
• ✅ Framework-agnostic guidelines

What Goes in projects/

• ✅ Tech stack specifics
• ✅ Project structure and navigation
• ✅ Domain-specific patterns
• ✅ Project-specific overrides

What Goes in skills/

• ✅ Detailed workflows (>50 lines)
• ✅ Task-specific instructions
• ✅ Reference material used occasionally
• ✅ Complex processes with multiple steps

When to Use Skills

Extract to skill when:

• Content is >50-100 lines
• Only needed for specific tasks
• Used occasionally, not constantly
• Detailed step-by-step instructions

Keep in main file when:

• Concise reference information
• Needed frequently during development
• Core patterns you want always visible

Examples

See the projects/example-project/ directory for a complete example showing:

• Project structure
• Common file usage
• Skill references
• Override patterns

Contributing

This is a template - customize it for your needs! Some ideas:

• Add more common guidelines for your tech stack
• Create skills for your workflows
• Add project-specific overrides
• Extend the test suite
• Improve documentation

Future Directions

Potential enhancements we'd like to explore:

Skill Management

• Central skill repository: Pull common skills from a shared registry
• Skill versioning: Track skill versions, allow pinning to specific versions
• Skill dependencies: Skills that reference or depend on other skills

Developer Experience

• Interactive setup wizard: Guided initial configuration (./build.rb --init)
• Guideline linting: Validate guideline format, check for common issues, verify skill references exist
• Git hooks: Auto-rebuild on commit, validate changes pre-commit

Advanced Features

• Multi-project diffs: Compare guidelines across projects to find inconsistencies
• Conditional includes: Include common files based on tech stack detection
• CI/CD examples: GitHub Actions, GitLab CI templates for automated validation
• Migration tools: Import existing CLAUDE.md files into template structure

Have ideas? Open an issue or PR! We're particularly interested in:

• Real-world usage patterns and learnings
• Skills that could be shared broadly
• Improvements to the build system
• Better testing approaches

License

MIT License - See LICENSE file

Resources

• Claude Code Documentation
• Skills Documentation

---

Happy coding with Claude! 🚀