Tools for creating CLAUDE.md files and Claude Code rules

version
1.2.0
GitHub stars
13

Install

/plugin install dp-tools@claude-code-toolkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dariuszparys/claude-code-toolkit.

Contents

Discovered from source

Commands 2

Task: Create/Update CLAUDE.md

You are helping me create or update a CLAUDE.md file. This file onboards AI coding agents into the codebase.

Step 0: Detect Context

First, determine where you are:

# Get repo root
git rev-parse --show-toplevel

# Get current directory
pwd

If current directory IS the repo root: → You are creating a ROOT CLAUDE.md (comprehensive, sets up progressive disclosure)

If current directory is BELOW the repo root: → You are creating a SUBDIRECTORY CLAUDE.md (package/app-specific, additive to root) → Read the root CLAUDE.md first to avoid duplication → After creating, offer to update root CLAUDE.md with a reference to this new file

Before Writing Anything

  1. Explore the current directory structure using find or tree
  2. Read existing documentation (README, CONTRIBUTING, existing CLAUDE.md)
  3. If in subdirectory: read the root CLAUDE.md to understand what's already covered
  4. Identify the tech stack from package.json, Cargo.toml, go.mod, or similar
  5. Look for existing patterns in the code
  6. Check for existing agent_docs/ or similar directories

Critical Constraints

Instruction Budget

  • Claude Code's system prompt uses ~50 instructions already
  • LLMs reliably follow only ~150-200 instructions total
  • Target: 60-100 lines ideal, never exceed 300 lines

The Ignore Problem

Claude Code tells the model to ignore CLAUDE.md content that isn't relevant to the current task. Every line must be universally applicable or it gets skipped.

What to Include

1. Project Identity (2-3 lines max)

  • Project name and one-sentence purpose
  • No marketing copy

2. Tech Stack (with versions)

  • Framework, language, database, ORM, key libraries
  • Include version numbers to prevent outdated suggestions

3. Essential Commands Only

  • Only commands used in >50% of sessions
  • Dev, test, build, database commands

4. Project Structure (non-obvious parts only)

  • Skip standard framework conventions
  • Focus on what would confuse a new developer

5. Hard Rules (universally applicable)

  • Things that apply to EVERY task
  • Critical "never do X" warnings
  • Architectural boundaries

6. Domain Context

  • Business logic that can't be inferred from code
  • Key domain terms — this is what auto-generators miss

7. Progressive Disclosure Pointers

Reference external docs instead of embedding:

## Docs
- `docs/database.md` — before DB changes
- `docs/auth.md` — before touching auth

What to EXCLUDE

  • Code style guidelines → use linters (Biome, ESLint)
  • Long code examples → they become outdated
  • Framework basics → Claude already knows these
  • Conditional instructions → put in separate docs
  • Historical context → "we used to..." is noise
  • TODO lists → not universally applicable

Output Structure

For ROOT CLAUDE.md (repo root)

# Project: [Name]

[One sentence purpose]

## Stack
- [Framework + version]
- [Language + config]
- [Database + ORM]

## Commands
- `cmd` — description
- `cmd` — description

## Structure
[High-level: apps, packages, key directories]

## Rules
[Universal hard rules across entire repo]

## Domain
[Business logic, key concepts]

## Docs
- `agent_docs/topic.md` — when to read

## Package Docs
Subdirectories with their own CLAUDE.md:
- `path/to/package/` — brief description

Target: 60-100 lines, comprehensive but lean.

For SUBDIRECTORY CLAUDE.md (apps/, packages/, etc.)

# [Package/App Name]

[One sentence: what this specific package does]

## Commands
- `cmd` — description (only if different from root)

## Structure
[Package-specific directories only]

## Rules
[Package-specific rules NOT covered by root]

## Domain
[Package-specific business logic if any]

Target: 30-50 lines maximum. This is ADDITIVE to root — don't repeat anything already in root CLAUDE.md.

Your Task

  1. Detect context (root vs subdirectory)
  2. If subdirectory: read root CLAUDE.md first
  3. Explore the relevant directory thoroughly
  4. Generate the CLAUDE.md content (or show diff if updating existing)
  5. For root: list any agent_docs/ files that should be created with brief descriptions
  6. For subdirectory: explicitly note what you're NOT including because it's in root
  7. For updates: explicitly state what to remove and why
  8. For subdirectory (new file): update root CLAUDE.md's "Package Docs" section

Updating Root CLAUDE.md (Subdirectory Only)

After creating a subdirectory CLAUDE.md, check the root CLAUDE.md:

  1. If "Package Docs" section exists:

    • Check if this subdirectory is already listed
    • If not, add an entry: - \path/` — brief description`
  2. If "Package Docs" section does NOT exist:

    • Add the section before the end of the file:
    ## Package Docs
    Subdirectories with their own CLAUDE.md:
    - `current/path/` — brief description of what this package does
    
  3. Present the diff for root CLAUDE.md and ask for confirmation before writing

