BMAD-METHOD/docs/dev-template-guide.md

Developer Template Guide

BMAD Method Documentation

Introduction

This Developer Template Guide provides a comprehensive collection of templates designed specifically for developers working within the BMAD Method framework. These templates streamline development workflows, ensure consistency, and promote best practices across projects.

Template Categories

The developer templates are organized into six primary categories:

1. Project Setup Templates - For initializing new projects and components
2. Development Templates - For coding standards and implementation patterns
3. Testing Templates - For test planning and implementation
4. Documentation Templates - For code and API documentation
5. Review Templates - For code reviews and quality assurance
6. Handoff Templates - For transitioning completed work

Template Library

Project Setup Templates

Component Initialization Template

/**
 * @component ComponentName
 * @description Brief description of the component's purpose
 * @author Developer Name
 * @created YYYY-MM-DD
 * 
 * @props {PropType} propName - Description of the prop
 * @returns {JSX.Element} Component JSX
 */

import React from 'react';
import { PropType } from './types';

interface ComponentNameProps {
  propName: PropType;
  // Add additional props
}

export const ComponentName: React.FC<ComponentNameProps> = ({ 
  propName,
  // Destructure additional props
}) => {
  // Component logic
  
  return (
    <div className="component-name">
      {/* Component JSX */}
    </div>
  );
};

export default ComponentName;

Project Structure Template

project-name/
├── src/
│   ├── components/
│   │   ├── common/
│   │   │   └── [shared components]
│   │   ├── features/
│   │   │   └── [feature-specific components]
│   │   └── layouts/
│   │       └── [layout components]
│   ├── hooks/
│   │   └── [custom hooks]
│   ├── utils/
│   │   └── [utility functions]
│   ├── services/
│   │   └── [API services]
│   ├── types/
│   │   └── [TypeScript types/interfaces]
│   ├── styles/
│   │   └── [global styles]
│   └── pages/
│       └── [page components]
├── public/
│   └── [static assets]
├── tests/
│   └── [test files]
└── [configuration files]

Development Templates

Component Implementation Template

/**
 * @component FeatureComponent
 * @description Implements the [feature name] functionality
 */

import React, { useState, useEffect } from 'react';
import { useService } from '@/hooks/useService';
import { ComponentProps } from '@/types';

export const FeatureComponent: React.FC<ComponentProps> = (props) => {
  // State management
  const [data, setData] = useState<DataType>(initialState);
  
  // Service hooks
  const { fetchData, isLoading, error } = useService();
  
  // Effects
  useEffect(() => {
    // Effect logic
    const loadData = async () => {
      const result = await fetchData();
      setData(result);
    };
    
    loadData();
  }, [fetchData]);
  
  // Event handlers
  const handleAction = () => {
    // Handler logic
  };
  
  // Conditional rendering
  if (isLoading) return <LoadingComponent />;
  if (error) return <ErrorComponent message={error.message} />;
  
  // Main render
  return (
    <div className="feature-component">
      {/* Component content */}
    </div>
  );
};

Custom Hook Template

/**
 * @hook useFeature
 * @description Custom hook for [feature] functionality
 * @returns {Object} Hook methods and state
 */

import { useState, useEffect, useCallback } from 'react';

export function useFeature(initialValue) {
  // State
  const [state, setState] = useState(initialValue);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);
  
  // Methods
  const doSomething = useCallback(async () => {
    setIsLoading(true);
    setError(null);
    
    try {
      // Implementation
      const result = await someAsyncOperation();
      setState(result);
      return result;
    } catch (err) {
      setError(err);
      return null;
    } finally {
      setIsLoading(false);
    }
  }, [/* dependencies */]);
  
  // Effects
  useEffect(() => {
    // Effect implementation
  }, [/* dependencies */]);
  
  // Return hook API
  return {
    state,
    isLoading,
    error,
    doSomething
  };
}

Testing Templates

Component Test Template

/**
 * @test ComponentName
 * @description Test suite for ComponentName component
 */

import { render, screen, fireEvent } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { ComponentName } from './ComponentName';

