ai-rules for Claude Code

To prevent context window bloat and improve Claude's reasoning capabilities, distinguish between Rules and Skills:

• Rules (.claude/rules/): Use these for high-level, declarative standards that Claude needs to know for literally every task (e.g., "Use conventional commits" or "Never use git add -A"). Keep these short and avoid code examples.
• Skills (.claude/commands/): Use these for detailed, implementation-heavy guides that are only relevant during specific tasks (e.g., "How to configure Playwright" or "k6 load testing templates"). These are invoked on-demand using a command (e.g., /test) and can contain extensive code examples and checklists.

The Goal: Minimize the lines in .claude/rules/ (aim for ~300 lines) to leave maximum space for your actual code and reasoning.

# Example of how a skill is invoked in a conversation
/test

The project uses a two-tier context management system to optimize Claude Code's performance and reduce context bloat. Instead of loading all instructions at once, it separates them into:

1. Always-loaded Rules (.claude/rules/): These are the "what". They contain non-negotiable, high-level standards that apply to every task (e.g., coding standards, security principles, Git conventions). They are small (~276 lines) to ensure they stay in Claude's active context without overwhelming it.

2. On-demand Skills (.claude/commands/): These are the "how". They contain detailed implementation guides, templates, and checklists. They are only loaded when you explicitly invoke them using a slash command (e.g., /test, /api). This keeps the context relevant to the specific task at hand.

This project uses a two-tier system to manage Claude Code context efficiently:

1. Always-Loaded Rules: Short, declarative standards located in .claude/rules/. These load into every conversation and cover non-negotiable standards (e.g., coding-standards.md, git-standards.md). They are designed to be minimal (approx. 276 lines) to save context.
2. On-Demand Skills: Detailed guides and code examples located in .claude/commands/. These do not consume context until you explicitly invoke them using a /command in the Claude Code interface.

Design Principle: Rules define what the standard is; Skills define how to implement it.

Before writing custom markdown rules to enforce workflows, check if Claude Code provides a native way to handle it. Custom markdown enforcement is brittle and burns context.

To use these rules across multiple projects while keeping them updated, add the repository as a git submodule and symlink the rules and commands into your project's .claude directory. This ensures that the core rules are loaded into every conversation without bloating your context window.

# Add to your project
git submodule add https://github.com/sahin/ai-rules.git .claude/ai-rules

# Symlink rules and commands into place
ln -s ai-rules/.claude/rules .claude/rules
ln -s ai-rules/.claude/commands .claude/commands

If you prefer not to use git submodules, you can manually clone the repository and copy the rules and commands directories directly into your project's .claude folder.

git clone https://github.com/sahin/ai-rules.git
cp -r ai-rules/.claude/rules /your/project/.claude/rules/
cp -r ai-rules/.claude/commands /your/project/.claude/commands/

Use these commands to check if your rules are consuming too much context. If your rules exceed 1,000 lines, you are likely hurting Claude's performance.

# Count total lines in your rules
wc -l .claude/rules/**/*.md

# Count individual files
find .claude/rules -name "*.md" | wc -l

Ensure that your CLAUDE.md file does not contain "phantom references" (links to directories that do not exist). Phantom references waste context and cause Claude to hallucinate or waste tool calls. Use this script to verify your references:

# Check if your CLAUDE.md references things that exist
grep -oP '\.\S+/' CLAUDE.md | sort -u | while read dir; do
  [ -d "$dir" ] || echo "PHANTOM: $dir does not exist"
done

The following rules are automatically loaded into every Claude Code conversation to enforce baseline standards.

| File | Covers |
|------|--------|
| `coding-standards.md` | File naming, size limits, imports, error handling, TypeScript, anti-patterns |
| `testing-requirements.md` | Coverage targets, test pyramid, AAA pattern, before-delivery checklist |
| `api-security-standards.md` | REST design, HTTP status codes, input validation, auth, OWASP top 10 |
| `database-standards.md` | Naming, required columns, constraints, migrations, query performance |
| `git-standards.md` | Branch naming, conventional commits, PR guidelines |
| `project-standards.md` | File organization, docs placement, frontend requirements, env config |

The following six categories of standards are always present in the context to ensure consistent output. They define the "what" of the project's quality requirements:

1. Coding Standards: File naming (kebab-case), component naming (PascalCase), function size limits, and TypeScript policies.
2. Testing Requirements: Coverage targets (e.g., 100% API, 80% UI), test pyramid ratios, and the AAA pattern.
3. API & Security Standards: RESTful design, HTTP status codes, input validation, and OWASP awareness.
4. Database Standards: Naming (snake_case), required columns (created_at, updated_at), and migration principles.
5. Git Standards: Branch naming (feature/, bugfix/), conventional commits, and PR size limits.
6. Project Standards: File organization, documentation location, and mandatory UI states (loading/error/empty).