claude-skill-vue-development

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Vue Development Plugin for Claude Code

A comprehensive, test-driven Vue 3 development skill that enforces modern best practices with 100% compliance under pressure.

**Now available as a Claude Code plugin!** See [PLUGIN-README.md](https://github.com/alexanderop/claude-skill-vue-development/blob/HEAD/PLUGIN-README.md) for installation and usage instructions.

## Overview

This skill teaches Claude agents to write production-quality Vue 3 code using:
- **TypeScript-first** patterns (no runtime validation)
- **Modern Composition API** (defineModel, not manual props)
- **User-behavior testing** (Testing Library, not implementation details)
- **Clean composables** (single responsibility, no UI logic)

## Plugin Structure

```
.claude-plugin/
├── plugin.json (Plugin manifest)
├── marketplace.json (Marketplace configuration)
└── skills/
    └── vue-development/
        ├── SKILL.md (1,216 words)
        │   ├── Red flags (12 anti-patterns)
        │   ├── Quick rules (components, testing, routing, composables)
        │   ├── Essential patterns with examples
        │   ├── Rationalization table (11 excuses countered)
        │   └── Quick checklists (4 domains)
        └── references/
            ├── component-patterns.md (616 words)
            ├── composable-patterns.md (1,848 words)
            ├── routing-patterns.md (589 words)
            ├── testing-composables.md (1,627 words)
            └── testing-patterns.md (785 words)

Total: 6,681 words (1,216 main + 5,465 references)
```

**Legacy Structure:** The original skill files remain in `.claude/skills/vue/` for backward compatibility during migration.

## What It Covers

### Components (`component-patterns.md`)
- Props: `defineProps<{ }>()` with TypeScript, no `const` unless needed
- Emits: `const emit = defineEmits<{ event: [args] }>()`
- V-model: `defineModel<type>()` (NOT manual modelValue)
- Templates: `:prop` shorthand, `#slot` shorthand, explicit `<template>` tags
- Naming: PascalCase or kebab-case, general → specific

### Composables (`composable-patterns.md`)
- Naming: `useFeatureName.ts` with PascalCase
- Structure: Primary state → Metadata → Methods
- Single responsibility principle
- Error exposure (no console.error only)
- NO UI logic (toasts/alerts belong in components)
- Functional core, imperative shell pattern

### Testing Components (`testing-patterns.md`)
- PRIMARY: `@testing-library/vue` for user behavior
- API mocking: MSW (`msw`)
- NEVER: `setTimeout()` in tests, testing internal state
- Async: `findBy*` queries or `waitFor()`
- Query priority: accessibility > test IDs

### Testing Composables (`testing-composables.md`)
- **Independent composables**: Test directly (no lifecycle/inject)
- **Dependent composables**: Use `withSetup` helper (lifecycle hooks)
- **Inject composables**: Use `useInjectedSetup` helper (provide/inject)
- Patterns for async, localStorage, document title, etc.

### Routing (`routing-patterns.md`)
- File-based routing with unplugin-vue-router
- AVOID: `index.vue` → use route groups `(name).vue`
- Explicit params: `[userId]` not `[id]`
- Navigation: Named routes with typed params
- Route guards and meta fields

## Effectiveness

### Before Skill: 37.5% compliance
- Props: 0/3 correct (used const unnecessarily, runtime validation)
- Emits: 0/1 correct (array syntax, no types)
- V-model: 0/1 correct (manual modelValue)
- Testing: 3/4 correct (rejected setTimeout but missed Testing Library)

### After Skill: 100% compliance
- Props: ✅ TypeScript generics, no const when unused
- Emits: ✅ Typed event signatures
- V-model: ✅ defineModel() usage
- Testing: ✅ Proper async, no setTimeout
- Composables: ✅ Correct naming, structure, error handling

**Improvement: 167% increase**

## Key Features

### Red Flags (Auto-Detection)
Agents STOP when they catch themselves:
- "For speed" / "quick demo" → shortcuts
- Manual modelValue → use defineModel()
- setTimeout() in tests → proper async
- UI logic in composables → expose error state
- Generic `[id]` params → explicit names

### Rationalization Table
Counters 11 common excuses:
- "TypeScript is too verbose" → It's actually LESS code
- "We can clean it up later" → Write it right the first time
- "Composables can show toasts" → UI belongs in components
- "counter.ts is fine" → Must use 'use' prefix

### Reference Architecture
Heavy content loads on-demand:
- Components → 616 words
- Composables → 1,848 words
- Routing → 589 words
- Testing (components) → 785 words
- Testing (composables) → 1,627 words

Main skill stays small (1,216 words) for fast initial load.

## Installation

### As a Plugin (Recommended)

See [PLUGIN-README.md](https://github.com/alexanderop/claude-skill-vue-development/blob/HEAD/PLUGIN-README.md) for detailed installation instructions.

**Quick Start:**

```bash
# Add the marketplace
/plugin marketplace add alexanderop/claude-skill-vue-development

# Install the plugin
/plugin install vue-development@vue-development-marketplace
```

### Legacy Installation (Direct Skill)

1. Place skill files in `.claude/skills/vue/`
2. The skill auto-loads when:
   - Creating Vue 3 components
   - Implementing v-model
   - Defining props/emits
   - Setting up routes
   - Writing Vue tests
   - Creating composables

Or invoke manually:
```
Skill: vue-development
```

## Testing Methodology

Created using **Test-Driven Development for Documentation**:

1. **RED Phase**: Created 8 pressure scenarios, ran baseline tests without skill
2. **GREEN Phase**: Wrote minimal skill addressing observed failures
3. **REFACTOR Phase**: Closed loopholes, achieved 100% compliance

All rationalizations captured from real agent behavior under:
- Time pressure ("ASAP", "ship tonight")
- Authority pressure ("just make it work")
- Exhaustion pressure ("debugging for 2 hours")
- Confusion pressure ("I think I need to...")

## Documentation

- `SKILL-CREATION-SUMMARY.md` - TDD methodology and results
- `OPTIMIZATION-SUMMARY.md` - Reference architecture details
- `FINAL-STATUS.md` - Complete status and metrics
- `test-scenarios/` - All baseline and with-skill test results

## Usage Examples

### Component Creation
**Without skill:** Used runtime validation, `const props =` unnecessarily, no emits types
**With skill:** TypeScript generics, correct const usage, fully typed emits

### V-Model Implementation
**Without skill:** Manual modelValue prop + update:modelValue emit
**With skill:** `defineModel<string>()` for clean two-way binding

### Testing
**Without skill:** setTimeout(1000), testing internal state
**With skill:** findBy* queries, user-visible behavior only

### Composables
**Without skill:** UI logic in composables, missing 'use' prefix, console.error only
**With skill:** Proper naming, error exposure, no UI logic, single responsibility

## Requirements

- Vue 3.4+ (for defineModel)
- TypeScript
- Vitest (recommended for testing)
- @testing-library/vue
- msw (for API mocking)
- unplugin-vue-router (for file-based routing)

## Contributing

The skill enforces best practices from:
- Official Vue 3 documentation
- Vue Composition API RFC
- Testing Library principles
- Kent C. Dodds testing philosophy
- Community best practices from alexop.dev

## Status

✅ **PRODUCTION-READY**

- 100% compliance rate in testing
- 25% smaller main file (1,216 vs original 1,618 words)
- 312% more comprehensive (6,681 total words)
- Tested under multiple pressure scenarios
- Zero new rationalizations after optimization

## License

Created following Claude Code superpowers methodology.

Vue Development Plugin for Claude Code

A comprehensive, test-driven Vue 3 development skill that enforces modern best practices with 100% compliance under pressure.

Now available as a Claude Code plugin! See PLUGIN-README.md for installation and usage instructions.

Overview

This skill teaches Claude agents to write production-quality Vue 3 code using:

TypeScript-first patterns (no runtime validation)
Modern Composition API (defineModel, not manual props)
User-behavior testing (Testing Library, not implementation details)
Clean composables (single responsibility, no UI logic)

Plugin Structure

.claude-plugin/
├── plugin.json (Plugin manifest)
├── marketplace.json (Marketplace configuration)
└── skills/
    └── vue-development/
        ├── SKILL.md (1,216 words)
        │   ├── Red flags (12 anti-patterns)
        │   ├── Quick rules (components, testing, routing, composables)
        │   ├── Essential patterns with examples
        │   ├── Rationalization table (11 excuses countered)
        │   └── Quick checklists (4 domains)
        └── references/
            ├── component-patterns.md (616 words)
            ├── composable-patterns.md (1,848 words)
            ├── routing-patterns.md (589 words)
            ├── testing-composables.md (1,627 words)
            └── testing-patterns.md (785 words)

Total: 6,681 words (1,216 main + 5,465 references)

Legacy Structure: The original skill files remain in .claude/skills/vue/ for backward compatibility during migration.

What It Covers

Components (`component-patterns.md`)

Props: defineProps<{ }>() with TypeScript, no const unless needed
Emits: const emit = defineEmits<{ event: [args] }>()
V-model: defineModel<type>() (NOT manual modelValue)
Templates: :prop shorthand, #slot shorthand, explicit <template> tags
Naming: PascalCase or kebab-case, general → specific

Composables (`composable-patterns.md`)

Naming: useFeatureName.ts with PascalCase
Structure: Primary state → Metadata → Methods
Single responsibility principle
Error exposure (no console.error only)
NO UI logic (toasts/alerts belong in components)
Functional core, imperative shell pattern

Testing Components (`testing-patterns.md`)

PRIMARY: @testing-library/vue for user behavior
API mocking: MSW (msw)
NEVER: setTimeout() in tests, testing internal state
Async: findBy* queries or waitFor()
Query priority: accessibility > test IDs

Testing Composables (`testing-composables.md`)

Independent composables: Test directly (no lifecycle/inject)
Dependent composables: Use withSetup helper (lifecycle hooks)
Inject composables: Use useInjectedSetup helper (provide/inject)
Patterns for async, localStorage, document title, etc.

Routing (`routing-patterns.md`)

File-based routing with unplugin-vue-router
AVOID: index.vue → use route groups (name).vue
Explicit params: [userId] not [id]
Navigation: Named routes with typed params
Route guards and meta fields

Effectiveness

Before Skill: 37.5% compliance

Props: 0/3 correct (used const unnecessarily, runtime validation)
Emits: 0/1 correct (array syntax, no types)
V-model: 0/1 correct (manual modelValue)
Testing: 3/4 correct (rejected setTimeout but missed Testing Library)

After Skill: 100% compliance

Props: ✅ TypeScript generics, no const when unused
Emits: ✅ Typed event signatures
V-model: ✅ defineModel() usage
Testing: ✅ Proper async, no setTimeout
Composables: ✅ Correct naming, structure, error handling

Improvement: 167% increase

Key Features

Red Flags (Auto-Detection)

Agents STOP when they catch themselves:

"For speed" / "quick demo" → shortcuts
Manual modelValue → use defineModel()
setTimeout() in tests → proper async
UI logic in composables → expose error state
Generic [id] params → explicit names

Rationalization Table

Counters 11 common excuses:

"TypeScript is too verbose" → It's actually LESS code
"We can clean it up later" → Write it right the first time
"Composables can show toasts" → UI belongs in components
"counter.ts is fine" → Must use 'use' prefix

Reference Architecture

Heavy content loads on-demand:

Components → 616 words
Composables → 1,848 words
Routing → 589 words
Testing (components) → 785 words
Testing (composables) → 1,627 words

Main skill stays small (1,216 words) for fast initial load.

Installation

As a Plugin (Recommended)

See PLUGIN-README.md for detailed installation instructions.

Quick Start:

# Add the marketplace
/plugin marketplace add alexanderop/claude-skill-vue-development

# Install the plugin
/plugin install vue-development@vue-development-marketplace

Legacy Installation (Direct Skill)

Place skill files in .claude/skills/vue/
The skill auto-loads when:
- Creating Vue 3 components
- Implementing v-model
- Defining props/emits
- Setting up routes
- Writing Vue tests
- Creating composables

Or invoke manually:

Skill: vue-development

Testing Methodology

Created using Test-Driven Development for Documentation:

RED Phase: Created 8 pressure scenarios, ran baseline tests without skill
GREEN Phase: Wrote minimal skill addressing observed failures
REFACTOR Phase: Closed loopholes, achieved 100% compliance

All rationalizations captured from real agent behavior under:

Time pressure ("ASAP", "ship tonight")
Authority pressure ("just make it work")
Exhaustion pressure ("debugging for 2 hours")
Confusion pressure ("I think I need to...")

Documentation

SKILL-CREATION-SUMMARY.md - TDD methodology and results
OPTIMIZATION-SUMMARY.md - Reference architecture details
FINAL-STATUS.md - Complete status and metrics
test-scenarios/ - All baseline and with-skill test results

Usage Examples

Component Creation

Without skill: Used runtime validation, const props = unnecessarily, no emits types With skill: TypeScript generics, correct const usage, fully typed emits

V-Model Implementation

Without skill: Manual modelValue prop + update:modelValue emit With skill: defineModel<string>() for clean two-way binding

Testing

Without skill: setTimeout(1000), testing internal state With skill: findBy* queries, user-visible behavior only

Composables

Without skill: UI logic in composables, missing 'use' prefix, console.error only With skill: Proper naming, error exposure, no UI logic, single responsibility

Requirements

Vue 3.4+ (for defineModel)
TypeScript
Vitest (recommended for testing)
@testing-library/vue
msw (for API mocking)
unplugin-vue-router (for file-based routing)

Contributing

The skill enforces best practices from:

Official Vue 3 documentation
Vue Composition API RFC
Testing Library principles
Kent C. Dodds testing philosophy
Community best practices from alexop.dev

Status

✅ PRODUCTION-READY

100% compliance rate in testing
25% smaller main file (1,216 vs original 1,618 words)
312% more comprehensive (6,681 total words)
Tested under multiple pressure scenarios
Zero new rationalizations after optimization

License

Created following Claude Code superpowers methodology.