Final Checklist

For ROOT CLAUDE.md

  • Under 100 lines (or justified if longer)
  • Every instruction is universally applicable
  • No style guides (use linters)
  • No code snippets that will become outdated
  • Uses pointers to docs, not embedded content
  • Domain knowledge included
  • A senior dev could start contributing immediately

For SUBDIRECTORY CLAUDE.md

  • Under 50 lines
  • Nothing duplicated from root CLAUDE.md
  • Only package-specific commands, rules, structure
  • Stack info only if different from root (e.g., different framework)
  • No references to agent_docs (that's root's job)

After confirmation, write the CLAUDE.md file to the current directory.

Task: Create Claude Code Rules

You are helping me create modular rules files for Claude Code. Rules are topic-specific instruction files stored in .claude/rules/.

When to Use Rules vs CLAUDE.md

Use CaseApproach
Project overview, stack, commandsCLAUDE.md
Path-specific conventions (API, tests)Rules with paths: frontmatter
Large project with many conventionsRules organized in subdirectories
Shared rules across projectsRules (can be symlinked)

Step 1: Analyze the Project

# Check if rules directory exists
ls -la .claude/rules/ 2>/dev/null || echo "No rules directory yet"

# Check existing CLAUDE.md
cat .claude/CLAUDE.md 2>/dev/null || cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"

# Understand project structure
tree -L 2 -d 2>/dev/null || find . -type d -maxdepth 2

Step 2: Identify Rule Candidates

Look for areas that would benefit from dedicated rules:

  • Language-specific: typescript.md, python.md, go.md
  • Layer-specific: api.md, frontend.md, database.md
  • Practice-specific: testing.md, security.md, logging.md
  • Domain-specific: payments.md, auth.md, notifications.md

Step 3: Choose Rule Type

A. Global Rules (no paths)

Apply to all files in the project:

# Testing Standards

- Use descriptive test names: `test_<function>_<scenario>_<expected>`
- Each test file must have a corresponding source file
- Mock external services, never call real APIs in tests

B. Path-Scoped Rules (with paths frontmatter)

Apply only to matching files:

---
paths: src/api/**/*.ts
---

# API Development Rules

- All endpoints must validate input with zod schemas
- Use standard error response format from `lib/errors`
- Rate limiting required for public endpoints

Path Pattern Examples

PatternMatches
**/*.tsAll TypeScript files
src/api/**/*.tsAPI TypeScript files only
src/**/*.{ts,tsx}All TS/TSX in src
tests/**/*.test.tsTest files only
{src,lib}/**/*.tsMultiple directories

Step 4: Create Rules Structure

For a typical project, suggest this structure:

.claude/
├── CLAUDE.md           # Main project memory (overview, stack, commands)
└── rules/
    ├── typescript.md   # Language conventions
    ├── testing.md      # Testing standards
    ├── api.md          # API-specific (paths: src/api/**)
    └── database.md     # Database conventions

For larger projects with many rules:

.claude/
├── CLAUDE.md
└── rules/
    ├── languages/
    │   ├── typescript.md
    │   └── python.md
    ├── layers/
    │   ├── api.md
    │   ├── frontend.md
    │   └── database.md
    └── practices/
        ├── testing.md
        └── security.md

Rule Writing Guidelines

Keep Rules Focused

  • One topic per file
  • 20-50 lines ideal
  • Use descriptive filenames

Use Path Scoping Sparingly

  • Only when rules genuinely don't apply project-wide
  • Prefer global rules when possible (simpler)

Avoid Duplication

  • Don't repeat what's in CLAUDE.md
  • Cross-reference: "See security.md for auth requirements"

Be Specific

Bad: "Write clean code" Good: "Functions must have max 20 lines, extract helpers for complex logic"

Output Format

For each rule file, provide:

## Rule: {filename}

**Scope**: Global / Path-scoped to `{pattern}`
**Purpose**: {one sentence}

### Content

\`\`\`markdown
{rule content}
\`\`\`

Your Task

  1. Analyze the project structure and existing CLAUDE.md
  2. Identify 2-4 rule candidates based on the codebase
  3. Present each rule with its scope and purpose
  4. Ask which rules to create
  5. Create .claude/rules/ directory if needed
  6. Write the approved rule files

After Creating Rules

Remind the user:

  • Rules are automatically loaded by Claude Code
  • No configuration needed after creating the files
  • Rules can be version controlled with the project
  • Use paths: frontmatter for path-specific rules

Sponsors

Details

Marketplace
dariuszparys/claude-code-toolkit
Source
plugins/dp-tools
Category
Community

More from dariuszparys/claude-code-toolkit

All 6