Skip to content

rules-guide.md

Latest commit

 

History

History
153 lines (121 loc) · 3.95 KB

rules-guide.md

File metadata and controls

153 lines (121 loc) · 3.95 KB

Path Rules Guide

Path rules (.claude/rules/*.md) are context files that are loaded only when Claude edits files matching the specified path patterns. This keeps Claude's context focused and relevant.

File Location

.claude/rules/
├── backend.md      # Loaded when editing backend code
├── frontend.md     # Loaded when editing frontend code
└── database.md     # Loaded when editing schema files

Syntax

Each rule file has a YAML frontmatter with a paths array, followed by the rule content in markdown:

---
paths:
  - "apps/api/**/*.ts"
  - "apps/api/**/*.tsx"
---
# Backend API Conventions
- Use authentication guards on all controllers
- Service methods must include error handling

Path Pattern Syntax

Paths use glob patterns:

Pattern Matches
**/*.ts All .ts files in any subdirectory
apps/api/**/*.ts .ts files under apps/api/
src/components/*.tsx .tsx files directly in src/components/ (not subdirs)
**/*.prisma All .prisma files anywhere
**/test/** All files under any test/ directory

When Rules Load

Rules are loaded when Claude is about to edit (Edit or Write tool) a file that matches any path pattern in the frontmatter. They are not loaded when:

  • Claude reads a file
  • Claude searches with Grep/Glob
  • The file doesn't match any pattern

Best Practices

1. Keep Rules Focused

Each rule file should cover one domain. Don't mix backend and frontend rules.

# Good
.claude/rules/backend.md     → Backend conventions
.claude/rules/frontend.md    → Frontend conventions
.claude/rules/database.md    → Database conventions

# Bad
.claude/rules/all-rules.md   → Everything in one file

2. Rules vs. CLAUDE.md

Content Where
Project overview, tech stack, key paths CLAUDE.md
Universal coding standards CLAUDE.md
Backend-specific conventions .claude/rules/backend.md
Frontend-specific conventions .claude/rules/frontend.md
Database-specific conventions .claude/rules/database.md

3. Be Specific and Actionable

Rules should tell Claude what to do, not explain concepts.

# Good
- Use @UseGuards(JwtAuthGuard) on all controller routes
- Database queries must use include/select for related data

# Bad
- Follow best practices for security
- Write efficient database queries

4. Include Framework-Specific Patterns

# NestJS Backend Rules
- All controllers use @UseGuards(JwtAuthGuard)
- DTOs validated with class-validator decorators
- Use NestJS Logger, not console.log
- Modules needing global scope use @Global()

# FastAPI Backend Rules
- All route handlers use Depends() for auth
- Pydantic models for request/response validation
- Use Python logging, not print()
- Database sessions via get_db() dependency

5. Reference Key Services

If your project has centralized services, tell Claude to use them:

- AI calls go through AiService — never call external APIs directly
- File storage goes through StorageService
- WebSocket events pushed through the Gateway

Common Rule Files

Test Conventions

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---
# Test Conventions
- Use descriptive test names: "should [expected behavior] when [condition]"
- Arrange-Act-Assert pattern
- Mock external services, not internal logic
- Each test file corresponds to one source file

API Documentation

---
paths:
  - "apps/api/**/*.controller.ts"
---
# Controller Conventions
- Add Swagger decorators (@ApiOperation, @ApiResponse) to all endpoints
- Group related endpoints with @ApiTags
- Document query parameters and request bodies

Migration Files

---
paths:
  - "alembic/versions/*.py"
  - "prisma/migrations/**"
---
# Migration Conventions
- Never delete columns in production without a deprecation period
- Always add indexes for foreign keys
- Test migrations with rollback: up then down