Skip to content

reboot0555/dotclaudemd

BranchesTags

Repository files navigation

dotclaudemd

CLAUDE.md Template Registry CLI — scaffold, lint, and health-check your CLAUDE.md files.

Think "github/gitignore but for CLAUDE.md."

npm version license node

Table of Contents

What is CLAUDE.md?

CLAUDE.md is a special markdown file that Claude Code reads at the start of every conversation. It tells Claude how your project works — what commands to run, where code lives, and what conventions to follow.

Think of it as a project brief for your AI pair programmer. Without it, Claude has to guess your project structure, build system, and coding style every time. With a good CLAUDE.md, Claude already knows:

  • How to build, test, and run your project
  • Your directory structure and key files
  • Framework-specific conventions (Server Components vs Client Components, Composition API vs Options API, etc.)
  • Which database, ORM, and package manager you use

Where does CLAUDE.md go?

Location Scope When Claude reads it
./CLAUDE.md Project-level When working in this project directory
./.claude/CLAUDE.md Project-level (hidden) Same as above, but keeps your root directory clean
~/.claude/CLAUDE.md Global Every conversation, in every project

You can use dotclaudemd init --global to generate the global one.

dotclaudemd vs Claude Code /init

Claude Code has a built-in /init command that generates a CLAUDE.md. Here's how it compares to dotclaudemd init:

Claude Code /init dotclaudemd init
How it works Claude reads your codebase and writes a CLAUDE.md using AI generation Selects from 19 curated templates based on your detected stack
Output quality Varies by conversation — different each time Consistent, battle-tested templates with framework-specific best practices
Customization Freeform — you can ask Claude to adjust Structured variables (styling, database, framework, etc.) with predefined options
Speed Takes 30-60s as Claude analyzes your code Instant — template selection + variable substitution
Token cost Uses Claude API tokens for generation Zero tokens — runs locally, no AI calls
Offline Requires internet connection Works fully offline
Linting None 8 built-in lint rules catch anti-patterns
Health checks None doctor command verifies CLAUDE.md stays in sync with your project
Reproducible No — regenerating gives different results Yes — same template + same variables = same output

When to use which?

Use dotclaudemd init when:

  • You want a proven, consistent starting point for your stack
  • You're setting up CLAUDE.md for the first time on a well-known framework (Next.js, Rails, Spring Boot, etc.)
  • You want to lint and health-check your CLAUDE.md over time
  • You're working offline or want to avoid spending tokens on generation
  • You need reproducible output across team members' projects

Use Claude Code /init when:

  • Your project has a unique or unconventional structure that no template covers
  • You want Claude to analyze your specific codebase and generate a tailored CLAUDE.md
  • You're working on a project that doesn't fit standard categories

Use both together:

  1. Run npx dotclaudemd init to get a solid template-based starting point
  2. Then ask Claude to refine it based on your specific project's nuances
  3. Run npx dotclaudemd lint and npx dotclaudemd doctor periodically to keep it healthy

Why

There is no standard starting point for writing CLAUDE.md files. Developers write them from scratch, often missing best practices or including anti-patterns that waste context window tokens.

dotclaudemd solves this with:

  • 19 curated templates across 8 language/framework categories
  • Auto-detection of your project stack (reads package.json, Cargo.toml, go.mod, pom.xml, Gemfile, composer.json)
  • Linting that catches anti-patterns before they cost you tokens
  • Health checks that verify your CLAUDE.md stays in sync with your actual project

Quick Start

npx dotclaudemd init

This auto-detects your project stack and generates a CLAUDE.md from the best matching template. Works for any language — Node.js, Python, Java, Go, Rust, Ruby, PHP, and more.

Installation

Requires Node.js >= 20 — but your project can be any language. dotclaudemd is a scaffolding tool that runs once to generate a file; it doesn't become a project dependency.

For Node.js / JavaScript / TypeScript projects

You already have Node — just run directly:

# No install needed
npx dotclaudemd init

# Or install globally
npm install -g dotclaudemd

# Or as a dev dependency (for CI lint/doctor checks)
npm install -D dotclaudemd

If installed as a dev dependency, add to your package.json scripts:

{
  "scripts": {
    "claude:lint": "dotclaudemd lint",
    "claude:doctor": "dotclaudemd doctor"
  }
}

