SDD Custom Steering Document Creation

Create specialized steering documents that provide context-specific guidance beyond the standard product/tech/structure documents.

When to Use Custom Steering

Custom steering is useful for:

• Domain-specific rules: API design, database conventions
• File-type guidance: Test patterns, component standards
• Workflow processes: PR reviews, deployment procedures
• Team conventions: Code review standards, documentation rules

Inclusion Modes

Custom steering documents can be loaded in three ways:

Mode	Behavior	Use Case
ALWAYS	Loaded in every AI interaction	Core conventions, critical rules
CONDITIONAL	Loaded when file patterns match	Test-specific, API-specific rules
MANUAL	Referenced with @filename.md	Rarely needed, specialized contexts

Workflow

Step 1: Identify the Need

Ask yourself:

• What specialized context is missing?
• When should this guidance apply?
• Is this project-wide or context-specific?

Step 2: Choose Inclusion Mode

Is this guidance ALWAYS relevant?
├── YES → Use ALWAYS mode
│
└── NO → Is it relevant for specific file types?
         ├── YES → Use CONDITIONAL mode with patterns
         │         Examples: *.test.ts, src/api/**/*
         │
         └── NO → Use MANUAL mode
                  Reference with @filename.md when needed

Step 3: Create Document

Save to .spec/steering/{filename}.md:

# {Topic Name}

## Purpose
{Why this steering document exists}

## Scope
{When this guidance applies}

## Guidelines

### Guideline 1: {Name}
{Detailed guidance}

**Do:**
- {Good practice}

**Don't:**
- {Anti-pattern}

### Guideline 2: {Name}
{Detailed guidance}

## Examples

### Good Example
```{language}
{Code showing good practice}

Bad Example

// DON'T: {explanation}
{Code showing anti-pattern}

Checklist

• {Verification item 1}
• {Verification item 2}

---

Inclusion Mode: {ALWAYS | CONDITIONAL | MANUAL} File Patterns: {patterns for CONDITIONAL mode} Created: {date}

## Common Custom Steering Documents

### API Design Standards
```markdown
# API Design Standards

## Inclusion
Mode: CONDITIONAL
Patterns: src/api/**/*.ts, src/routes/**/*.ts

## Guidelines

### RESTful Conventions
- Use plural nouns for resources: `/users`, not `/user`
- Use HTTP methods correctly: GET (read), POST (create), PUT (update), DELETE (remove)
- Return appropriate status codes

### Request/Response Format
- Use JSON for request/response bodies
- Include `Content-Type: application/json` header
- Wrap responses in consistent envelope

Test Patterns

# Test Patterns

## Inclusion
Mode: CONDITIONAL
Patterns: **/*.test.ts, **/*.spec.ts

## Guidelines

### Arrange-Act-Assert
Every test should follow:
1. **Arrange**: Set up test data and mocks
2. **Act**: Execute the code under test
3. **Assert**: Verify the results

### Naming Convention
`describe('{Class/Function}', () => {`
`  it('should {expected behavior} when {condition}', () => {`

Component Standards

# Component Standards

## Inclusion
Mode: CONDITIONAL
Patterns: src/components/**/*.tsx

## Guidelines

### Component Structure
1. Imports (external, internal, types)
2. Type definitions
3. Component function
4. Helper functions
5. Exports

Database Conventions

# Database Conventions

## Inclusion
Mode: CONDITIONAL
Patterns: src/db/**/*.ts, **/migrations/**/*

## Guidelines

### Table Naming
- Use snake_case: `user_accounts`
- Use plural: `orders`, not `order`
- Prefix with domain: `auth_sessions`

### Column Naming
- Use snake_case: `created_at`
- Foreign keys: `{table}_id`
- Booleans: `is_active`, `has_access`

File Pattern Syntax

Patterns use glob syntax:

Pattern	Matches
*.test.ts	All test files in current dir
**/*.test.ts	All test files recursively
src/api/**/*	All files in api directory tree
*.{ts,tsx}	TypeScript and TSX files
!node_modules/**	Exclude node_modules

MCP Tool Integration

Custom steering documents are managed manually. After creating:

1. Save to .spec/steering/{name}.md
2. Verify file patterns work as expected
3. Reference in AGENTS.md/CLAUDE.md if needed

Quality Checklist

• Purpose is clearly stated
• Inclusion mode is appropriate
• File patterns are specific (for CONDITIONAL)
• Guidelines are actionable
• Examples show good and bad practices
• Checklist for verification included