Improved workflow with Claude

AI-Generated Workflow for a Project

I keep updating it; that’s the current state as I write this. It’s too verbose now, but I kinda like this version. I do need to make it more concise…

Check it out:

AI-Assisted Development Workflow

This document outlines the recommended workflow for developing features with Claude’s assistance.

Overview

The development workflow consists of three main phases that may be revisited iteratively:

1. Research & Planning: Gather information and requirements
2. Specification: Create clear implementation specifications
3. Implementation: Code the feature based on the specification

Directory Structure

/
├── ai_docs/                    # AI planning and research documents
│   ├── features/               # Feature-specific research and planning
│   │   └── feature_name/       # Documents for a specific feature
│   │       ├── research.md     # Research findings
│   │       ├── planning.md     # Planning notes
│   │       └── requirements.md # Requirements
│   └── workflow.md             # This workflow document
├── specs/                      # Implementation specifications
│   └── feature_name_spec.md    # Specification for a feature
├── .claude/                    # Claude-specific configuration
│   └── commands/               # Commands to prime Claude for different tasks
│       ├── plan.md             # Command to prime context for planning
│       └── implement.md        # Command to prime context for implementation
└── [rest of project]           # Actual codebase

Note from a human

I’ve seen this folder structure on some videos of https://www.youtube.com/@indydevdan, and I’m giving it a try

Workflow Phases

1. Research & Planning

During this phase:

• Research and gather all necessary information
• Document findings in ai_docs/features/[feature_name]/
• Create multiple documents as needed for different aspects
• Each feature in ai_docs/features/ should include:
  • Requirements
  • Architecture decisions
  • API contracts
  • Data models
• Use the plan command to prime Claude’s context for planning

Example commands:

# Within a Claude session
/project:plan

Claude will ask which feature you want to plan, and then prime its context accordingly.

2. Specification

During this phase:

• Synthesize research into a clear implementation specification
• Create a spec file at specs/[feature_name]_spec.md
• Reference relevant research documents from ai_docs/
• The spec should be comprehensive and standalone
• Focus on implementation details, not research findings

Spec format:

# Feature Name Specification
 
## Overview
Brief description of the feature.
 
This spec is based on research documented in:
- [Research Document 1](/ai_docs/features/feature_name/research1.md)
- [Research Document 2](/ai_docs/features/feature_name/research2.md)
 
## Requirements
List of requirements.
 
## Implementation Details
Detailed implementation plan.
 
## Testing
Testing approach.

3. Implementation

During this phase:

• Use the specification as the primary reference
• Code the feature according to the specification
• Use the implement command to prime Claude’s context for implementation
• Always write tests first or alongside implementation code
• Implement in small testable increments
• Run tests frequently to catch issues early

Example commands:

# Within a Claude session
/project:implement

Claude will ask which spec you want to implement, and then prime its context accordingly.

Iterative Development

The development process is iterative rather than strictly linear:

1. Continuous Documentation Updates:

   • As you learn more during implementation, update the research documents instead of creating new ones
   • Refine the specification as the implementation progresses
   • The spec should always reflect the current understanding and approach

2. Moving Between Phases:

   • You may need to return to the planning phase when new questions arise
   • Update the specification when implementation details change
   • Keep cycling through planning → specification → implementation as needed

3. Avoiding Duplication:

   • Rather than creating new files when revisiting a phase, update existing documents
   • Maintain a single source of truth for each aspect of the feature
   • Use clear references between documents rather than duplicating content

4. Consolidation at Milestones:

   • Periodically review and consolidate documentation
   • Remove redundant or obsolete documents
   • Keep the most up-to-date and relevant documentation

Working with Claude

• For planning tasks:
  • Within a session: /project:plan (Claude will ask which feature to plan)
• For implementation tasks:
  • Within a session: /project:implement (Claude will ask which spec to implement)
• Keep research documents in ai_docs/
• Keep implementation specs in specs/
• Reference research documents from specs
• The actual code is the primary documentation; ai_docs are temporary artifacts

From Specification to Implementation

When a specification document is complete, the implementation phase begins:

1. Use the implement command to prime Claude with the specification:

   /project:implement
   

2. When prompted, specify which spec to implement (e.g., specs/feature_name_spec.md)
3. Claude will transform the specification into actionable todos
4. Each todo represents a concrete implementation task
5. Work through todos systematically, marking them as in-progress and completed
6. If issues arise during implementation, update the specification and run the implement command again
7. For complex migrations or database changes, always create a detailed specification before implementation

Documentation Management

• Always update documentation rather than create new files
• Use clear file naming conventions
• Keep one implementation spec file for each feature
• Relevant documentation should be moved to the docs directory for long-term reference
• The ai_docs directory is primarily for AI assistance and may be removed or archived after feature completion

Code Review Process

1. Ensure all tests pass
2. Verify implementation against requirements in specs/
3. Check for architecture adherence
4. Confirm tests are comprehensive
5. Verify test coverage is adequate for critical functionality
6. Check that error cases are properly tested
7. Ensure tests are maintainable and clearly document the expected behavior

Example Workflow

# Initial research and planning
/project:plan
# When prompted, specify the feature name 'my_feature'
# Document findings in ai_docs/features/my_feature/research.md

# Create specification
# Create specs/my_feature_spec.md referencing research

# Begin implementation
/project:implement
# When prompted, specify the spec 'specs/my_feature_spec.md'

# New information discovered during implementation
# Update ai_docs/features/my_feature/research.md
# Update specs/my_feature_spec.md to reflect new understanding

# Continue implementation with updated spec
/project:implement
# When prompted, specify the spec 'specs/my_feature_spec.md'

# Final review and cleanup
# Remove redundant docs from ai_docs/features/my_feature/
# Ensure specs/my_feature_spec.md is complete and accurate