dev-specs（开发规格）

/dev-specs - Implementation Specifications

Skill Awareness: See skills/_registry.md for all available skills. - Before: Ensure /debrief completed (BRD exists) - Auto: Runs /dev-scout if scout.md missing - After: Use /dev-coding for implementation

Generate precise implementation plans from BRD use cases. Creates per-UC specs with shared components.

When to Use

• After /debrief created BRD use cases
• After /dev-scout {feature} analyzed codebase
• Before starting implementation
• When onboarding engineers to a feature

Usage

/dev-specs auth                              # Generate specs for auth feature
/dev-specs auth UC-AUTH-001                  # Single use case only
/dev-specs billing --api=swagger.json        # With API spec file
/dev-specs payments --schema=schema.prisma   # With DB schema

Prerequisites

Before running, ensure:

1. plans/brd/ exists with use cases
2. plans/features/{feature}/ exists

Note: Scout is auto-triggered if missing (see Phase 0).

Input Files

The skill can accept additional context files:

Output Structure

plans/features/{feature}/
├── README.md              # Feature overview
├── scout.md               # From /dev-scout
│
└── specs/
    ├── README.md          # Index, implementation order, dependencies
    │
    ├── shared/            # Shared across all UCs
    │   ├── data-model.md  # Schema changes, entities
    │   ├── patterns.md    # Code patterns, conventions
    │   └── security.md    # Auth, validation, permissions
    │
    ├── UC-XXX-001-{slug}/ # Per use case
    │   ├── README.md      # Implementation plan
    │   ├── changes.md     # Files to create/modify
    │   └── tests.md       # Test cases
    │
    └── UC-XXX-002-{slug}/
        └── ...

Workflow

Phase 0: Check Dependencies & Graph Context

Before generating specs, verify prerequisites and gather context:

1. Check: plans/brd/ exists?
   → No: Error "Run /debrief first"

2. Check: plans/features/{feature}/ exists?
   → No: Error "Feature not found in BRD"

3. Check: plans/features/{feature}/scout.md exists?
   → No: Auto-run scout (see below)

4. Read: plans/docs-graph.json
   → Get related nodes and dependencies

Auto-Scout Logic:

If scout.md doesn't exist:

1. Notify user: "No scout found for {feature}, running analysis..."
2. Execute scout workflow (medium mode) for the feature
3. Save to plans/features/{feature}/scout.md
4. Continue to Phase 1

Docs-Graph Integration:

Read plans/docs-graph.json to understand:

Example graph query for /dev-specs auth:

{
  "feature": "auth",
  "use_cases": ["uc-auth-001", "uc-auth-002", "uc-auth-003"],
  "existing_specs": [],
  "dependencies": {
    "uc-auth-002": ["uc-auth-001"],  // Signup depends on Login
    "uc-auth-003": ["uc-auth-001"]   // Forgot depends on Login
  },
  "cross_feature": ["feature-billing"]  // Auth linked from billing
}

This informs:

• Implementation order (Login first, then Signup/Forgot)
• Shared components (auth patterns used by billing)
• What specs are already done vs. needed

Phase 1: Gather Context

1. Read BRD use cases for the feature

- plans/brd/use-cases/UC-{GROUP}-*.md - Extract acceptance criteria, business rules

1. Read feature scout (if exists)

- plans/features/{feature}/scout.md - Understand existing implementation

1. Read additional inputs (if provided)

- API specs → Extract endpoints, contracts - DB schema → Understand data model - Design docs → UI requirements

1. Ask clarifying questions using AskUserQuestion:

Q1: Implementation Scope

• Backend only
• Frontend only
• Full-stack
• API/Service only
• Mobile app

Q2: Additional Context (multi-select)

• Have API specs (Swagger/OpenAPI/GraphQL)
• Have DB schema file
• Have design files/links
• Have existing documentation
• None

Q3: Testing Approach

• Unit tests only
• Unit + Integration
• Unit + Integration + E2E
• No tests (docs only)

Phase 2: Analyze Impact

For each use case:

1. What's new? - Files/components to create
2. What changes? - Existing files to modify
3. What's shared? - Reusable across UCs
4. Dependencies? - What must exist first

Create impact summary:

## Impact Analysis

| UC | New Files | Modified | Dependencies |
|----|-----------|----------|--------------|
| UC-AUTH-001 | 5 | 2 | shared/data-model |
| UC-AUTH-002 | 3 | 1 | UC-AUTH-001 |

Phase 3: Generate Shared Specs

Create specs/shared/ files:

data-model.md:

# Data Model

## New Entities

### User
| Field | Type | Notes |
|-------|------|-------|
| id | uuid | PK |
| email | string | Unique |
| passwordHash | string | bcrypt |

## Schema Changes

-- Migration: add_users_table CREATE TABLE users ( id UUID PRIMARY KEY, email VARCHAR(255) UNIQUE NOT NULL, ... );

