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

• Conventional Commits
• fast-check Property Testing
• TypeBox Schema Validation

🤝 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 🚀