describe('ComponentName', () => {
  // Test setup
  const defaultProps = {
    propName: 'test value'
  };
  
  beforeEach(() => {
    // Setup before each test
  });
  
  afterEach(() => {
    // Cleanup after each test
  });
  
  // Test cases
  test('renders correctly with default props', () => {
    render(<ComponentName {...defaultProps} />);
    expect(screen.getByText('expected text')).toBeInTheDocument();
  });
  
  test('handles user interaction correctly', async () => {
    render(<ComponentName {...defaultProps} />);
    
    // Simulate user interaction
    await userEvent.click(screen.getByRole('button'));
    
    // Assert expected outcome
    expect(screen.getByText('new state')).toBeInTheDocument();
  });
  
  test('calls callback when action performed', () => {
    const mockCallback = jest.fn();
    render(<ComponentName {...defaultProps} onAction={mockCallback} />);
    
    fireEvent.click(screen.getByRole('button'));
    
    expect(mockCallback).toHaveBeenCalledTimes(1);
    expect(mockCallback).toHaveBeenCalledWith(expect.any(Object));
  });
});

Integration Test Template

/**
 * @test FeatureIntegration
 * @description Integration tests for the Feature functionality
 */

import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { FeatureContainer } from './FeatureContainer';
import { ServiceProvider } from '@/services';
import { mockService } from '@/tests/mocks';

describe('Feature Integration', () => {
  // Setup test environment
  beforeEach(() => {
    // Setup mocks and providers
  });
  
  test('completes end-to-end workflow successfully', async () => {
    // Arrange
    mockService.getData.mockResolvedValueOnce({ id: 1, name: 'Test' });
    
    // Act
    render(
      <ServiceProvider value={mockService}>
        <FeatureContainer />
      </ServiceProvider>
    );
    
    // Initial state assertions
    expect(screen.getByText('Loading...')).toBeInTheDocument();
    
    // Wait for data load
    await waitFor(() => {
      expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
    });
    
    // Interact with the feature
    await userEvent.click(screen.getByText('Perform Action'));
    
    // Assert final state
    expect(screen.getByText('Action Complete')).toBeInTheDocument();
    expect(mockService.updateData).toHaveBeenCalledWith({ id: 1, status: 'updated' });
  });
});

Documentation Templates

API Documentation Template

/**
 * @api ServiceName
 * @description Service for handling [functionality] operations
 */

/**
 * Fetches data from the API
 * 
 * @async
 * @function fetchData
 * @param {string} id - The identifier for the requested resource
 * @param {Object} options - Additional options for the request
 * @param {boolean} options.includeDetails - Whether to include detailed information
 * @returns {Promise<DataType>} The fetched data
 * @throws {Error} When the network request fails
 * @example
 * // Basic usage
 * const data = await fetchData('user-123');
 * 
 * // With options
 * const detailedData = await fetchData('user-123', { includeDetails: true });
 */
export async function fetchData(id, options = {}) {
  // Implementation
}

Component Documentation Template

# ComponentName

## Overview
Brief description of the component's purpose and functionality.

## Props

| Name | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| prop1 | string | - | Yes | Description of prop1 |
| prop2 | number | 0 | No | Description of prop2 |
| prop3 | () => void | - | No | Callback when action occurs |

## Usage Examples

### Basic Usage
```jsx
import { ComponentName } from '@/components';

function MyComponent() {
  return <ComponentName prop1="value" />;
}

Advanced Usage

import { ComponentName } from '@/components';

function MyComponent() {
  const handleAction = () => {
    console.log('Action triggered');
  };

  return (
    <ComponentName 
      prop1="value"
      prop2={42}
      prop3={handleAction}
    />
  );
}

Behavior

Describe the component's behavior, including:

• State management
• Side effects
• User interactions
• Error handling

Accessibility

Accessibility considerations and implementations:

• Keyboard navigation
• Screen reader support
• ARIA attributes
• Focus management

### Review Templates

#### Code Review Template

```markdown
# Code Review: [PR/Component Name]

## General Assessment
- [ ] Code follows project style guidelines
- [ ] Component/function has a single responsibility
- [ ] Logic is clear and maintainable
- [ ] Error handling is appropriate
- [ ] Performance considerations addressed

