sdd-steering

SDD Steering Document Generation

Generate project-specific steering documents that provide context and guidance for AI-assisted development.

What Are Steering Documents?

Steering documents are markdown files in .spec/steering/ that provide project-specific context to guide AI interactions. They describe YOUR project's unique characteristics.

Document Types

Document	Purpose	Content
product.md	Product context	Vision, users, features, goals
tech.md	Technology stack	Languages, frameworks, tools, architecture
structure.md	Project conventions	Directory structure, naming, patterns
custom-*.md	Custom guidance	Specialized rules for specific contexts

Workflow

Step 1: Analyze Project

Gather information from:

1. Project manifest - Dependencies and metadata (e.g., package.json, Cargo.toml, pyproject.toml, pom.xml, go.mod)
2. Directory structure - Folder organization
3. Existing code patterns - Naming conventions, architecture
4. Documentation - README, existing docs
5. Build configuration - Build tools, scripts, CI/CD

Step 2: Generate Product Steering

Create .spec/steering/product.md:

# Product Overview

## Description
{Project description from manifest or analysis}

## Vision
{Long-term product vision}

## Target Users
- **Primary:** {Main user persona}
- **Secondary:** {Other user types}

## Core Features
1. {Feature 1} - {Brief description}
2. {Feature 2} - {Brief description}

## Key Value Propositions
- {Value 1}
- {Value 2}

## Success Metrics
- {Metric 1}: {Target}
- {Metric 2}: {Target}

Step 3: Generate Tech Steering

Create .spec/steering/tech.md:

# Technology Overview

## Stack

### Language
- **Primary:** {e.g., TypeScript, Python, Go, Rust, Java}
- **Version:** {e.g., 5.x, 3.11, 1.21}
- **Runtime:** {if applicable, e.g., Node.js, JVM, .NET}

### Frameworks
- {Framework 1}: {Purpose}
- {Framework 2}: {Purpose}

### Key Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| {dep1} | {version} | {why used} |

## Architecture

### Pattern
{e.g., Clean Architecture, MVC, Microservices, Hexagonal}

### Layers

┌─────────────────┐ │ Presentation │ Controllers, CLI, UI ├─────────────────┤ │ Application │ Services, Use Cases ├─────────────────┤ │ Domain │ Entities, Business Logic ├─────────────────┤ │ Infrastructure │ Database, External APIs └─────────────────┘

## Development Environment

### Prerequisites
- {Language runtime and version}
- {Package manager} (e.g., npm, pip, cargo, go mod, maven)

### Setup
```bash
# Clone and install dependencies
{package manager install command}

# Run development server
{dev server command}

Common Commands

Command	Purpose
{install}	Install dependencies
{dev}	Development server
{build}	Production build
{test}	Run tests
{lint}	Code linting

Quality Standards

• Test coverage: >= 80%
• Linting: {language-appropriate linter}
• Type checking: {if applicable}

### Step 4: Generate Structure Steering

Create `.spec/steering/structure.md`:

```markdown
# Project Structure

## Directory Layout

project-root/ ├── src/ # Source code │ ├── domain/ # Business logic │ ├── application/ # Use cases │ ├── infrastructure/ # External adapters │ └── {entry point} # Main entry point ├── tests/ # Test files ├── docs/ # Documentation └── {project manifest} # Dependencies/config

## Naming Conventions

### Files
| Type | Convention | Example |
|------|------------|---------|
| Components | {project convention} | `UserProfile.{ext}` |
| Services | {project convention} | `AuthService.{ext}` |
| Utilities | {project convention} | `format_date.{ext}` |
| Tests | {test convention} | `auth_test.{ext}` |
| Types/Interfaces | {project convention} | `user_types.{ext}` |

### Code
| Element | Convention | Example |
|---------|------------|---------|
| Classes/Types | PascalCase | `UserService` |
| Functions/Methods | {language convention} | `get_user_by_id` or `getUserById` |
| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
| Variables | {language convention} | `user_name` or `userName` |
| Interfaces | {project convention} | `UserRepository` or `IUserRepository` |

## Module Organization

### Import Order
1. Standard library / built-ins
2. External packages / dependencies
3. Internal modules (absolute paths)
4. Relative imports
5. Type/interface imports (if language separates them)

### Export Pattern
- Use barrel exports / index files where appropriate
- Named exports preferred over default (language-dependent)
- Public API exposed from domain layer

## Patterns

### Dependency Injection
{DI approach used, e.g., Inversify, manual}

### Error Handling
{Error handling pattern, e.g., Result types, exceptions}

### Logging
{Logging approach, e.g., structured logging}

Step 5: Create Directory

Ensure .spec/steering/ directory exists and save documents.

MCP Tool Integration

This skill generates documents manually. For automated analysis, the sdd-init MCP tool creates basic steering during project initialization.

Quality Checklist

• Product description is clear and specific
• Target users are well-defined
• Technology stack is accurately documented
• Directory structure matches actual project
• Naming conventions are consistent
• Development setup instructions are complete
• Key patterns are documented

Notes

• Steering documents are project-specific - they describe YOUR project
• Keep them updated as the project evolves
• Use custom steering for domain-specific rules
• Reference from AGENTS.md or CLAUDE.md in project root