Project Instructions Development

Manages the complete lifecycle of project instructions: creating initial documentation, syncing with codebase patterns, and organizing modular rules.

When to Use This Skill

Use when:

• "Create CLAUDE.md for this project"
• "Initialize CLAUDE.md" or "generate CLAUDE.md"
• "Sync CLAUDE.md with my code"
• "Update documentation from codebase"
• "Extract patterns from code"
• "Create .claude/rules/ structure"
• "Split large CLAUDE.md"
• "Manage modular documentation"

What This Skill Does

Provides 4 main operations:

• ✅ Initialize: Create new CLAUDE.md with opinionated baseline standards
• ✅ Sync: Analyze codebase and update documentation with detected patterns
• ✅ Organize: Create or manage .claude/rules/ modular structure
• ✅ Split: Break large CLAUDE.md into focused rule files

Note: .claude/rules/ only works in project directories, not in global ~/.claude/

CRITICAL RULES

Language

• CLAUDE.md MUST be 100% in English (industry standard)
• Never mix languages in documentation
• Code, comments, and docs all in English

No Dynamic Data

• NEVER include: line counts, file counts, commit statistics, dates, timestamps
• NEVER write: "Analyzed X files", "Y lines of code", "Created on..."
• Only include: stable patterns, timeless structures, architectural principles

User Confirmation

• ALWAYS ask questions to understand context and preferences
• ALWAYS show preview before writing any files
• ALWAYS get explicit confirmation before creating/modifying files

Instructions

Step 0: Check Global Configuration (CRITICAL)

Before creating any project-level documentation, ALWAYS read the user's global CLAUDE.md:

# Check if global CLAUDE.md exists
~/.claude/CLAUDE.md

If it exists:

• Read and analyze what rules are already defined globally
• DO NOT duplicate global rules in project CLAUDE.md
• Only add project-specific patterns that differ from or extend global rules
• Mention to user: "I found your global CLAUDE.md - I'll only add project-specific rules"

If it doesn't exist:

• Proceed normally with project documentation

Step 1: Determine Operation and Complexity

Use AskUserQuestion tool with THREE questions:

{
  "questions": [
    {
      "question": "What do you need help with?",
      "header": "Operation",
      "multiSelect": false,
      "options": [
        {
          "label": "Create new CLAUDE.md",
          "description": "Start from scratch with opinionated baseline"
        },
        {
          "label": "Sync CLAUDE.md with existing code",
          "description": "Analyze codebase to detect patterns and update docs"
        },
        {
          "label": "Split large CLAUDE.md into rules/",
          "description": "Break CLAUDE.md (>500 lines) into focused files"
        }
      ]
    },
    {
      "question": "What complexity level?",
      "header": "Structure",
      "multiSelect": false,
      "options": [
        {
          "label": "Simple (just CLAUDE.md)",
          "description": "Single file, good for small/medium projects"
        },
        {
          "label": "Modular (CLAUDE.md + .claude/rules/)",
          "description": "Multiple files with path patterns, for large projects"
        }
      ]
    },
    {
      "question": "Should this be shared with your team or kept local?",
      "header": "Sharing",
      "multiSelect": false,
      "options": [
        {
          "label": "Shared (CLAUDE.md)",
          "description": "Committed to git, shared across team and sessions"
        },
        {
          "label": "Local only (CLAUDE.local.md)",
          "description": "Git-ignored, personal workspace rules only"
        }
      ]
    }
  ]
}

Route to workflow:

• Create new + Simple + Shared → Initialize Workflow (Step 2) - CLAUDE.md
• Create new + Simple + Local → Initialize Workflow (Step 2) - CLAUDE.local.md + add to .gitignore
• Create new + Modular + Shared → Initialize Workflow (Step 2) + Organize Workflow (Step 4) - CLAUDE.md
• Create new + Modular + Local → Initialize Workflow (Step 2) + Organize Workflow (Step 4) - CLAUDE.local.md + add to .gitignore
• Sync + Simple + Shared → Sync Workflow (Step 3) - update CLAUDE.md
• Sync + Simple + Local → Sync Workflow (Step 3) - update CLAUDE.local.md
• Sync + Modular → Sync Workflow (Step 3) + Organize Workflow (Step 4)
• Split → Split Workflow (Step 5)

