Modular Rules
Relevant source files
The following files were used as context for generating this wiki page:Modular Rules are an optional set of markdown files that provide specific, granular instructions to the Claude Code agent. They are located in the .claude/rules/ directory and serve as a supplement to the main project memory file, CLAUDE.md. These rules allow for organizing instructions into distinct, manageable topics, such as code style or security guidelines.
Unlike Skills, which are detailed documents about project-specific patterns that Claude decides when to apply, Modular Rules appear to be more general-purpose instructions that can be loaded for context. They are presented as an optional feature for organizing instructions.
Sources: README.md:100-102
Architecture and Purpose
Modular Rules fit into the broader Claude Code configuration as a source of contextual information. They exist alongside the primary CLAUDE.md project memory and the more complex Skills system. While CLAUDE.md provides a high-level overview and critical project-wide rules, the .claude/rules/ directory allows for a more organized and granular breakdown of these instructions.
The following diagram illustrates the hierarchy of knowledge sources available to the Claude Code agent within this project.
This diagram shows how Modular Rules act as one of several information sources for the agent.
Sources: README.md:23, README.md:65, README.md:100, CLAUDE.md:1
Comparison with Other Configuration
The project utilizes several mechanisms to guide the AI agent. The table below compares Modular Rules with CLAUDE.md and Skills.
| Feature | CLAUDE.md | Modular Rules | Skills |
|---|---|---|---|
| Location | Project root or .claude/ | .claude/rules/ | .claude/skills/{skill-name}/ |
| Purpose | Persistent project memory, key facts, critical rules | Optional, modular instructions | Deep domain knowledge, specific patterns |
| Format | Markdown | Markdown | Markdown with frontmatter |
| Activation | Automatic at session start | Assumed to be loaded for context | Matched via description and triggers |
Sources: README.md:65-67, README.md:100-102, README.md:310-312, CLAUDE.md:31-48, .claude/skills/testing-patterns/SKILL.md:1-5
Directory Structure
Modular Rules are stored within the .claude/ directory, which centralizes the configuration for the Claude Code agent.
your-project/
└── .claude/
├── agents/
├── commands/
├── hooks/
├── skills/
└── rules/
├── code-style.md
└── security.md
Sources: README.md:41, README.md:56-58
The repository provides two examples of modular rules:
code-style.md: Contains guidelines related to code formatting and conventions.security.md: Contains guidelines for writing secure code.
Sources: .claude/rules/code-style.md, .claude/rules/security.md
Example Rules
The repository includes examples that demonstrate how to structure these rule files.
Code Style Rules
The code-style.md file provides a set of formatting and style conventions that are more granular than the high-level style points in CLAUDE.md.
Key Guidelines:
- Imports: Grouped and sorted (stdlib, third-party, internal).
- Naming: Use
PascalCasefor components/types andcamelCasefor variables/functions. - Comments: Use
//for single-line and/** ... */for JSDoc blocks. - Error Handling: Prefer
try...catchfor async operations and use specific error classes.
Sources: .claude/rules/code-style.md:3-25
Security Rules
The security.md file outlines critical security practices to be followed during development.
Key Guidelines:
- Input Validation: Always validate and sanitize user input on the server-side.
- Authentication: Use JWTs with short-lived access tokens and secure refresh tokens.
- API Security: Implement rate limiting and protect against common vulnerabilities (CSRF, XSS).
- Dependencies: Avoid using dependencies with known vulnerabilities.
Sources: .claude/rules/security.md:3-23
Summary
Modular Rules provide an optional but organized way to supply Claude Code with specific instructions. By separating concerns like code style and security into individual files within the .claude/rules/ directory, developers can maintain a clean and scalable set of guidelines for the AI agent. This approach complements the broader project context defined in CLAUDE.md and the specialized, trigger-based knowledge contained in Skills.
Sources: README.md:100-102