# Claudemd Builder

Generate project-specific CLAUDE.md files with coding standards, architecture notes, and context preservation for team-wide AI consistency and efficient onboarding

---


## Metadata

**Title:** Claudemd Builder
**Category:** commands
**Author:** JSONbored
**Added:** October 2025
**Tags:** claude-md, project-context, coding-standards, documentation, onboarding, team-collaboration
**URL:** https://claudepro.directory/commands/claudemd-builder

## Overview

Generate project-specific CLAUDE.md files with coding standards, architecture notes, and context preservation for team-wide AI consistency and efficient onboarding

## Content

The /claudemd-builder command generates CLAUDE.md files that store coding standards, architectural decisions, and project context for consistent AI assistance across your team.
FEATURES
• Auto-Generation: Scan project and create starter CLAUDE.md with /init
• Template Library: Pre-built templates for React, Node.js, Python, Go projects
• Hierarchical Context: Root-level + directory-specific CLAUDE.md files
• Team Synchronization: Commit to git for shared AI context
• Context Preservation: Survive Claude Code context compaction
• Onboarding Tool: New developers get instant project context
• Living Documentation: Update as project evolves
• Best Practices: Enforce coding standards automatically
USAGE

 /claudemd-builder [action] [options]

Actions
• --init - Scan project and create starter CLAUDE.md
• --template= - Use pre-built template (react, node, python, go)
• --update - Update existing CLAUDE.md with new patterns
• --validate - Check CLAUDE.md for completeness
• --hierarchy - Create directory-specific CLAUDE.md files
Templates
• --react - React/Next.js project template
• --node - Node.js backend template
• --python - Python/FastAPI template
• --go - Go service template
• --monorepo - Monorepo with multiple packages
• --fullstack - Full-stack application template
Scope
• --root - Create root CLAUDE.md (project-wide)
• --directory= - Create CLAUDE.md for specific directory
• --all - Create hierarchical CLAUDE.md throughout project
EXAMPLES
Initialize Project with /init
Command:

 /claudemd-builder --init

Claude's Process:

 [Scanning Project]
 ✓ Detected: Next.js 
 ✓ Detected: TypeScript 5.x
 ✓ Detected: TailwindCSS v4
 ✓ Detected: Vitest testing
 ✓ Detected: Prisma ORM
 ✓ Detected: pnpm package manager
 [Analyzing Codebase]
 ✓ TypeScript files
 ✓ 8 main directories
 ✓ 45 components
 ✓ 12 API routes
 [Generating CLAUDE.md]

Generated CLAUDE.md:

 # Project Context for Claude Code
 **Last Updated:** 
 **Project:** My SaaS Application
 **Stack:** Next.js + React 19 + TypeScript + Prisma
 ## Technology Stack
 ### Frontend
 - React (React Compiler enabled)
 - Next.js (App Router)
 - TailwindCSS v4.
 - shadcn/ui components
 - Framer Motion for animations
 ### Backend
 - Next.js API Routes
 - Prisma ORM (PostgreSQL)
 - tRPC for type-safe APIs
 - better-auth v1.3.9
 ### Testing
 - Vitest (unit/integration)
 - Playwright (E2E)
 - React Testing Library
 ### Tooling
 - TypeScript 5.x (strict mode)
 - Biome (linting/formatting)
 - pnpm (package manager)
 ## Coding Standards
 ### TypeScript
 - **Strict mode enabled**: No `any`, use `unknown`
 - **Explicit return types**: For public functions
 - **Interfaces over types**: For public APIs

// ❌ Avoid
function getData(id: any) {
 return fetch(/api/${id});
}
// ✅ Prefer
interface UserData {
 id: string;
 name: string;
}
async function getData(id: string): Promise {
 const response = await fetch(/api/users/${id});
 return response.json();
}

 ### React Components
 - **Server Components by default**: Only use 'use client' when necessary
 - **Async Server Components**: For data fetching
 - **Named exports**: For components