Step 2: Initialize Workflow (Create New CLAUDE.md)

Create opinionated baseline CLAUDE.md for new projects.

Process:

1. Determine filename (from Step 1 answer):

- Shared → CLAUDE.md - Local only → CLAUDE.local.md

1. Detect project type

- Check if it's a code project (package.json, requirements.txt, go.mod, etc.) - Or non-code (docs, notes, research, etc.) - Ask user if unclear

1. Think through design:

- Minimum viable CLAUDE.md? - Similar projects/patterns? - Architectural trade-offs? - Common pitfalls in this stack?

1. Show preview with:

- Structure outline - Key sections - Estimated line count - Architecture reasoning - Filename that will be created

1. Generate and write (after confirmation):

- Single file: ~150-250 lines - Modular: ~100-150 lines with references to rules/ - Use determined filename from step 1

1. If local only (CLAUDE.local.md):

- Add CLAUDE.local.md to .gitignore - Create .gitignore if it doesn't exist - Inform user it's git-ignored

1. Inform user with next steps

See references/initialize-workflow.md for complete details

Step 3: Sync Workflow (Analyze Code and Update Docs)

Analyze codebase to extract patterns and update documentation.

Process:

1. Detect current setup:

- Check if CLAUDE.md exists - Check if .claude/rules/ exists - Determine mode: CREATE, UPDATE Single, UPDATE Modular

1. Analyze codebase (use Task tool with Explore agent):

- Main source directory - Tech stack - Folder organization - Test patterns

1. Extract patterns:

- Naming conventions (files, functions, variables) - Architectural pattern (FSD, Feature-First, etc.) - Import patterns - Testing conventions - Component/API patterns

1. Think through findings:

- Stable (>80%) vs emerging patterns - What to document vs leave implicit - Single file or modular approach

1. Show findings to user:

- Detected patterns - Mismatches with documented patterns - Recommendations

1. Ask approach (AskUserQuestion):

- Update CLAUDE.md (single file) - Create .claude/rules/ (modular) - Show both options

1. Generate updates and write (after confirmation)

1. Inform user with summary of changes

See references/sync-workflow.md for complete details

Step 4: Organize Workflow (Create .claude/rules/ Structure)

Set up modular documentation with focused rule files.

Process:

1. Detect stack (same as initialize)

1. Ask which rules to create (AskUserQuestion):

- coding-standards.md (recommended) - architecture.md (recommended) - testing.md - api.md

1. Think through design:

- What in each file vs CLAUDE.md - Path patterns for each file - Keep each file <200 lines

1. Show preview:

- File structure - Estimated line counts - Path patterns - CLAUDE.md updates

1. Create files (after confirmation):

- Create .claude/rules/ directory - Create each rule file with YAML frontmatter - Update CLAUDE.md to reference rules

1. Inform user with structure overview

See references/organize-and-split-workflows.md for templates and details

Step 5: Split Workflow (Break Large CLAUDE.md)

Break CLAUDE.md (>500 lines) into focused modular files.

Process:

1. Read and analyze CLAUDE.md:

- Identify sections - Core vs detailed content - Line counts per section

1. Think through split strategy:

- What stays in CLAUDE.md (core standards) - What moves to rules/ (detailed guidelines) - Organize by topic - Path patterns

1. Show split preview:

- Current vs after structure - What moves where - Line count reduction

1. Execute split (after confirmation):

- Create .claude/rules/ - Create rule files with moved content - Update CLAUDE.md (remove moved, add references)

1. Inform user with results

See references/organize-and-split-workflows.md for complete details

Architecture Pattern Selection

Quick reference:

See references/architecture-patterns.md for complete guide

Path Pattern Examples

# Coding standards for TypeScript
---
paths: src/**/*.{ts,tsx}
---

