Development Best Practices

Development Best Practices

This guide outlines best practices for AI-assisted development using agent-init. Following these practices ensures consistent, high-quality code and effective collaboration with AI assistants.

Core Principles

1. Issue-Driven Development

Always create issues before writing code.

Benefits:

• Clear scope and requirements
• Better tracking and documentation
• Improved AI context understanding
• Easier collaboration and review

Example workflow:

# Create an issue
make issue

# Create feature branch
git checkout -b feature/123-add-user-auth

# Work on the feature
# ...

# Reference issue in commit
git commit -m "feat: add user authentication (#123)"

2. Session Management

Use session tracking to maintain context across development.

Start every development session:

make session-start

Document in CLAUDE.md:

• Current goals
• Active issues
• Key decisions
• Blockers or questions

End sessions properly:

make session-end

3. Quality-First Approach

Run quality checks before every commit.

Essential checks:

# Run all quality checks
make lint test

# Or individually
make lint      # Code style
make test      # Unit tests
make typecheck # Type checking (if applicable)

Pre-commit checklist:

• Code passes linting
• All tests pass
• Documentation updated
• No console.log or debug statements
• No hardcoded values

Code Organization

Directory Structure

Maintain clear separation of concerns:

project/
├── src/              # Source code
│   ├── components/   # UI components
│   ├── utils/        # Utility functions
│   ├── services/     # Business logic
│   └── types/        # Type definitions
├── tests/            # Test files
├── docs/             # Documentation
├── scripts/          # Build/deploy scripts
└── external/         # Git submodules

File Naming Conventions

• Components: PascalCase (e.g., UserProfile.tsx)
• Utilities: camelCase (e.g., formatDate.ts)
• Tests: Match source with .test suffix
• Documentation: kebab-case (e.g., api-reference.md)

Module Organization

Keep modules focused and cohesive:

// Good: Single responsibility
export function validateEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

// Bad: Mixed concerns
export function userUtils() {
  // Validation, formatting, API calls all in one place
}

Working with AI Assistants

1. Clear Communication

Provide specific, actionable requests:

Good:

“Add input validation to the user registration form. Email should be valid format, password minimum 8 characters with at least one number.”

Avoid:

“Make the form better”

2. Context Management

Keep CLAUDE.md updated:

## Current Context
- Working on: User authentication feature
- Using: React + TypeScript + Jest
- Constraints: Must support SSO
- Dependencies: Auth0 SDK

3. Code Review with AI

Ask AI to review for:

• Security vulnerabilities
• Performance issues
• Best practice violations
• Missing edge cases
• Documentation gaps

Example prompt:

“Review this authentication module for security vulnerabilities and suggest improvements”

Documentation Standards

1. Code Comments

Document the “why”, not the “what”:

// Good: Explains reasoning
// Use debounce to prevent API spam during search
const debouncedSearch = debounce(searchAPI, 300);

// Bad: States the obvious
// Call search function
searchAPI();

2. Function Documentation

Use JSDoc or similar:

/**
 * Validates user credentials against the authentication service
 * @param credentials - User login credentials
 * @returns Promise resolving to authenticated user or null
 * @throws {AuthError} When authentication service is unavailable
 */
async function authenticate(credentials: LoginCredentials): Promise<User | null> {
  // Implementation
}

3. README Updates

Keep README current with:

• Setup instructions
• Architecture decisions
• API documentation links
• Troubleshooting guide

Testing Practices

1. Test Organization

Structure tests to mirror source:

src/
  components/
    UserProfile.tsx
tests/
  components/
    UserProfile.test.tsx

2. Test Coverage

Aim for meaningful coverage:

• Unit tests for utilities and pure functions
• Integration tests for API endpoints
• E2E tests for critical user paths

3. Test Naming

Use descriptive test names:

// Good: Clear expectation
describe('validateEmail', () => {
  it('should return false for email without @ symbol', () => {
    expect(validateEmail('invalid.email')).toBe(false);
  });
});

// Bad: Vague
it('should work', () => {
  // ...
});

Version Control

1. Commit Messages

Follow conventional commits:

feat: add user authentication
fix: resolve memory leak in data processor
docs: update API reference for v2
chore: upgrade dependencies
refactor: simplify error handling logic

2. Branch Strategy

Use descriptive branch names:

• feature/123-user-authentication
• bugfix/456-memory-leak
• chore/update-dependencies

3. Pull Request Guidelines

PR checklist:

• Descriptive title and description
• Links to related issues
• Tests added/updated
• Documentation updated
• No merge conflicts
• Reviews requested

External Dependencies

1. Submodule Management

Add external repositories properly:

# Add submodule
git submodule add https://github.com/org/repo external/repo

# Update submodules
git submodule update --init --recursive

# Track specific version
cd external/repo
git checkout v1.2.3
cd ../..
git add external/repo
git commit -m "chore: pin repo to v1.2.3"

2. Dependency Documentation

Document in CLAUDE.md:

## External Dependencies
- `external/auth-lib`: v2.1.0 - Authentication library
  - Purpose: Handle OAuth flows
  - License: MIT
  - Last updated: 2024-01-15

Performance Considerations

1. Code Optimization

Profile before optimizing:

• Use browser DevTools
• Run performance tests
• Monitor memory usage
• Track render times

2. Bundle Size

Keep bundles lean:

• Lazy load routes
• Tree shake imports
• Compress assets
• Monitor bundle size

3. Caching Strategy

Implement appropriate caching:

• HTTP cache headers
• Service worker caching
• Memoization for expensive operations
• Database query caching

Security Best Practices

1. Input Validation

Always validate user input:

// Validate and sanitize
function processUserInput(input: string): string {
  // Remove script tags
  const sanitized = DOMPurify.sanitize(input);

  // Validate length
  if (sanitized.length > MAX_LENGTH) {
    throw new ValidationError('Input too long');
  }

  return sanitized;
}

2. Authentication

Secure authentication practices:

• Use proven libraries (don’t roll your own)
• Implement proper session management
• Use secure password hashing
• Enable MFA when possible

3. Data Protection

Protect sensitive data:

• Encrypt data at rest
• Use HTTPS everywhere
• Implement proper access controls
• Audit data access

Continuous Improvement

1. Regular Reviews

Schedule regular reviews:

• Weekly code reviews
• Monthly dependency updates
• Quarterly security audits
• Annual architecture review

2. Learning from Issues

Post-mortem process:

1. What went wrong?
2. Why did it happen?
3. How can we prevent it?
4. What did we learn?

3. Metrics Tracking

Monitor key metrics:

• Test coverage
• Build times
• Bundle sizes
• Performance scores
• Error rates

Conclusion

Following these best practices ensures:

• Consistent, maintainable code
• Effective AI collaboration
• Reduced bugs and issues
• Better team productivity
• Higher code quality

Remember: These are guidelines, not rigid rules. Adapt them to your project’s specific needs while maintaining the core principles of quality and clarity.

See Also

• Getting Started Guide
• API Reference
• Example Guide