Skip to content

README.md

Latest commit

 

History

History
142 lines (108 loc) · 4.08 KB

README.md

File metadata and controls

142 lines (108 loc) · 4.08 KB

Claude Code Guidelines

Sabrina Ramonov's best practices for Claude Code development

This repository contains comprehensive guidelines for using Claude Code effectively, emphasizing maintainability, safety, and developer velocity.

🚀 Quick Setup

Install these guidelines on any device with Claude Code:

curl -s https://raw.githubusercontent.com/ekodevapps/Claude-Code-Guidelines/main/setup.sh | bash

Or manually:

git clone https://github.com/ekodevapps/Claude-Code-Guidelines.git
mkdir -p ~/.claude
cp Claude-Code-Guidelines/CLAUDE.md ~/.claude/CLAUDE.md

📋 What's Included

Implementation Best Practices

  • Before Coding: Clarifying questions and approach planning
  • While Coding: TDD, naming conventions, type safety
  • Testing: Unit/integration separation, assertion quality
  • Database: Transaction handling and type overrides
  • Code Organization: Monorepo structure guidelines
  • Tooling Gates: Prettier and TypeScript requirements
  • Git Standards: Conventional commits format

Quality Checklists

  • Function Quality: Readability, complexity, testability analysis
  • Test Quality: Strong assertions, edge cases, no trivial tests
  • Property-Based Testing: Using fast-check for robust test coverage

Quick Command Shortcuts

  • QNEW: Initialize with best practices
  • QPLAN: Analyze codebase for consistent implementation
  • QCODE: Implement with tests and formatting
  • QCHECK/QCHECKF/QCHECKT: Code quality reviews
  • QUX: Generate UX test scenarios
  • QGIT: Conventional commits and push

🏗️ Code Organization

packages/
├── api/                    # Fastify API server
│   ├── src/publisher/      # Social media integrations
│   └── test/              # Integration tests
├── web/                   # Next.js 15 App Router
├── shared/                # Shared utilities (≥2 packages)
│   └── src/db-types.override.ts
└── api-schema/            # TypeBox contracts

🧪 Testing Philosophy

Must Follow

  • T-1: Colocate unit tests in *.spec.ts files
  • T-2: Integration tests in packages/api/test/
  • T-3: Separate pure logic from DB-touching tests
  • T-6: Single comprehensive assertions over multiple weak ones

Example Quality Test

describe('getCharacterCount', () => {
  test('counts characters correctly for various inputs', () => {
    const testCases = [
      { input: 'hello', expected: 5 },
      { input: 'hello world', expected: 11 },
      { input: '', expected: 0 }
    ];
    
    testCases.forEach(({ input, expected }) => {
      expect(getCharacterCount(input)).toBe(expected);
    });
  });
});

🔧 Development Workflow

TDD Cycle

  1. Scaffold stub → Write minimal function signature
  2. Write failing test → Red phase
  3. Implement → Green phase
  4. Refactor → Maintain quality

Quality Gates

  • ✅ prettier --check passes
  • ✅ turbo typecheck lint passes
  • ✅ All tests pass
  • ✅ Functions follow quality checklist

💡 Pro Tips

Type Safety

// ✅ Good: Branded types for IDs
type UserId = Brand<string, 'UserId'>

// ❌ Bad: Plain string types
type UserId = string

Function Quality

  • Readable and self-explanatory code over comments
  • Low cyclomatic complexity
  • Single responsibility
  • Easy to test without heavy mocking

When NOT to Extract Functions

  • Won't be reused elsewhere
  • Doesn't improve testability significantly
  • Doesn't drastically improve readability

📚 Resources

🤝 Contributing

These guidelines evolve with best practices. To update:

  1. Fork this repository
  2. Make your changes to CLAUDE.md
  3. Test with your projects
  4. Submit a pull request

📄 License

MIT License - Use these guidelines freely in your projects.

Made for Claude Code developers who value quality, maintainability, and velocity 🚀