/claude-code-specs-generator

Claude Code Specs Generator

A documentation and context management system for AI-assisted development, inspired by Amazon's Kiro IDE. This tool generates structured specification documents that dramatically improve Claude Code's understanding of your project, leading to more accurate code suggestions and better architectural decisions.

Overview

Claude Code Specs Generator creates a systematic approach to project documentation by generating 6 essential documents that guide AI assistants in understanding your codebase:

Steering Documents (.claude/steering/)

  • product.md - Product vision, target users, features, and business goals
  • tech.md - Approved technology stack, libraries, and technical constraints
  • structure.md - Code organization patterns, folder layout, and naming conventions

Specification Documents (specs/)

  • design.md - Technical architecture and implementation details
  • requirements.md - User stories and acceptance criteria
  • tasks.md - Current development tasks and priorities

The system automatically updates your CLAUDE.md file to reference these documents, ensuring they're loaded into Claude's context for every interaction.

Benefits

  • Enhanced Code Quality: AI suggestions align with your approved tech stack and architectural patterns
  • Consistent Development: New features follow established conventions and product vision
  • Better Context Awareness: Claude understands your business domain and technical constraints
  • Faster Onboarding: New team members get comprehensive project understanding
  • Maintainable Documentation: Structured approach keeps docs up-to-date with codebase

Commands

/specs-create - Initial Setup

Creates the complete specs structure from scratch by analyzing your codebase.

What it does:

  1. Analyzes project architecture, tech stack, and existing documentation
  2. Generates all 6 specification documents
  3. Updates CLAUDE.md with document references
  4. Imports content from existing PRD.md, TODO.md, or similar files

When to use:

  • Starting a new project with Claude Code
  • First-time setup of the specs system
  • Migrating from manual documentation

/specs-init - Context Reload

Reinitializes Claude's context with the updated steering documents.

What it does:

  1. Clears Claude's working memory (/clear)
  2. Reloads context with all specs documents (/init)
  3. Prioritizes steering documents for maximum impact

When to use:

  • After running /specs-create
  • When Claude seems unaware of project context
  • After manual edits to specs documents

/refresh-specs - Quick Updates

Performs lightweight updates after minor code changes.

What it does:

  1. Analyzes recent git commits and file changes
  2. Updates specs to reflect new dependencies or structural changes
  3. Refreshes development status and priorities

When to use:

  • After small feature additions
  • When new dependencies are added
  • For routine maintenance after minor changes

/update-full-specs - Major Updates

Comprehensive documentation refresh after significant changes.

What it does:

  1. Deep analysis of codebase changes and new features
  2. Updates all 6 documents to reflect current state
  3. Reviews and removes outdated information
  4. Ensures cross-document consistency

When to use:

  • After major feature releases
  • Following architectural refactoring
  • When integrating new technologies
  • After sprint completion or milestone delivery

Getting Started

  1. Initial Setup

    Run: /specs-create

    This analyzes your codebase and creates all specification documents.

  2. Load Context

    Run: /specs-init

    This reloads Claude with your new project context.

  3. Verify Setup Ask Claude: "List the loaded steering docs."

    Expected response should acknowledge loading all 6 documents.

  4. Regular Maintenance

    • Use /refresh-specs after minor changes
    • Use /update-full-specs after major updates

File Structure

After setup, your project will include:

your-project/
├── .claude/
│   └── steering/
│       ├── product.md      # Product vision and business goals
│       ├── tech.md         # Technology stack and constraints
│       └── structure.md    # Code organization patterns
├── specs/
│   ├── design.md          # Technical architecture
│   ├── requirements.md    # User stories and acceptance criteria
│   └── tasks.md          # Current development tasks
└── CLAUDE.md             # Updated with document references

Best Practices

Document Maintenance

  • Keep tasks.md manageable to avoid excessive token usage
  • Regularly archive completed tasks
  • Update docs promptly after significant changes
  • Review and validate cross-references between documents

Usage Workflow

  1. Make code changes
  2. Run appropriate update command (/refresh-specs or /update-full-specs)
  3. Use /specs-init if context seems stale
  4. Continue development with enhanced AI assistance

Quality Assurance

  • Verify technical details match actual implementation
  • Ensure consistent terminology across all documents
  • Maintain accurate CLAUDE.md references
  • Remove deprecated or outdated information

Git Workflow

There is an included git workflow which will refresh the documents automatically after a PR is merged to the main branch. I would suggest testing it first since in its current form, it requires a Claude API key. You could modify it to accept the oauth token from Claude Code when it sets up Github Actions on its own from the console.

Inspiration

This system is inspired by Amazon's Kiro IDE approach to context management, where structured specification documents provide AI assistants with comprehensive project understanding. By maintaining these documents alongside your code, you create a powerful feedback loop that continuously improves AI-assisted development quality.

License

Whatever, use it how you like it.