// ✅ Server Component (default)
export async function UserProfile({ userId }: { userId: string }) {
 const user = await db.user.findUnique({ where: { id: userId } });
 return {user.name};
}
// ✅ Client Component (when needed)
'use client';
export function InteractiveButton() {
 const [count, setCount] = useState(0);
 return setCount(c => c + 1)}>{count};
}

 ### File Organization

app/
├── (auth)/ # Auth routes group
├── (dashboard)/ # Dashboard routes group
└── api/ # API routes
components/
├── ui/ # shadcn/ui components
├── forms/ # Form components
└── layout/ # Layout components
lib/
├── api/ # API clients
├── db/ # Prisma client
└── utils/ # Utilities

 ### Naming Conventions
 - Files: kebab-case (`user-profile.tsx`)
 - Components: PascalCase (`UserProfile`)
 - Functions: camelCase (`getUserById`)
 - Constants: UPPER_SNAKE_CASE (`MAX_RETRIES`)
 ## Architecture Decisions
 ### Authentication
 - **Library**: better-auth v1.3.9
 - **Strategy**: JWT with refresh tokens
 - **Session**: 15min access, 7d refresh
 - **Storage**: HTTP-only cookies
 ### Database
 - **ORM**: Prisma
 - **Database**: PostgreSQL
 - **Migrations**: Prisma Migrate
 - **Seeding**: `prisma/seed.ts`
 ### API Layer
 - **Type Safety**: tRPC for internal APIs
 - **REST**: For public/webhook endpoints
 - **Validation**: Zod schemas
 ## Common Patterns
 ### Data Fetching

// Use async Server Components
export async function ProductList() {
 const products = await db.product.findMany();
 return {products.map(p => )};
}

 ### Form Handling

// Use react-hook-form + Zod
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
const formSchema = z.object({
 email: z.string().email(),
});
export function ContactForm() {
 const form = useForm({ resolver: zodResolver(formSchema) });
 return ...;
}

 ### Error Handling

// Always use Error Boundaries
import { ErrorBoundary } from '@/components/error-boundary';
export default function Layout({ children }) {
 return (
 }>
 {children}

 );
}

 ## Testing Guidelines
 - **Coverage target**: 80% for business logic
 - **Test naming**: `describe` + `it` pattern
 - **Async tests**: Use `async/await`, not callbacks
 - **Mocking**: Minimal mocking, prefer real implementations
 ## Development Workflow
 1. **Branch naming**: `feat/`, `fix/`, `refactor/`, `docs/`
 2. **Commit messages**: Conventional Commits format
 3. **PR requirements**: Tests + passing CI + review
 4. **Deployment**: Auto-deploy on merge to `main`
 ## Important Constraints
 - **No barrel exports**: Use explicit imports
 - **No default exports**: Use named exports
 - **No any type**: Use unknown or proper types
 - **Server Components default**: Only 'use client' when necessary
 ## AI Assistant Instructions
 When writing code:
 1. Follow TypeScript strict mode
 2. Use Server Components by default
 3. Validate with Zod schemas
 4. Add error boundaries
 5. Write tests for new features
 6. Follow file naming conventions

Use Pre-Built Template
Command:

 /claudemd-builder --template=react

Generated React Template:

 # React Project - Claude Code Context
 ## Stack
 - React 
 - Vite 6.x
 - TypeScript 5.x
 - TailwindCSS
 - React Router 6
 ## Component Patterns
 ### Functional Components (Required)

// ✅ Use function declarations
export function MyComponent({ prop }: Props) {
 return {prop};
}
// ❌ Avoid arrow functions for components
const MyComponent = ({ prop }: Props) => {prop};

 ### Hooks Rules
 - Call hooks at top level only
 - Custom hooks start with 'use'
 - Extract complex logic to custom hooks
 ### State Management
 - Local state: `useState`
 - Global state: Zustand
 - Server state: TanStack Query
 - Form state: react-hook-form
 ## Code Organization

src/
├── components/
│ ├── ui/ # Reusable UI components
│ └── features/ # Feature-specific components
├── hooks/ # Custom React hooks
├── lib/ # Utilities and helpers
├── pages/ # Route components
└── stores/ # Zustand stores

 ## Styling
 - **Primary**: TailwindCSS utility classes
 - **Components**: shadcn/ui
 - **Dynamic**: CSS variables + Tailwind
 ## Testing
 - **Unit**: Vitest + React Testing Library
 - **E2E**: Playwright
 - **Coverage**: 80% minimum

