.clackyrules Configuration

Overview

The .clackyrules file defines project-specific rules and conventions that help Clacky AI better understand your codebase and follow your project’s standards. This file should be placed in the root directory of your project and committed to your repository.

What is .clackyrules?

.clackyrules is a configuration file that contains:

Coding Standards: Style guides, naming conventions, and formatting rules
Project Constraints: Technical limitations, requirements, and boundaries
Background Context: Project history, architecture decisions, and domain knowledge
Git Management Norms: Commit message formats, branching strategies, and merge policies

Automatic Integration

The rules defined in .clackyrules are:

Automatically applied to all AI interactions within the project
Fetched by agents when they start working on your codebase
Applied to all threads in the current project for consistent behavior

File Specifications

Recommended size: 2,000 characters for optimal performance
Maximum size: 20,480 characters
Format: Plain text with clear, structured content
Location: Root directory of your project (same level as package.json, README.md, etc.)

Example .clackyrules File

# Project Rules for E-commerce Platform

## Coding Standards
- Use TypeScript for all new code
- Follow functional programming patterns where possible
- Prefer const over let, avoid var
- Use meaningful variable names (no abbreviations)
- All functions must have JSDoc comments
- Maximum line length: 100 characters

## Architecture Constraints  
- No direct database calls from components
- All API calls must go through the /api layer
- Use React Query for server state management
- Implement proper error boundaries
- Follow atomic design for component structure

## Git Conventions
- Commit messages: type(scope): description
- Branch naming: feature/ticket-number-description
- Always create PR for main branch merges
- Squash commits before merging

## Project Context
- Legacy payment system integration required
- Must support mobile-first responsive design
- Performance budget: <3s initial load time
- Accessibility: WCAG 2.1 AA compliance required

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Files: kebab-case (user-profile.utils.ts)
- Variables: camelCase (userProfileData)
- Constants: UPPER_SNAKE_CASE (API_BASE_URL)

Best Practices

Define Rule Objectives

Start your .clackyrules file with clear objectives that explain what you want to achieve:

# Objectives
- Maintain consistent code quality across the team
- Ensure security best practices are followed
- Optimize for performance and accessibility
- Reduce technical debt and improve maintainability

Provide Examples

Include concrete examples rather than abstract rules:

✅ Good: “Use descriptive function names: calculateTotalPrice() instead of calc()”

❌ Bad: “Use good naming conventions”

Avoid Rule Conflicts

Ensure your rules don’t contradict each other or common practices:

Don’t conflict with your linter/formatter settings
Be specific about priorities when rules might overlap
Clearly state exceptions to general rules

Key Conventions

Structure your rules in clear sections:

Coding Standards: Syntax, formatting, patterns
Architecture: Structure, dependencies, data flow
Testing: Coverage, naming, organization
Documentation: Comments, README updates
Git: Commits, branches, releases

Organize and Tag

Use clear headings and consistent formatting:

## Database Access Rules
- All queries must use TypeORM entities
- No raw SQL in business logic
- Use repository pattern for data access
- Implement proper transaction handling

## Error Handling Standards  
- Use custom error classes for business logic
- Log all errors with appropriate context
- Return user-friendly error messages
- Implement proper error boundaries in React

Integration with GitHub

We recommend merging your .clackyrules into your GitHub repository for several reasons:

Team Consistency: All team members and AI agents follow the same rules
Version Control: Track changes to your coding standards over time
CI/CD Integration: Rules can be referenced in automated workflows
Documentation: Serves as living documentation for new team members

Tips for Effective Rules

Start Small: Begin with essential rules and expand over time
Be Specific: Vague rules lead to inconsistent interpretation
Update Regularly: Evolve rules as your project grows
Test Impact: Monitor how rule changes affect AI behavior
Team Review: Collaborate on rules with your development team

Common Use Cases

New Project Setup

# New React + TypeScript Project Rules
- Use Next.js App Router for routing
- Implement TypeScript strict mode
- Use Tailwind CSS for styling
- Follow React 18+ patterns (hooks, suspense)

Legacy Code Maintenance

# Legacy System Constraints
- Maintain backward compatibility with PHP 7.4
- No breaking changes to existing API endpoints
- Gradual TypeScript migration strategy
- Preserve existing database schema

Team Collaboration

# Team Development Standards
- Code reviews required for all PRs
- Feature flags for experimental features
- Comprehensive unit test coverage (>80%)
- Performance testing for critical paths

Remember: The .clackyrules file is your opportunity to teach Clacky AI about your project’s unique requirements and ensure consistent, high-quality code generation that matches your team’s standards.

Services Open In Local IDE