## Specific Feedback

### Strengths
- 
- 
- 

### Areas for Improvement
- 
- 
- 

### Questions
- 
- 
- 

## Testing Assessment
- [ ] Unit tests cover core functionality
- [ ] Edge cases are tested
- [ ] Mocks are used appropriately
- [ ] Test descriptions are clear

## Documentation Assessment
- [ ] Code is well-commented
- [ ] API documentation is complete
- [ ] Usage examples provided
- [ ] Complex logic is explained

## Final Recommendation
- [ ] Approve
- [ ] Approve with minor changes
- [ ] Request changes

## Additional Notes

Performance Review Template

# Performance Review: [Component/Feature Name]

## Rendering Performance
- Initial render time: [ms]
- Re-render time: [ms]
- Memory usage: [MB]

## Network Performance
- Bundle size impact: [KB]
- API call efficiency: [description]
- Caching strategy: [description]

## Optimization Opportunities
- [ ] Memoization of expensive calculations
- [ ] Lazy loading of components
- [ ] Code splitting
- [ ] Resource preloading
- [ ] Virtualization for large lists

## Profiling Results
[Include screenshots or data from performance profiling tools]

## Recommendations
1. 
2. 
3. 

## Implementation Priority
- [ ] Critical (blocking issue)
- [ ] High (significant impact)
- [ ] Medium (noticeable improvement)
- [ ] Low (minor optimization)

Handoff Templates

Implementation Handoff Template

# Implementation Handoff: [Feature Name]

## Feature Overview
Brief description of the implemented feature.

## Implementation Details
- **Files Modified**:
  - `path/to/file1.tsx`: Description of changes
  - `path/to/file2.tsx`: Description of changes
  
- **New Components**:
  - `ComponentName`: Purpose and usage
  
- **Services/Hooks**:
  - `serviceName`: Purpose and API
  
- **State Management**:
  - Description of state changes and data flow

## Testing
- **Test Coverage**: XX%
- **Test Files**:
  - `path/to/test1.test.tsx`: What it tests
  - `path/to/test2.test.tsx`: What it tests
  
- **Manual Testing Scenarios**:
  1. Step-by-step scenario 1
  2. Step-by-step scenario 2

## Known Limitations
- List any known issues or limitations
- Include planned future improvements

## Dependencies
- List of external dependencies and versions
- Any specific configuration requirements

## Deployment Notes
- Special deployment considerations
- Feature flags or environment variables

## Documentation
- Links to relevant documentation
- API references

Template Selection Matrix

Use this matrix to determine which templates to use based on your current development phase:

Development Phase	Recommended Templates
Project Initialization	Project Structure Template, Component Initialization Template
Feature Development	Component Implementation Template, Custom Hook Template, API Documentation Template
Testing	Component Test Template, Integration Test Template
Code Review	Code Review Template, Performance Review Template
Documentation	API Documentation Template, Component Documentation Template
Handoff	Implementation Handoff Template

Template Customization Guidelines

These templates are designed to be customized for your specific project needs:

1. Maintain Core Structure: Keep the fundamental structure intact to ensure consistency
2. Extend as Needed: Add project-specific sections or fields as required
3. Remove Irrelevant Sections: Not all sections will apply to every component or feature
4. Update Standards: As project standards evolve, update templates accordingly
5. Version Control: Track template changes in version control

Template Maintenance

The Developer Template Guide should be maintained as a living document:

1. Regular Reviews: Review templates quarterly to ensure they remain relevant
2. Feedback Collection: Gather developer feedback on template usability
3. Update Process: Follow the standard documentation update process for template changes
4. Versioning: Maintain version history for templates
5. Notification: Notify the development team of significant template changes

Integration with Development Workflow

These templates integrate with the BMAD Method development workflow:

1. IDE Integration: Templates can be added as snippets in your IDE
2. CI/CD Integration: Templates can be used in automated checks
3. Code Generation: Templates can be used with code generation tools
4. Documentation Generation: API documentation templates can feed into automated documentation systems

---

Last Updated: June 2025