For Python, Go, Rust, Java, Ruby, PHP, and other projects

Node.js is only needed to run the CLI — it's not a project dependency. Think of it like using npx to run Prettier on a Python repo, or using pip to install pre-commit in a Java project. Many developer tools are language-agnostic.

Option 1: Use npx (if Node.js is already installed)

Most developers already have Node.js on their machine. Check with node -v.

# One-time scaffold — no install needed
npx dotclaudemd init

# Periodic health checks
npx dotclaudemd lint
npx dotclaudemd doctor

Option 2: Install Node.js just for this

If you don't have Node.js, install it temporarily:

# macOS (Homebrew)
brew install node

# Ubuntu/Debian
sudo apt install nodejs npm

# Fedora
sudo dnf install nodejs npm

# Or use a version manager (nvm, fnm, volta)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 20

# Then run
npx dotclaudemd init

Option 3: Install globally (recommended for non-Node projects)

Install once, use everywhere — no npx prefix needed:

npm install -g dotclaudemd

# Now use directly in any project
cd ~/my-python-project && dotclaudemd init
cd ~/my-go-project && dotclaudemd init
cd ~/my-rust-project && dotclaudemd init

Note: dotclaudemd does not add any files to your project besides CLAUDE.md. It reads your project's manifest files (pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile, composer.json) but never modifies them.

Commands

dotclaudemd init

Scaffold a CLAUDE.md from a template. Auto-detects your project stack and prompts you for template variables (styling, database, framework options, etc).

# Auto-detect stack, interactive prompts
dotclaudemd init

# Use a specific template by name
dotclaudemd init --stack nextjs-typescript

# Write to ~/.claude/CLAUDE.md (global instructions for all projects)
dotclaudemd init --global

# Use all defaults without prompting (great for CI)
dotclaudemd init --no-interactive

# Overwrite an existing CLAUDE.md without confirmation
dotclaudemd init --force

# Combine flags
dotclaudemd init --stack rails --no-interactive --force

How detection works: The CLI looks at your project root for manifest files (package.json, Cargo.toml, go.mod, pom.xml, Gemfile, composer.json, pyproject.toml) and their contents (dependencies, lock files) to suggest the best matching template.

dotclaudemd lint [file]

Lint a CLAUDE.md for common anti-patterns that waste context window tokens or confuse Claude.

# Lint CLAUDE.md in current project
dotclaudemd lint

# Lint a specific file
dotclaudemd lint path/to/CLAUDE.md

# Machine-readable JSON output
dotclaudemd lint --json

Returns exit code 1 if errors are found (useful for CI).

Lint Rules:

Rule Severity What it catches
line-count warn / error >80 lines (warn), >150 lines (error) — large files eat into Claude's context window
has-commands warn No build, test, or dev commands found — Claude needs these to help you build and test
no-personality warn "Be a senior engineer", "act as an expert" — persona instructions waste tokens and don't improve output
no-at-file-refs warn @docs/api.md patterns that embed entire files into context
no-negative-only warn "Never use X" without "prefer Y instead" — Claude works better with positive guidance
stale-file-refs warn File paths like src/old-module.ts that no longer exist in your project
no-unicode-bullets info Unicode bullet characters instead of markdown - lists
no-placeholder-vars error Unreplaced {{variable}} placeholders from template rendering

Example output:

Linting CLAUDE.md

  ⚠  line-count: File is 95 lines. Consider trimming to under 80 lines to save context window.
  ⚠  no-personality: Line 3: Avoid persona instructions like "act as". They waste tokens.
  ⚠  stale-file-refs: Line 12: Referenced path "src/old-module.ts" does not exist.

  1 file linted: 0 errors, 3 warnings, 0 info

dotclaudemd doctor

Check your CLAUDE.md freshness against your actual project state. Catches drift between what your CLAUDE.md says and what your project actually has.

# Run all health checks
dotclaudemd doctor

# Machine-readable JSON output (includes freshness score)
dotclaudemd doctor --json

Health Checks:

Check What it verifies
scripts-exist Commands like npm run build actually exist in package.json scripts
deps-mentioned Major production dependencies are mentioned somewhere in CLAUDE.md
file-refs-valid File paths like src/utils/helpers.ts actually exist on disk
node-version-match The Node version stated in CLAUDE.md matches .nvmrc / .node-version
test-framework-match The test framework mentioned (jest, vitest, etc.) matches what's in devDependencies
package-manager-match The package manager stated (npm, pnpm, yarn) matches your lockfile

