instructions-development

What this skill does

# 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:**

```bash
# 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:

```json
{
  "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 count