Introduction
In today's software development landscape, AI coding assistants like GitHub Copilot, Cursor, and Claude have become invaluable tools. However, ensuring these AI tools adhere to project-specific coding standards remains challenging. Rulens addresses this gap by automatically converting your linting configurations into AI-friendly documentation.
What is Rulens?
Rulens is a CLI tool that extracts and formats your Biome and ESLint rules into comprehensive Markdown documentation. This documentation can then be read by AI coding assistants, helping them understand your project's standards before writing any code.
npx rulens generateThe following markdown will be generated:
# Project Lint Rules Reference
## 📋 Document Overview
This document contains a comprehensive catalog of linting rules enabled in this project. It is automatically generated by [Rulens](https://github.com/MH4GF/rulens) and provides AI code assistants and developers with detailed information about code style and quality requirements.
---
## 📑 Table of Contents
- [Introduction](#introduction)
- [AI Usage Guide](#ai-usage-guide)
- [Biome Rules](#biome-rules)
- [ESLint Rules](#eslint-rules)
---
## 📖 Introduction
This document lists all active linting rules configured in the project. Each rule includes:
- A link to official documentation
- A brief description of what the rule enforces
- Severity level (when available)
Use this reference to understand the code standards and avoid common issues when writing or reviewing code.
---
## 🤖 AI Usage Guide
**For AI Code Assistants**: When generating code for this project, please adhere to the following guidelines:
1. **Scan relevant categories first**: Focus on rules in categories related to the code you're generating.
2. **Respect all rules**: Ensure all generated code follows all linting rules.
3. **Avoid common pitfalls**: Check complexity rules to avoid anti-patterns.
When uncertain about specific rules, refer to the rule documentation links provided.
---
## 🔧 Biome Rules
Biome enforces modern JavaScript/TypeScript best practices with a focus on correctness, maintainability, and performance.
### accessibility
Rules in this category ensure that code is accessible to all users, including those using assistive technologies.
| Rule | Description | Options |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------- |
| [`noAccessKey`](https://biomejs.dev/linter/rules/no-access-key) | Enforce that the accessKey attribute is not used on any HTML element. | |
| [`noAriaHiddenOnFocusable`](https://biomejs.dev/linter/rules/no-aria-hidden-on-focusable) | Enforce that aria-hidden=“true” is not set on focusable elements. | |
| [`noAriaUnsupportedElements`](https://biomejs.dev/linter/rules/no-aria-unsupported-elements) | Enforce that elements that do not support ARIA roles, states, and properties do not have those attributes. | |
## 🔧 ESLint Rules
ESLint provides static analysis focused on identifying potential errors and enforcing coding standards.
### @typescript-eslint
Rules in this category enforce TypeScript-specific best practices and type safety.
| Rule | Description | Options |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------- |
| [`await-thenable`](https://typescript-eslint.io/rules/await-thenable) | Disallow awaiting a value that is not a Thenable | |
| [`ban-ts-comment`](https://typescript-eslint.io/rules/ban-ts-comment) | Disallow `@ts-<directive>` comments or require descriptions after directives | {"minimumDescriptionLength":10} |
| [`consistent-type-imports`](https://typescript-eslint.io/rules/consistent-type-imports) | Enforce consistent usage of type imports | [] |The Problem Rulens Solves
When working with AI coding assistants, ensuring high-quality code that matches your project standards is crucial. Before Rulens, developers had three main approaches:
- Manually updating custom AI instructions (like
.cursorrules) - time-consuming and error-prone - Relying on type definitions - helpful but limited for style rules
- Using linting tools - creates a slow feedback cycle of code generation → linting → correction
The ideal workflow would have AI understand your rules before generating code. This is exactly what Rulens enables.
How Rulens Works
The process is remarkably simple:
- Run
npx rulens generatein your project root - This creates a
docs/lint-rules.mdfile containing all linting rules with descriptions - Add an instruction to your AI assistant:
IMPORTANT: Read coding guidelines in docs/lint-rules.md before beginning code work
That's it! Your AI assistant now understands your linting rules before writing any code.
See also docs/lint-rules.md and CLAUDE.md in the rulens project.
A Real-World Success Story: Reducing vi.mock Usage
My personal experience using Claude 3.7 Sonnet and Claude Code demonstrated Rulens' effectiveness. One specific challenge I faced was with test code generation. Claude would frequently use vi.mock extensively in Vitest tests, which reduced function purity and created overly broad test scopes.
While I could configure ESLint with eslint-plugin-vitest's no-restricted-vi-methods rule to prohibit vi.mock, applying this after code generation was problematic. AI assistants struggled to refactor existing test code with deeply embedded mocking patterns.
By generating coding guidelines with Rulens and instructing Claude to read them beforehand, the AI almost completely stopped using vi.mock in generated test code, instead creating tests with better scoping and higher function purity from the start.
Future Directions
Rulens currently supports Biome and ESLint rules, with plans to expand to other linting tools. Some potential improvements include:
- Support for additional linting tools (Prettier, Stylelint)
- Rule prioritization and categorization options
- Custom templates for different documentation formats
- Integration with more AI coding platforms
Conclusion
Rulens bridges the gap between your linting configurations and AI coding assistants, ensuring that AI-generated code meets your project's standards from the start. This simple but powerful tool streamlines the development process by teaching your AI assistant about your coding standards upfront, reducing rework and maintaining consistent code quality.
Rulens reduces the need to write coding guidelines. And it helps you get production-ready code from your AI assistants on the first try.
If you like rulens, I’d love your support—please give our repository a ⭐️ on GitHub! I'm also waiting for issues and pull requests.