Freshness Score: Doctor computes a 0-100% freshness score based on check results:

  • 80-100% (green) — CLAUDE.md is up to date
  • 50-79% (yellow) — Some things are stale, consider updating
  • 0-49% (red) — CLAUDE.md is significantly out of sync

dotclaudemd browse

Browse and preview all available templates before choosing one.

# Interactive browser — select category, then template, then preview
dotclaudemd browse

# Non-interactive: list all templates
dotclaudemd browse --list

# Filter by language category
dotclaudemd browse --category python
dotclaudemd browse --category javascript
dotclaudemd browse --category java

Templates

19 templates across 8 categories. Each template includes project-specific commands, architecture layout, and coding conventions.

JavaScript / TypeScript

Template Description Key Variables
nextjs-typescript Next.js App Router with TypeScript src_dir (src/app), styling (Tailwind/CSS Modules/styled-components)
nextjs-prisma-tailwind Full-stack Next.js with Prisma + Tailwind src_dir, db (PostgreSQL/MySQL/SQLite)
react-vite React SPA with Vite styling (Tailwind/CSS Modules/vanilla), state (Zustand/Redux/Context)
express-mongodb Express.js REST API with MongoDB auth (JWT/Passport/None)
mern-stack Full-stack MERN application styling, state
node-cli-tool Node.js CLI with TypeScript cli_framework (Commander/yargs/Clipanion), package_manager
sveltekit SvelteKit with TypeScript styling (Tailwind/vanilla), adapter (auto/node/static/vercel)
astro Astro content site styling, ui_framework (React/Vue/Svelte/None)
vue-nuxt Vue 3 SPA or Nuxt 3 variant (Nuxt 3/Vue 3 SPA), styling, state_management (Pinia/None)
typescript-monorepo Turborepo or Nx monorepo monorepo_tool (Turborepo/Nx), package_manager (pnpm/npm/yarn)

Python

Template Description Key Variables
fastapi-sqlalchemy FastAPI with SQLAlchemy ORM db_type (PostgreSQL/MySQL/SQLite), package_manager (pip/poetry/uv)
django-rest Django REST Framework db_type, package_manager
flask-basic Flask web application db_type, package_manager

Java

Template Description Key Variables
springboot Spring Boot REST API build_tool (Maven/Gradle), db (PostgreSQL/MySQL/H2), java_version (21/17)

Go

Template Description Key Variables
go-api Go REST API router (net/http/Chi/Gin/Echo), db_type (PostgreSQL/SQLite/None)

Rust

Template Description Key Variables
cargo-workspace Rust Cargo workspace project_type (Binary/Library/Both)

Ruby

Template Description Key Variables
rails Ruby on Rails api_only (Yes/No), db (PostgreSQL/MySQL/SQLite)

PHP

Template Description Key Variables
laravel Laravel PHP application db (MySQL/PostgreSQL/SQLite)

Global

Template Description Key Variables
default Generic template for any project project_name, language

Use Cases

1. Starting a new project

You just ran create-next-app or rails new and want to add a CLAUDE.md immediately:

cd my-new-project
npx dotclaudemd init

The CLI auto-detects your stack, suggests the best template, and prompts you for project-specific options (styling, database, etc).

2. Adding CLAUDE.md to an existing project

Your team has been working on a project for months but never created a CLAUDE.md:

cd existing-project
npx dotclaudemd init

Same flow — it reads your package.json (or pom.xml, Gemfile, etc.) and generates a CLAUDE.md that already knows your dependencies and project structure.

3. Setting up global Claude instructions

Want Claude to follow certain conventions across all your projects:

npx dotclaudemd init --global

This writes to ~/.claude/CLAUDE.md, which Claude reads for every project you open.

4. CI/CD: Linting CLAUDE.md in pull requests

Add a lint check to your CI pipeline to catch CLAUDE.md anti-patterns before they get merged:

npx dotclaudemd lint --json

Returns exit code 1 on errors. Add to your CI config:

# GitHub Actions example
- name: Lint CLAUDE.md
  run: npx dotclaudemd lint

Or in package.json:

{
  "scripts": {
    "lint:claude": "dotclaudemd lint"
  }
}