# Testing conventions
---
paths: **/*.{test,spec}.*
---

# API-specific rules
---
paths: src/{api,routes}/**/*
---

Related Settings Configuration

respectGitignore

Control whether @-mention file picker respects .gitignore:

{
  "respectGitignore": true
}

Add to .claude/settings.json (project-specific) or ~/.claude/settings.json (global).

Use when: You want file suggestions to exclude gitignored files

fileSuggestion

Customize @ file search commands:

{
  "fileSuggestion": {
    "command": "rg --files",
    "timeout": 5000
  }
}

Use when:

• You want faster file search than default
• You need custom filtering logic
• You have specific tooling (e.g., fd, find with custom flags)

These settings affect how documentation discovery and file reference tools work.

Best Practices

1. ✅ Ask questions first - Understand user needs
2. ✅ Show previews - Confirm before writing
3. ✅ English only - 100% English content
4. ✅ No dynamic data - Only stable patterns
5. ✅ Opinionated defaults - But let user choose
6. ✅ Explain choices - Why this architecture?
7. ✅ Keep concise - CLAUDE.md 150-250 lines, rules <200 lines
8. ✅ Think step-by-step - Analyze before generating
9. ✅ Progressive disclosure - Core in CLAUDE.md, details in rules/

Anti-Patterns

• ❌ Generating without asking questions
• ❌ Writing files without preview/confirmation
• ❌ Including line counts, file counts, dates, statistics
• ❌ Mixed languages (English + other)
• ❌ "Analyzed X files" or dynamic statements
• ❌ Timestamps or "last updated"
• ❌ Overly long files (>500 lines CLAUDE.md, >200 lines rules)
• ❌ Not explaining architectural choices
• ❌ Duplicating content between CLAUDE.md and rules/

Additional Resources

Reference Files

Complete workflows and detailed guides:

• references/initialize-workflow.md - Creating new CLAUDE.md from scratch
• references/sync-workflow.md - Analyzing code and extracting patterns
• references/organize-and-split-workflows.md - Managing .claude/rules/ structure
• references/modular-organization.md - Modular documentation guide
• references/architecture-patterns.md - Complete architecture pattern guide

Examples

Study these as templates:

• examples/minimal-claude-md.md - Single file example (~200 lines)
• examples/modular-setup/ - Complete modular structure

- CLAUDE.md (minimal core) - .claude/rules/coding-standards.md - .claude/rules/architecture.md

Quick Decision Trees

Which Approach?

Project size?
├─ <10k lines → Single file CLAUDE.md
└─ >10k lines → Modular with .claude/rules/

Different rules for different areas?
├─ Yes → Modular (use path patterns)
└─ No → Single file

Which Operation?

Have documentation?
├─ No → Initialize workflow
└─ Yes → Is it outdated?
    ├─ Yes → Sync workflow
    └─ No → Is it >500 lines?
        ├─ Yes → Split workflow
        └─ No → Organize workflow (if want modular)

Which Architecture?

Type of project?
├─ Frontend SPA (React/Vue)
│   ├─ Large (>50k lines) → FSD
│   └─ Medium → Feature-First
├─ Backend API
│   ├─ Go/Java/C# → Package by Feature
│   ├─ Express/Flask/FastAPI → Feature-First
│   └─ Django/Rails → MVC
└─ Unsure → Ask user preferences

Output Examples

Initialize (Single File):

• New CLAUDE.md: 150-250 lines
• English, opinionated baseline
• Core standards + Architecture + Git

Initialize (Modular):

• Minimal CLAUDE.md: 100-150 lines
• Note to run organize workflow next

Sync:

• Updated CLAUDE.md with detected patterns
• Or created/updated .claude/rules/ files
• Summary of changes

Organize:

• .claude/rules/ structure
• Focused files (<200 lines each)
• Updated CLAUDE.md with references

Split:

• Reduced CLAUDE.md (~100-150 lines)
• New .claude/rules/ files
• Better organization

All outputs: 100% English, no dynamic data, user-confirmed, ready to use