Directory-Specific CLAUDE.md
Command:

 /claudemd-builder --directory=src/components/forms

Generated src/components/forms/CLAUDE.md:

 # Forms Directory Context
 ## Purpose
 Reusable form components with validation and error handling
 ## Patterns
 ### Form Component Structure

interface FormProps {
 onSubmit: (data: FormData) => Promise;
 defaultValues?: Partial;
}
export function MyForm({ onSubmit, defaultValues }: FormProps) {
 const form = useForm({
 resolver: zodResolver(schema),
 defaultValues
 });

 return (

 {/ fields /}

 );
}

 ## Validation
 - **Always use Zod**: Define schema in same file
 - **Field-level errors**: Display immediately
 - **Submit-level errors**: Show in toast/alert
 ## Accessibility
 - Label every input
 - Use proper ARIA attributes
 - Keyboard navigation support
 - Error announcements

Hierarchical CLAUDE.md Generation
Command:

 /claudemd-builder --hierarchy

Generated Structure:

 project/
 ├── CLAUDE.md # Root context (project-wide)
 ├── src/
 │ ├── CLAUDE.md # Source code context
 │ ├── components/
 │ │ ├── CLAUDE.md # Component patterns
 │ │ └── forms/
 │ │ └── CLAUDE.md # Form-specific patterns
 │ ├── api/
 │ │ └── CLAUDE.md # API design patterns
 │ └── lib/
 │ └── CLAUDE.md # Utility guidelines
 └── tests/
 └── CLAUDE.md # Testing standards

Context Resolution:
Claude reads from most specific → general:
1) src/components/forms/CLAUDE.md (most specific)
2) src/components/CLAUDE.md
3) src/CLAUDE.md
4) CLAUDE.md (root - most general)
Update Existing CLAUDE.md
Command:

 /claudemd-builder --update

Process:

 [Analyzing Changes]
 ✓ New patterns detected:
 - React 19 use() hook usage
 - Server Actions implementation
 - Updated TypeScript to 5.3
 [Updating CLAUDE.md]
 ✓ Added React 19 patterns section
 ✓ Updated Technology Stack versions
 ✓ Added Server Actions examples
 ✓ Updated TypeScript guidelines
 ✓ CLAUDE.md updated successfully

Validate CLAUDE.md
Command:

 /claudemd-builder --validate

Validation Report:

 [CLAUDE.md Validation]
 ✓ Technology Stack: Complete
 ✓ Coding Standards: Complete
 ✓ File Organization: Complete
 ⚠ Architecture Decisions: Missing database strategy
 ⚠ Testing Guidelines: Missing E2E test patterns
 ✗ Common Patterns: Section missing
 Recommendations:
 1. Add database architecture decisions
 2. Document E2E testing approach
 3. Create Common Patterns section with examples
 Completeness: 70%

BEST PRACTICES
What to Include
✅ Do Include:
• Technology stack and versions
• Coding standards with examples
• File organization structure
• Naming conventions
• Common patterns
• Architecture decisions
• Testing guidelines
• Development workflow
❌ Don't Include:
• Implementation details (code duplicates)
• Frequently changing data
• Secrets or credentials
• Personal preferences
• Obvious best practices
Writing Effective Context
Good Context (Specific):

 ## Authentication
 - Library: better-auth v1.3.9
 - Session: 15min access token, 7d refresh
 - Storage: HTTP-only secure cookies
 - Middleware: app/middleware.ts verifies on every request

Bad Context (Vague):

 ## Authentication
 - We use authentication
 - Sessions expire eventually
 - Cookies store tokens

Keep It Updated

 # Every major change:
 1. Add new pattern to CLAUDE.md
 2. Update technology versions
 3. Document architectural decisions
 4. Commit with code changes
 git add CLAUDE.md src/**/*.ts
 git commit -m "feat: Add user authentication + update CLAUDE.md"