5. Catching stale CLAUDE.md after refactoring

You refactored your project — renamed directories, swapped test frameworks, added new dependencies. Your CLAUDE.md is now out of date:

npx dotclaudemd doctor

Doctor checks whether the commands, file paths, and dependencies mentioned in your CLAUDE.md still match your actual project. It reports a freshness score and tells you exactly what's stale.

6. Browsing templates before choosing

Not sure which template fits your project? Browse them interactively:

npx dotclaudemd browse

Or list everything non-interactively:

npx dotclaudemd browse --list
npx dotclaudemd browse --category python

7. Scaffolding for a specific stack (non-interactive)

You know exactly which template you want and don't need prompts:

npx dotclaudemd init --stack fastapi-sqlalchemy --no-interactive --force

This uses all default variable values and overwrites any existing CLAUDE.md.

8. Onboarding new team members

New developer joins the team? The CLAUDE.md already documents:

  • How to build, test, and run the project
  • Project architecture and key directories
  • Coding conventions and patterns to follow

Generate it once, commit it, and every developer (and Claude) benefits.

9. Monorepo setup

For Turborepo or Nx monorepos:

npx dotclaudemd init --stack typescript-monorepo

The template covers workspace commands, package boundaries, and shared config conventions.

10. Non-JavaScript projects (Python, Go, Rust, Java, Ruby, PHP)

dotclaudemd works for any language. It reads your project's manifest files — not just package.json:

# Python project with pyproject.toml
cd my-fastapi-app && npx dotclaudemd init
# → detects FastAPI, suggests fastapi-sqlalchemy template

# Java project with pom.xml
cd my-spring-app && npx dotclaudemd init
# → detects Spring Boot, suggests springboot template

# Go project with go.mod
cd my-go-api && npx dotclaudemd init
# → detects Go + router, suggests go-api template

# Ruby project with Gemfile
cd my-rails-app && npx dotclaudemd init
# → detects Rails, suggests rails template

# Rust project with Cargo.toml
cd my-rust-project && npx dotclaudemd init
# → detects Rust, suggests cargo-workspace template

# PHP project with composer.json
cd my-laravel-app && npx dotclaudemd init
# → detects Laravel, suggests laravel template

The CLI only needs Node.js to run — it doesn't add any Node files to your project. The only output is a CLAUDE.md file.

11. Multi-language project

Your project root has both package.json and pom.xml? The detector picks the primary stack. You can always override:

npx dotclaudemd init --stack springboot

Auto-Detection

The CLI detects your project stack by examining files in your project root:

File Detected Language Frameworks Detected
package.json JavaScript/TypeScript Next.js, SvelteKit, Astro, Nuxt, Vue, Express, React, MERN
turbo.json / nx.json JavaScript/TypeScript Turborepo, Nx (monorepo)
pyproject.toml / requirements.txt Python FastAPI, Django, Flask
Cargo.toml Rust Actix, Axum, Rocket
go.mod Go Gin, Fiber, Chi, Echo
pom.xml / build.gradle Java Spring Boot
Gemfile Ruby Rails
composer.json PHP Laravel

It also detects:

  • Package managers: npm, pnpm, yarn, bun, poetry, pipenv, uv, pip, cargo, go, maven, gradle, bundler, composer
  • Test frameworks: vitest, jest, mocha, pytest
  • Lock files: package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb, poetry.lock, Pipfile.lock, uv.lock

Contributing

See CONTRIBUTING.md for how to add templates and contribute.

Adding a Template

Templates live in templates/{category}/{name}.md with YAML frontmatter:

---
name: my-template
displayName: My Template
description: Short description
category: javascript
tags: [javascript, typescript, myframework]
variables:
  - name: styling
    prompt: "Styling solution?"
    options: [Tailwind CSS, vanilla CSS]
    default: Tailwind CSS
detects:
  files: [package.json]
  dependencies: [my-framework]
priority: 10
---

# Project

My project using {{styling}}.

## Commands
...

Variables use {{double_braces}} for substitution. The detects field enables auto-suggestion when the CLI finds matching files or dependencies.

License

MIT

About

CLAUDE.md Template Registry CLI - scaffold, lint, and health-check your CLAUDE.md files

Topics

cli template ai scaffold developer-tools claude claude-code claudemd

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

4 tags

Packages

 
 
 

Contributors

Languages