instructions-development

name

instructions-development

description

This skill should be used when the user asks to "create CLAUDE.md", "initialize CLAUDE.md", "sync CLAUDE.md with code", "update documentation from codebase", "create .claude/rules/", "manage modular rules", "split large CLAUDE.md", or mentions project documentation setup. Manages complete lifecycle of project instructions including creation, synchronization with code patterns, and modular organization.

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

2. 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

3. Think through design:

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

4. Show preview with:

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

5. Generate and write (after confirmation):

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

6. 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

7. 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

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

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

3. Extract patterns:

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

4. Think through findings:

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

5. Show findings to user:

   • Detected patterns
   • Mismatches with documented patterns
   • Recommendations

6. Ask approach (AskUserQuestion):

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

7. Generate updates and write (after confirmation)

8. 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)

2. Ask which rules to create (AskUserQuestion):

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

3. Think through design:

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

4. Show preview:

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

5. Create files (after confirmation):

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

6. 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

2. Think through split strategy:

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

3. Show split preview:

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

4. Execute split (after confirmation):

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

5. Inform user with results

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

---

Architecture Pattern Selection

Quick reference:

Stack	Recommended Pattern
React/Vue SPA	Feature-Sliced Design (FSD)
Next.js	FSD or Feature-First
Express/Fastify	Feature-First
NestJS	Feature-First
Django/Flask	MVC
Rails	MVC
Spring Boot	Package by Feature
Go API	Package by Feature

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