Skip to main content

Best Practices Guide

Essential patterns for effective SpecifyX usage in development workflows.

Project Organization​

Directory Structure​

my-project/
├── .specify/               # SpecifyX configuration
│   ├── config.toml        # Project settings
│   ├── scripts/           # Python utilities
│   └── templates/         # Custom templates
├── .claude/commands/      # AI assistant commands  
├── specs/                 # Feature specifications
│   └── 001-user-auth/     # Spec directories
└── src/                   # Implementation code

Naming Conventions​

Branch Names: Use descriptive patterns matching your team's conventions:

# .specify/config.toml
[branching]
patterns = [
    "feature/{feature-name}",
    "hotfix/{bug-id}",
    "chore/{task-name}"
]

Specification IDs: Use numeric prefixes for ordered development:

001-user-authentication/
002-payment-integration/
003-admin-dashboard/

Configuration Management​

Global Configuration​

Place team-wide settings in ~/.config/specifyx/config.toml:

[defaults]
ai_assistant = "claude"

[branching]
patterns = ["feature/{feature-name}", "main"]
validation_rules = ["lowercase_only", "no_spaces"]

Project Configuration​

Override globals in .specify/config.toml:

[project]
name = "my-app"
description = "Project description"

[branching]
patterns = ["feature/{feature-name}", "hotfix/{bug-id}", "main"]

Specification Writing​

Structure Template​

# Feature Name

## Overview
Brief description and business value.

## User Stories
- As a [user type], I want [goal] so that [benefit]

## Acceptance Criteria
- [ ] Specific testable requirements
- [ ] Error handling scenarios
- [ ] Performance requirements

## Technical Notes
- Architecture decisions
- Dependencies
- Constraints

Writing Guidelines​

  • Be specific: Avoid vague requirements
  • Include examples: Show expected inputs/outputs
  • Define edge cases: Handle error scenarios
  • Keep updated: Sync specs with implementation changes

Development Workflow​

Choosing Your Workflow​

SpecifyX supports multiple development workflows to match your team's preferences:

Best for teams with parallel feature development:

  1. Create feature branch: specifyx run create-feature "feature name"
  2. Write specification: Complete spec.md before coding
  3. Implement feature: Use generated scripts and templates
  4. Update documentation: Keep specs current with changes
  5. Clean merge: Ensure branch is ready for integration

Single-Branch Development (No Branching)​

Perfect for small teams or solo developers who prefer simplicity:

  1. Create specification: specifyx run create-feature "feature name" --no-branch
  2. Work on current branch: Develop directly on main/master
  3. Commit frequently: Make small, incremental commits
  4. Update specs: Keep specifications current with implementation

Use no-branch workflow when:

  • Working solo or in very small teams (2-3 people)
  • Rapid prototyping or exploration projects
  • Simple applications with minimal feature complexity
  • Teams practicing trunk-based development
  • Projects with infrequent releases

Template Customization​

  • Start small: Modify existing templates before creating new ones
  • Test templates: Verify Jinja2 syntax and variable substitution
  • Document changes: Add comments explaining custom logic
  • Version control: Track template changes with project

Workflow Selection​

SpecifyX supports multiple development workflows to match your team's preferences:

Best for teams with parallel feature development:

  1. Create feature branch: specifyx run create-feature "User authentication"
    • Creates branch: feature/user-authentication
    • Creates directory: specs/001-feature-user-authentication/
  2. Setup planning: specifyx run setup-plan setup (auto-detects from branch)
  3. Generate tasks: specifyx run generate-tasks (auto-detects from branch)
  4. Implement feature: Use generated scripts and templates
  5. Merge when complete: Ensure branch is ready for integration

Single-Branch Development (No Branching)​

Perfect for small teams or solo developers who prefer simplicity:

  1. Create specification: specifyx run create-feature "User authentication system" --no-branch
    • Creates meaningful directory: specs/001-user-authentication-system/
    • Stays on current branch (main)
  2. Setup planning: specifyx run setup-plan setup --spec-id 001
  3. Generate tasks: specifyx run generate-tasks --spec-id 001
  4. Work on current branch: Develop directly on main/master
  5. Commit frequently: Make small, incremental commits

When to Use No-Branch Workflow:​

  • Working solo or in very small teams (2-3 people)
  • Rapid prototyping or exploration projects
  • Simple applications with minimal feature complexity
  • Teams practicing trunk-based development
  • Projects with infrequent releases

Error Handling in No-Branch Workflow:​

When multiple specs exist, commands provide helpful guidance:

❯ specifyx run setup-plan setup
Multiple specs available on main branch. Specify which one to use:
  specifyx run setup-plan --spec-id 001
  specifyx run setup-plan --spec-id 002

Available specs:
  001 - user-authentication-system
  002 - payment-integration

Team Collaboration​

Specification Reviews​

  • Peer review specs before implementation starts
  • Use clear acceptance criteria for validation
  • Document decisions in spec files, not just comments
  • Update specs when requirements change

Configuration Sharing​

  • Commit project config (.specify/config.toml) to version control
  • Document team conventions in README or CONTRIBUTING guides
  • Standardize patterns across projects in organization
  • Share global configs for consistent team experience

AI Integration​

Command Organization​

  • Separate by function: Different commands for different tasks
  • Use descriptive names: Make command purpose clear
  • Include examples: Show expected usage patterns
  • Keep updated: Sync with project evolution

Template Variables​

# Use consistent variable naming
{{ project_name }}          # snake_case for technical
{{ project_title }}         # Title Case for display
{{ ai_assistant }}          # lowercase for tools

Performance & Maintenance​

Project Hygiene​

  • Clean unused templates: Remove obsolete template files
  • Update dependencies: Keep project requirements current
  • Archive old specs: Move completed features to archive folder
  • Review configuration: Regularly audit settings for relevance

Troubleshooting Prevention​

  • Validate configuration: Use specifyx config validate
  • Test templates locally: Verify before committing changes
  • Document custom patterns: Explain non-standard configurations
  • Monitor script permissions: Ensure execution rights are maintained

Common Patterns​

Multi-Environment Setup​

# Development
[dev]
branch_patterns = ["feature/{name}", "experiment/{name}"]

# Production  
[prod]
branch_patterns = ["hotfix/{id}", "release/{version}"]

Custom Script Integration​

# .specify/scripts/custom_task.py
from specify_cli.utils import get_project_config

def main():
    config = get_project_config()
    # Custom logic using SpecifyX utilities

Following these patterns ensures consistent, maintainable, and effective use of SpecifyX across your development workflow.