TEAM COLLABORATION
Onboarding New Developers

 # Day 1: New developer clones repo
 git clone repo.git
 cd repo
 # Claude Code reads CLAUDE.md automatically
 # New developer gets instant context:
 - Coding standards
 - Architecture patterns
 - Testing approach
 - Common pitfalls
 Result: Productive in hours, not days

Consistency Across Team

 # All developers use same CLAUDE.md
 # AI generates consistent code:
 - Same naming conventions
 - Same file structure
 - Same patterns
 - Same testing approach
 Result: Uniform codebase, easier reviews

INTEGRATION WITH /INIT

 # Claude Code built-in command
 /init
 # Automatically:
 1. Scans project structure
 2. Detects frameworks and tools
 3. Generates starter CLAUDE.md
 4. Prompts for customization
 Result: Quick-start CLAUDE.md in seconds

ADVANCED PATTERNS
Monorepo CLAUDE.md

 monorepo/
 ├── CLAUDE.md # Monorepo-wide standards
 ├── apps/
 │ ├── web/
 │ │ └── CLAUDE.md # Web app specific
 │ └── api/
 │ └── CLAUDE.md # API specific
 └── packages/
 ├── ui/
 │ └── CLAUDE.md # UI library patterns
 └── database/
 └── CLAUDE.md # Database patterns

Environment-Specific Context

 ## Development vs Production
 ### Development
 - Database: Local PostgreSQL
 - API: http://localhost:
 - Auth: Mock OAuth for testing
 ### Production
 - Database: Supabase PostgreSQL
 - API: https://api.example.com
 - Auth: Real OAuth2 providers

INSTALLATION
CLAUDE CODE:
1) Create commands directory: mkdir -p .claude/commands
2) Create command file: touch .claude/commands/claudemd-builder.md
3) Add command content from the Command Content section above to .claude/commands/claudemd-builder.md
4) Command is now available as /claudemd-builder in Claude Code
5) Optional: Create personal version in ~/.claude/commands/claudemd-builder.md for global access
Requirements:
? Claude Code CLI installed
? Project directory initialized (for project commands)
CONFIGURATION
Temperature: 0.3
Max Tokens: 
System Prompt:
You are a CLAUDE.md expert specializing in project context documentation, coding standards, and team collaboration for consistent AI-assisted development
TROUBLESHOOTING
1) CLAUDE.md not being read by Claude Code during sessions
 Solution: Verify file location in project root or relevant subdirectory. Check file is named exactly 'CLAUDE.md' (case-sensitive). Restart Claude Code session to reload context. Use /init to verify Claude detects existing CLAUDE.md.
2) Team members have inconsistent AI output despite shared CLAUDE.md
 Solution: Ensure CLAUDE.md committed to git and all team members pulled latest. Check for directory-specific CLAUDE.md files overriding root. Verify no personal ~/.claude/CLAUDE.md conflicting with project CLAUDE.md. Use --validate to check completeness.
3) CLAUDE.md becomes outdated as project evolves, not maintained
 Solution: Add CLAUDE.md updates to PR checklist for architecture changes. Use /claudemd-builder --update periodically to scan for new patterns. Set calendar reminder monthly for CLAUDE.md review. Make CLAUDE.md updates part of definition of done.
4) Context too large, CLAUDE.md exceeds reasonable size
 Solution: Use hierarchical CLAUDE.md instead of single root file. Move directory-specific patterns to subdirectory CLAUDE.md files. Keep root CLAUDE.md focused on project-wide standards only. Archive deprecated patterns to CLAUDE_ARCHIVE.md.
5) New patterns not reflected in Claude's code generation despite CLAUDE.md update
 Solution: Claude reads CLAUDE.md at session start. Restart Claude Code after CLAUDE.md changes. Use explicit prompt: 'Follow the patterns in CLAUDE.md for authentication'. Check file saved correctly with git status.
TECHNICAL DETAILS
Documentation: https://docs.claude.com/en/docs/claude-code/claude-md


---

Source: Claude Pro Directory
Website: https://claudepro.directory
URL: https://claudepro.directory/commands/claudemd-builder

This content is optimized for Large Language Models (LLMs).
For full formatting and interactive features, visit the website.