## Relationships

{Describe entity relationships}

patterns.md:

# Implementation Patterns

## Code Style
- Follow existing patterns from scout
- {Specific conventions}

## Error Handling
- {How to handle errors}
- {User feedback patterns}

## API Patterns (if applicable)
- {Request/response format}
- {Authentication headers}

## State Management (if applicable)
- {State patterns}
- {Data fetching}

security.md:

# Security Considerations

## Authentication
- {How auth works}

## Authorization
- {Permission model}

## Data Validation
- {Input validation rules}

## Sensitive Data
- {What to protect, how}

Phase 4: Generate UC Specs

For each use case, create folder with:

README.md (Implementation Plan):

# UC-{GROUP}-{NNN}: {Title}

> **Feature**: [[feature-{feature}]]
> **BRD**: [[uc-{group}-{nnn}]]
> **Status**: Draft

## Overview
{What this UC implements}

## Business Requirements
{From BRD - acceptance criteria}

## Current State
{From scout - what exists}

## Implementation Plan

### 1. {Step 1}
- {Detail}
- {Detail}

### 2. {Step 2}
- {Detail}

## API Contract (if applicable)

### {Method} {Endpoint}

**Request:**

{ "field": "type" }

**Response:**

{ "field": "type" }

**Errors:**

| Code | Reason |
| --- | --- |
| 400 | Invalid input |
| 401 | Unauthorized |

## UI Components (if applicable)

| Component | Purpose | Props |
| --- | --- | --- |
| {Name} | {Purpose} | {Key props} |

## Edge Cases

- {Edge case 1}
- {Edge case 2}

## Dependencies

- {What must exist first}

## Acceptance Mapping

| BRD Criteria | Implementation |
| --- | --- |
| Given X, When Y, Then Z | {How implemented} |

changes.md:

# File Changes

## New Files

| File | Purpose |
|------|---------|
| `src/api/auth/login.ts` | Login endpoint |
| `src/components/LoginForm.tsx` | Login form UI |

## Modified Files

| File | Change |
|------|--------|
| `src/lib/auth.ts` | Add login function |
| `prisma/schema.prisma` | Add User model |

## File Tree Preview

src/ ├── api/ │ └── auth/ │ └── login.ts # NEW ├── components/ │ └── auth/ │ └── LoginForm.tsx # NEW └── lib/ └── auth.ts # MODIFIED

tests.md:

# Test Plan

## Unit Tests

| Test | File | Description |
|------|------|-------------|
| Login validation | `login.test.ts` | Validate email/password |
| Token generation | `auth.test.ts` | JWT token creation |

## Integration Tests

| Test | Description |
|------|-------------|
| Login flow | POST /api/auth/login with valid creds |
| Invalid login | POST /api/auth/login with wrong password |

## E2E Tests (if applicable)

| Scenario | Steps |
|----------|-------|
| User login | Navigate to /login, enter creds, verify redirect |

## Test Data

{ "validUser": { "email": "test@example.com", "password": "TestPass123!" } }

## Coverage Target

- Unit: 80%+
- Integration: Key paths
- E2E: Happy path + critical errors

Phase 5: Generate Specs Index

Create specs/README.md:

# {Feature} - Implementation Specs

> **Feature**: [[feature-{feature}]]
> **Generated**: {date}
> **Use Cases**: {count}

## Overview
{Brief description of the feature implementation}

## Implementation Order

| Order | UC | Title | Depends On | Estimate |
|-------|-----|-------|------------|----------|
| 1 | [[uc-auth-001]] | Login | shared/* | - |
| 2 | [[uc-auth-002]] | Signup | [[uc-auth-001]] | - |
| 3 | [[uc-auth-003]] | Forgot Password | [[uc-auth-001]] | - |

## Shared Specs
- [Data Model](./shared/data-model.md)
- [Patterns](./shared/patterns.md)
- [Security](./shared/security.md)

## Dependencies Graph

flowchart TD shared[shared/*] --> UC001[UC-AUTH-001] UC001 --> UC002[UC-AUTH-002] UC001 --> UC003[UC-AUTH-003]

## Summary

| Metric | Count |
| --- | --- |
| Total Use Cases | {n} |
| New Files | {n} |
| Modified Files | {n} |
| Tests | {n} |

## Notes

{Any implementation notes, risks, considerations}

Phase 6: Summary

Output:

• Specs created
• Use cases covered
• Files that will change
• Dependencies identified
• Next steps

Tools Used

Integration with Other Skills

Tips

• Run /dev-scout {feature} first for better context
• Provide API specs when available for accurate contracts
• Keep each UC spec focused - one job per UC
• Estimates are left blank for team to fill

References

• references/spec-templates.md - Template structures
• references/checklist.md - Spec completeness checklist